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

On Sun, 10 Dec 2006, Josef Weidendorfer wrote:

Very nice.

On Saturday 09 December 2006 06:48, Junio C Hamano wrote:

quoted

 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".

quoted

+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.