Minor documentation fixup.
[git/git.git] / Documentation / git-commit.txt
CommitLineData
215a7ad1
JH
1git-commit(1)
2=============
62033318
JH
3
4NAME
5----
215a7ad1 6git-commit - Record your changes
62033318
JH
7
8SYNOPSIS
9--------
353ce815 10[verse]
4170a195 11'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>]
ae5d8470
MR
12 [--no-verify] [--amend] [-e] [--author <author>]
13 [--] [[-i | -o ]<file>...]
62033318
JH
14
15DESCRIPTION
16-----------
17Updates the index file for given paths, or all modified files if
c64ea852
RR
18'-a' is specified, and makes a commit object. The command specified
19by either the VISUAL or EDITOR environment variables are used to edit
20the commit log message.
62033318 21
5bfc4f23
JL
22Several environment variable are used during commits. They are
23documented in gitlink:git-commit-tree[1].
24
25
6d35cc76
JH
26This command can run `commit-msg`, `pre-commit`, and
27`post-commit` hooks. See link:hooks.html[hooks] for more
28information.
29
62033318
JH
30OPTIONS
31-------
eaa54efc 32-a|--all::
cb95bf48
JH
33 Update all paths in the index file. This flag notices
34 files that have been modified and deleted, but new files
8278ac2f 35 you have not told git about are not affected.
62033318
JH
36
37-c or -C <commit>::
38 Take existing commit object, and reuse the log message
39 and the authorship information (including the timestamp)
40 when creating the commit. With '-C', the editor is not
41 invoked; with '-c' the user can further edit the commit
42 message.
43
44-F <file>::
45 Take the commit message from the given file. Use '-' to
46 read the message from the standard input.
47
130fcca6
JH
48--author <author>::
49 Override the author name used in the commit. Use
50 `A U Thor <author@example.com>` format.
51
62033318
JH
52-m <msg>::
53 Use the given <msg> as the commit message.
54
eaa54efc 55-s|--signoff::
3f971fc4
JH
56 Add Signed-off-by line at the end of the commit message.
57
eaa54efc 58-v|--verify::
3f971fc4
JH
59 Look for suspicious lines the commit introduces, and
60 abort committing if there is one. The definition of
61 'suspicious lines' is currently the lines that has
62 trailing whitespaces, and the lines whose indentation
63 has a SP character immediately followed by a TAB
eaa54efc 64 character. This is the default.
3f971fc4 65
eaa54efc
NW
66-n|--no-verify::
67 The opposite of `--verify`.
68
69-e|--edit::
6d35cc76
JH
70 The message taken from file with `-F`, command line with
71 `-m`, and from file with `-C` are usually used as the
72 commit log message unmodified. This option lets you
73 further edit the message taken from these sources.
74
ae5d8470
MR
75--amend::
76
77 Used to amend the tip of the current branch. Prepare the tree
78 object you would want to replace the latest commit as usual
79 (this includes the usual -i/-o and explicit paths), and the
80 commit log editor is seeded with the commit message from the
81 tip of the current branch. The commit you create replaces the
82 current tip -- if it was a merge, it will have the parents of
83 the current tip as parents -- so the current top commit is
84 discarded.
85+
6cbd5d7d 86--
ae5d8470 87It is a rough equivalent for:
6cbd5d7d 88------
ae5d8470
MR
89 $ git reset --soft HEAD^
90 $ ... do something else to come up with the right tree ...
91 $ git commit -c ORIG_HEAD
6cbd5d7d
FD
92
93------
ae5d8470 94but can be used to amend a merge commit.
6cbd5d7d 95--
ae5d8470 96
130fcca6
JH
97-i|--include::
98 Instead of committing only the files specified on the
99 command line, update them in the index file and then
100 commit the whole index. This is the traditional
abda1ef5 101 behavior.
130fcca6 102
4170a195 103-o|--only::
130fcca6
JH
104 Commit only the files specified on the command line.
105 This format cannot be used during a merge, nor when the
106 index and the latest commit does not match on the
107 specified paths to avoid confusion.
62033318 108
e994004f 109\--::
4170a195
JH
110 Do not interpret any more arguments as options.
111
112<file>...::
113 Files to be committed. The meaning of these is
114 different between `--include` and `--only`. Without
115 either, it defaults `--only` semantics.
116
3ae854c3
JH
117If you make a commit and then found a mistake immediately after
118that, you can recover from it with gitlink:git-reset[1].
119
120
130fcca6
JH
121Discussion
122----------
123
124`git commit` without _any_ parameter commits the tree structure
125recorded by the current index file. This is a whole-tree commit
126even the command is invoked from a subdirectory.
127
128`git commit --include paths...` is equivalent to
129
130 git update-index --remove paths...
131 git commit
132
133That is, update the specified paths to the index and then commit
134the whole tree.
135
136`git commit paths...` largely bypasses the index file and
137commits only the changes made to the specified paths. It has
138however several safety valves to prevent confusion.
139
140. It refuses to run during a merge (i.e. when
141 `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users
142 that the traditional semantics now needs -i flag.
143
144. It refuses to run if named `paths...` are different in HEAD
145 and the index (ditto about reminding). Added paths are OK.
146 This is because an earlier `git diff` (not `git diff HEAD`)
147 would have shown the differences since the last `git
148 update-index paths...` to the user, and an inexperienced user
149 may mistakenly think that the changes between the index and
150 the HEAD (i.e. earlier changes made before the last `git
151 update-index paths...` was done) are not being committed.
152
153. It reads HEAD commit into a temporary index file, updates the
154 specified `paths...` and makes a commit. At the same time,
155 the real index file is also updated with the same `paths...`.
156
157`git commit --all` updates the index file with _all_ changes to
158the working tree, and makes a whole-tree commit, regardless of
159which subdirectory the command is invoked in.
160
161
62033318
JH
162Author
163------
3f971fc4
JH
164Written by Linus Torvalds <torvalds@osdl.org> and
165Junio C Hamano <junkio@cox.net>
166
62033318
JH
167
168GIT
169---
a7154e91 170Part of the gitlink:git[7] suite