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

[Nicolas Pitre <nico@cam.org>]

On Fri, 8 Dec 2006, Junio C Hamano wrote:

> 
> Signed-off-by: Junio C Hamano <junkio@cox.net>
> ---
> 
>  * So how about this?

Much better.  Comments below.

> diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
> index 517a86b..8fe42cb 100644
> --- a/Documentation/git-commit.txt
> +++ b/Documentation/git-commit.txt
> @@ -14,25 +14,47 @@ SYNOPSIS
>  
>  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
> +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");
>  
> +2. by using gitlink:git-rm[1] to identify content removal for the next
> +   commit, again before using the 'commit' command;
> +
> +3. by directly listing files containing changes to be committed as arguments
> +   to the 'commit' command, in which cases only those files alone will be
> +   considered for the commit;
> +
> +4. by using the -a switch with the 'commit' command to automatically "add"
> +   changes from all known files i.e. files that have already been committed
> +   before, and perform the actual commit.
> +
> +Note that the contents of the paths that resolved cleanly by a
> +conflicted merge are automatically staged for the next commit;
> +you still need to explicitly identify what you want in the
> +resulting commit using one of the above methods before
> +recording the merge commit.

Like I said in another mail, I really think this formal paragraph 
belongs elsewhere. But if you insist for keeping it here, at least it 
should be moved after mention of git-reset below.  But IMHO the merge 
example included further down should be sufficient information wrt 
committing a merge.

> +
> +The gitlink:git-status[1] command can be used to obtain a
> +summary of what is included by any of the above for the next
> +commit by giving the same set of parameters you would give to
> +this command.
> +
> +If you make a commit and then found a mistake immediately after
> +that, you can recover from it with gitlink:git-reset[1].
>  
> -This command can run `commit-msg`, `pre-commit`, and
> -`post-commit` hooks.  See link:hooks.html[hooks] for more
> -information.
>  
>  OPTIONS
>  -------
>  -a|--all::
> -	Update all paths in the index file.  This flag notices
> -	files that have been modified and deleted, but new files
> -	you have not told git about are not affected.
> +	Tell the command to automatically stage files that have
> +	been modified and deleted, but new files you have not
> +	told git about are not affected.
>  
>  -c or -C <commit>::
>  	Take existing commit object, and reuse the log message
> @@ -55,16 +77,13 @@ OPTIONS
>  -s|--signoff::
>  	Add Signed-off-by line at the end of the commit message.
>  
> --v|--verify::
> -	Look for suspicious lines the commit introduces, and
> -	abort committing if there is one.  The definition of
> -	'suspicious lines' is currently the lines that has
> -	trailing whitespaces, and the lines whose indentation
> -	has a SP character immediately followed by a TAB
> -	character.  This is the default.
> -
> --n|--no-verify::
> -	The opposite of `--verify`.
> +--no-verify::
> +	By default, the command looks for suspicious lines the
> +	commit introduces, and aborts committing if there is one.
> +	The definition of 'suspicious lines' is currently the
> +	lines that has trailing whitespaces, and the lines whose
> +	indentation has a SP character immediately followed by a
> +	TAB character.  This option turns off the check.
>  
>  -e|--edit::
>  	The message taken from file with `-F`, command line with
> @@ -95,16 +114,16 @@ but can be used to amend a merge commit.
>  --
>  
>  -i|--include::
> -	Instead of committing only the files specified on the
> -	command line, update them in the index file and then
> -	commit the whole index.  This is the traditional
> -	behavior.
> +	Before making a commit out of staged contents so far,
> +	stage the contents of paths given on the command line
> +	as well.  This is usually not what you want unless you
> +	are concluding a conflicted merge.
>  
>  -o|--only::
> -	Commit only the files specified on the command line.
> -	This format cannot be used during a merge, nor when the
> -	index and the latest commit does not match on the
> -	specified paths to avoid confusion.
> +	Commit only the files specified on the command line;
> +	this is the default when pathnames are given on the
> +	command line, so you usually do not have to give this
> +	option.  This format cannot be used during a merge.

Is there some value in keeping this option documented?  What about 
removing it (the documentation not the option)?

