Re: [PATCH] Documentation/git-commit: rewrite to make it more end-user friendly.

[Nicolas Pitre <nico@cam.org>]

On Sun, 10 Dec 2006, Josef Weidendorfer wrote:

> Very nice.
> 
> On Saturday 09 December 2006 06:48, Junio C Hamano wrote:
> >  DESCRIPTION
> >  -----------
> > -Updates the index file for given paths, or all modified files if
> > -'-a' is specified, and makes a commit object.  The command specified
> > -by either the VISUAL or EDITOR environment variables are used to edit
> > -the commit log message.
> > +Use 'git commit' when you want to record your changes into the repository
> > +along with a log message describing what the commit is about. All changes
> > +to be committed must be explicitly identified using one of the following
> 
> What about: "... must be explicitly identified (that is,
> must be "staged") ..."
> 
> This way, it will be clear for the reader that "to explicitly identify" is the
> same thing as "to stage", which is used quite often later.

Hmmm, maybe, maybe not.  Although I don't have particular problem with 
"staging area", I'm still unconvinced about the verb "stage".

> > +methods:
> >  
> > -Several environment variable are used during commits.  They are
> > -documented in gitlink:git-commit-tree[1].
> > +1. by using gitlink:git-add[1] to incrementally "add" changes to the
> > +   next commit before using the 'commit' command (Note: even modified
> > +   files must be "added");
> 
> Regarding this note: Of course unmodified files do not have to be added ;-)
> 
> What about: "(Note: changes in files already known to git, and even new
> changes done after a previous `git add` for a given file, still must
> be staged again)" 

This is getting too long for what it is worth in this case IMHO.