Re: [PATCH] Documentation/git-add.txt: Explain --patch option in layman terms
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Aug 30, 2009, 20:14 UTC
- Message-ID
- <7vab1hdppb.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <87ocpxb46g.fsf@jondo.cante.net>
Jari Aalto <jari.aalto@cante.net> writes:
Show 17 quoted lines
> Signed-off-by: Jari Aalto <jari.aalto@cante.net> > --- > Documentation/git-add.txt | 10 +++++----- > 1 files changed, 5 insertions(+), 5 deletions(-) > > diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt > index e67b7e8..71990c2 100644 > --- a/Documentation/git-add.txt > +++ b/Documentation/git-add.txt > @@ -67,14 +67,14 @@ OPTIONS > --interactive:: > Add modified contents in the working tree interactively to > the index. Optional path arguments may be supplied to limit > - operation to a subset of the working tree. See ``Interactive > - mode'' for details. > + operation to a subset of the working tree. See section > + ``INTERACTIVE MODE'' for details.
Sorry, the change in this hunk does not make *any* sense to me.
It is not justified with your commit log message, I do not see why you have to shout in all CAPS, and there is no such section in the documentation. But the "Interactive mode" section exists and is referred to by the original.
Show 8 quoted lines
> -p:: > --patch:: > - Similar to Interactive mode but the initial command loop is > - bypassed and the 'patch' subcommand is invoked using each of > - the specified filepatterns before exiting. > + Run interactive patch command for each file on command line. > + See section INTERACTIVE MODE and patch subcommand for more > + information.
I personally think fixing misworded phrase "initial command loop" would be sufficient. It should read "initial command menu". Perhaps like this.
Run ``add --interactive``, but bypass the initial command menu and directly jump to `patch` subcommand. See ``Interactive mode'' for details.
If you assume that the reader is not familiar with "add -i", then the above is not descriptive enough, but "Run interactive patch command" is not an improvement either. We would need a description of "what it is used for" before "how it would look to you" (i.e.. my rewrite shown above).
"What it is used for" would perhaps read like this.
Review the difference between the index and the work tree, and add modified contents to the index interactively by choosing which patch hunks to use.