Re: [RFC/PATCH] Git.pm: discourage casual use
Jonathan Nieder <jrnieder@gmail.com> writes:
> So how about something like this patch, to start?
Ok. We may probably want to reduce the repetition of "easy", though.
Show 23 quoted lines
> 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.
Junio C Hamano <gitster@pobox.com>