Thread (5 messages) flat view 5 messages, 4 authors, 2016-08-11

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

From: Junio C Hamano <hidden>
Date: 2016-08-11 19:22:21
Subsystem: documentation, the rest · Maintainers: Jonathan Corbet, Linus Torvalds

Possibly related (same subject, not in this thread)

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
Keyboard shortcuts
hback out one level
jnext message in thread
kprevious message in thread
ldrill in
Escclose help / fold thread tree
?toggle this help