Re: [RFC/PATCH] Git.pm: discourage casual use
From: Junio C Hamano <hidden>
Date: 2016-06-15 22:50:09
Possibly related (same subject, not in this thread)
- 2016-06-15 · [RFC/PATCH] Git.pm: discourage casual use · Jonathan Nieder <hidden>
Jonathan Nieder [off-list ref] writes:
So how about something like this patch, to start?
Ok. We may probably want to reduce the repetition of "easy", though.
quoted hunk
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.