--------
[verse]
'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>]
- [-e] [--author <author>] [--] [[-i | -o ]<file>...]
+ [--no-verify] [--amend] [-e] [--author <author>]
+ [--] [[-i | -o ]<file>...]
DESCRIPTION
-----------
-Updates the index file for given paths, or all modified files if
-'-a' is specified, and makes a commit object. The command
-VISUAL and EDITOR environment variables 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:
+
+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.
+
+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
-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
commit log message unmodified. This option lets you
further edit the message taken from these sources.
--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>...::
- 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].
+--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.
+--
-Discussion
-----------
+-i|--include::
+ 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.
-`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.
+-q|--quiet::
+ Supress commit summary message.
-`git commit --include paths...` is equivalent to
+\--::
+ Do not interpret any more arguments as options.
- git update-index --remove paths...
- git commit
+<file>...::
+ 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.
-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.
+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
+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 files whose
+contents are tracked 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).
+
+
+DISCUSSION
+----------
-. 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.
+include::i18n.txt[]
-. 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.
+ENVIRONMENT VARIABLES
+---------------------
+The command specified by either the VISUAL or EDITOR environment
+variables is used to edit the commit log message.
-. 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...`.
+HOOKS
+-----
+This command can run `commit-msg`, `pre-commit`, and
+`post-commit` hooks. See link:hooks.html[hooks] for more
+information.
-`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.
+SEE ALSO
+--------
+gitlink:git-add[1],
+gitlink:git-rm[1],
+gitlink:git-mv[1],
+gitlink:git-merge[1],
+gitlink:git-commit-tree[1]
Author
------