[RFC/PATCH] Git.pm: discourage casual use
From: Jonathan Nieder <hidden>
Date: 2016-06-15 22:50:09
Subsystem:
the rest · Maintainer:
Linus Torvalds
Possibly related (same subject, not in this thread)
- 2016-06-15 · Re: [RFC/PATCH] Git.pm: discourage casual use · Junio C Hamano <hidden>
- 2016-06-15 · Re: [RFC/PATCH] Git.pm: discourage casual use · Jonathan Nieder <hidden>
Git's internal perl interface still does not have a stable API, and meanwhile CPAN has a number of modules to fulfill the need for a perl git interface. The line # Totally unstable API. $VERSION = '0.01'; in the source makes this clear enough, but users who just looked at git-svn.perl and then tried "perldoc Git" would not notice. Add a note to the manual to warn the reader. Inspired-by: Yves Orton [off-list ref] Signed-off-by: Jonathan Nieder <redacted> --- demerphq wrote:
And well the line: # Totally unstable API. $VERSION = '0.01'; STRONGLY suggests that the module should not be used by code outside the Git package itself.
So how about something like this patch, to start?
diff --git a/perl/Git.pm b/perl/Git.pm
index 6cb0dd1..7f6c500 100644
--- a/perl/Git.pm
+++ b/perl/Git.pm@@ -63,12 +63,16 @@ require Exporter; =head1 DESCRIPTION -This module provides Perl scripts easy way to interface the Git version control -system. The modules have an easy and well-tested way to call arbitrary Git +This module provides an easy way to interact with the Git version control +system for Git's internal perl scripts. +The modules have an easy and well-tested way to call arbitrary Git commands; in the future, the interface will also provide specialized methods for doing easily operations which are not totally trivial to do over the generic command interface. +Note: this module should not be used by code outside the Git package itself, +since the API is not stable yet. + While some commands can be executed outside of any context (e.g. 'version' or 'init'), most operations require a repository context, which in practice means getting an instance of the Git object using the repository() constructor.