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

[Junio C Hamano <junkio@cox.net>]

Nicolas Pitre <nico@cam.org> writes:

>> +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,...IMHO the merge 
> example included further down should be sufficient information wrt 
> committing a merge.

You are right --- removed.

>>  -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)?

True, although the description of <files>... need to be
clarified if we do this.

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

Credit owed to JBF.

> I'd add (with links):
>
> SEE ALSO
> --------
> git-add, git-rm, git-mv, git-merge, git-commit-tree

Done.

Attached is an incremental patch on top of what you commented
on.

-- >8 --

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 8fe42cb..20a2cb3 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -34,12 +34,6 @@ methods:
    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.
-
 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
@@ -119,19 +113,15 @@ but can be used to amend a merge commit.
 	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 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.
-
 \--::
 	Do not interpret any more arguments as options.
 
 <file>...::
-	Files to be committed.  The meaning of these is
-	different between `--include` and `--only`.  Without
-	either, it defaults `--only` semantics.
+	When files are given on the command line, the command
+	commits the contents of the named files, without
+	recording the changes already staged.  The contents of
+	these files are also staged for the next commit on top
+	of what have been staged before.
 
 
 EXAMPLES
@@ -240,6 +230,15 @@ This command can run `commit-msg`, `pre-commit`, and
 `post-commit` hooks.  See link:hooks.html[hooks] for more
 information.
 
+
+SEE ALSO
+--------
+gitlink:git-add[1],
+gitlink:git-rm[1],
+gitlink:git-mv[1],
+gitlink:git-merge[1],
+gitlink:git-commit-tree[1]
+
 Author
 ------
 Written by Linus Torvalds <torvalds@osdl.org> and