>  \--::
>  	Do not interpret any more arguments as options.
> @@ -114,50 +133,112 @@ but can be used to amend a merge commit.
>  	different between `--include` and `--only`.  Without
>  	either, it defaults `--only` semantics.
>  
> -If you make a commit and then found a mistake immediately after
> -that, you can recover from it with gitlink:git-reset[1].
> -
> -
> -Discussion
> -----------
> -
> -`git commit` without _any_ parameter commits the tree structure
> -recorded by the current index file.  This is a whole-tree commit
> -even the command is invoked from a subdirectory.
> -
> -`git commit --include paths...` is equivalent to
> -
> -	git update-index --remove paths...
> -	git commit
> -
> -That is, update the specified paths to the index and then commit
> -the whole tree.
> -
> -`git commit paths...` largely bypasses the index file and
> -commits only the changes made to the specified paths.  It has
> -however several safety valves to prevent confusion.
> -
> -. It refuses to run during a merge (i.e. when
> -  `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users
> -  that the traditional semantics now needs -i flag.
> -
> -. It refuses to run if named `paths...` are different in HEAD
> -  and the index (ditto about reminding).  Added paths are OK.
> -  This is because an earlier `git diff` (not `git diff HEAD`)
> -  would have shown the differences since the last `git
> -  update-index paths...` to the user, and an inexperienced user
> -  may mistakenly think that the changes between the index and
> -  the HEAD (i.e. earlier changes made before the last `git
> -  update-index paths...` was done) are not being committed.
> -
> -. It reads HEAD commit into a temporary index file, updates the
> -  specified `paths...` and makes a commit.  At the same time,
> -  the real index file is also updated with the same `paths...`.
> -
> -`git commit --all` updates the index file with _all_ changes to
> -the working tree, and makes a whole-tree commit, regardless of
> -which subdirectory the command is invoked in.
>  
> +EXAMPLES
> +--------
> +When recording your own work, the contents of modified files in
> +your working tree are temporarily stored to a staging area
> +called the "index" with gitlink:git-add[1].  Removal

I like the way the index is introduced at this point.

> +of a file is staged with gitlink:git-rm[1].  After building the
> +state to be committed incrementally with these commands, `git
> +commit` (without any pathname parameter) is used to record what
> +has been staged so far.  This is the most basic form of the
> +command.  An example:
> +
> +------------
> +$ edit hello.c
> +$ git rm goodbye.c
> +$ git add hello.c
> +$ git commit
> +------------
> +
> +////////////
> +We should fix 'git rm' to remove goodbye.c from both index and
> +working tree for the above example.
> +////////////
> +
> +Instead of staging files after each individual change, you can
> +tell `git commit` to notice the changes to the tracked files in
> +your working tree and do corresponding `git add` and `git rm`
> +for you.  That is, this example does the same as the earlier
> +example if there is no other change in your working tree:
> +
> +------------
> +$ edit hello.c
> +$ rm goodbye.c
> +$ git commit -a
> +------------
> +
> +The command `git commit -a` first looks at your working tree,
> +notices that you have modified hello.c and removed goodbye.c,
> +and performs necessary `git add` and `git rm` for you.
> +
> +After staging changes to many files, you can alter the order the
> +changes are recorded in, by giving pathnames to `git commit`.
> +When pathnames are given, the command makes a commit that
> +only records the changes made to the named paths:
> +
> +------------
> +$ edit hello.c hello.h
> +$ git add hello.c hello.h
> +$ edit Makefile
> +$ git commit Makefile
> +------------
> +
> +This makes a commit that records the modification to `Makefile`.
> +The changes staged for `hello.c` and `hello.h` are not included
> +in the resulting commit.  However, their changes are not lost --
> +they are still staged and merely held back.  After the above
> +sequence, if you do:
> +
> +------------
> +$ git commit
> +------------
> +
> +this second commit would record the changes to `hello.c` and
> +`hello.h` as expected.
> +
> +After a merge (initiated by either gitlink:git-merge[1] or
> +gitlink:git-pull[1]) stops because of conflicts, cleanly merged
> +paths are already staged to be committed for you, and paths that
> +conflicted are left in unmerged state.  You would have to first
> +check which paths are conflicting with gitlink:git-status[1]
> +and after fixing them manually in your working tree, you would
> +stage the result as usual with gitlink:git-add[1]:
> +
> +------------
> +$ git status | grep unmerged
> +unmerged: hello.c
> +$ edit hello.c
> +$ git add hello.c
> +------------
> +
> +After resolving conflicts and staging the result, `git ls-files -u`
> +would stop mentioning the conflicted path.  When you are done,
> +run `git commit` to finally record the merge:
> +
> +------------
> +$ git commit
> +------------
> +
> +As with the case to record your own changes, you can use `-a`
> +option to save typing.  One difference is that during a merge
> +resolution, you cannot use `git commit` with pathnames to
> +alter the order the changes are committed, because the merge
> +should be recorded as a single commit.  In fact, the command
> +refuses to run when given pathnames (but see `-i` option).
> +
> +
> +ENVIRONMENT VARIABLES
> +---------------------
> +The command specified by either the VISUAL or EDITOR environment
> +variables is used to edit the commit log message.
> +
> +HOOKS
> +-----
> +This command can run `commit-msg`, `pre-commit`, and
> +`post-commit` hooks.  See link:hooks.html[hooks] for more
> +information.

I'd add (with links):

SEE ALSO
--------
git-add, git-rm, git-mv, git-merge, git-commit-tree

Otherwise very good.