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

Nicolas Pitre [off-list ref] writes:

quoted

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

quoted

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

quoted

+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

On Sat, 9 Dec 2006, Junio C Hamano wrote:

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

[...]

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

Might something like "When -i is provided however..." be missing in the 
above?  Otherwise it is rather confusing.

Besides that I'm really happy with the result.

On Sat, 9 Dec 2006, Jakub Narebski wrote:

I'm a bit uncomfortable about removing documentation to existing
(if no-op) option. I'd rather it stay.

How about mentioning it at the very end, under a "HYSTERICAL RAISINS" 
header. That way it's documented, and people still know to ignore it.

Junio C Hamano wrote:

Nicolas Pitre [off-list ref] writes:

quoted

quoted

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

I'm a bit uncomfortable about removing documentation to existing
(if no-op) option. I'd rather it stay.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Linus Torvalds wrote:

On Sat, 9 Dec 2006, Jakub Narebski wrote:

quoted

I'm a bit uncomfortable about removing documentation to existing
(if no-op) option. I'd rather it stay.

How about mentioning it at the very end, under a "HYSTERICAL RAISINS" 
header. That way it's documented, and people still know to ignore it.

"HISTORICAL NOTES". Yes, that is good idea.

Although for git-commit the option --only helps to explain what 
"git commit <path>..." does. So perhaps it should stay where it was.
-- 
Jakub Narebski