X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=Documentation%2Fgit-commit.txt;h=0a7365b9a80ed0d134bccb3fbe4baacc59056423;hb=da2a95b2a86e8b140d6c5413ea4307e395884135;hp=b92cf483152d7d393b20537d5407479aa13fefc1;hpb=eaa54efc619879ef0d0f7b95f5357d8dab86a713;p=git.git

diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index b92cf483..0a7365b9 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -7,7 +7,10 @@ git-commit - Record your changes
 
 SYNOPSIS
 --------
-'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>] [-e] [--] <file>...
+[verse]
+'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>]
+	   [--no-verify] [--amend] [-e] [--author <author>]
+	   [--] [[-i | -o ]<file>...]
 
 DESCRIPTION
 -----------
@@ -16,6 +19,10 @@ Updates the index file for given paths, or all modified files if
 VISUAL and EDITOR environment variables to edit the commit log
 message.
 
+Several environment variable are used during commits.  They are
+documented in gitlink:git-commit-tree[1].
+
+
 This command can run `commit-msg`, `pre-commit`, and
 `post-commit` hooks.  See link:hooks.html[hooks] for more
 information.
@@ -23,7 +30,9 @@ information.
 OPTIONS
 -------
 -a|--all::
-	Update all paths in the index file.
+	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.
 
 -c or -C <commit>::
 	Take existing commit object, and reuse the log message
@@ -36,6 +45,10 @@ OPTIONS
 	Take the commit message from the given file.  Use '-' to
 	read the message from the standard input.
 
+--author <author>::
+	Override the author name used in the commit.  Use
+	`A U Thor <author@example.com>` format.
+
 -m <msg>::
 	Use the given <msg> as the commit message.
 
@@ -59,11 +72,91 @@ OPTIONS
 	commit log message unmodified.  This option lets you
 	further edit the message taken from these sources.
 
+--amend::
+
+	Used to amend the tip of the current branch. Prepare the tree
+	object you would want to replace the latest commit as usual
+	(this includes the usual -i/-o and explicit paths), and the
+	commit log editor is seeded with the commit message from the
+	tip of the current branch. The commit you create replaces the
+	current tip -- if it was a merge, it will have the parents of
+	the current tip as parents -- so the current top commit is
+	discarded.
++
+--
+It is a rough equivalent for:
+------
+	$ git reset --soft HEAD^
+	$ ... do something else to come up with the right tree ...
+	$ git commit -c ORIG_HEAD
+
+------
+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
+	behaviour.
+
+-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.
+
 --::
 	Do not interpret any more arguments as options.
 
 <file>...::
-	Update specified paths in the index file before committing.
+	Files to be committed.  The meaning of these is
+	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.
 
 
 Author