manpages: italicize git command names (which were in teletype font)
[git/git.git] / Documentation / git-commit.txt
CommitLineData
215a7ad1
JH
1git-commit(1)
2=============
62033318
JH
3
4NAME
5----
c3f0baac 6git-commit - Record changes to the repository
62033318
JH
7
8SYNOPSIS
9--------
353ce815 10[verse]
b1889c36 11'git commit' [-a | --interactive] [-s] [-v] [-u<mode>] [--amend]
c4a7ff52
SB
12 [(-c | -C) <commit>] [-F <file> | -m <msg>]
13 [--allow-empty] [--no-verify] [-e] [--author=<author>]
5f065737 14 [--cleanup=<mode>] [--] [[-i | -o ]<file>...]
62033318
JH
15
16DESCRIPTION
17-----------
d69806d1
JN
18Stores the current contents of the index in a new commit along
19with a log message from the user describing the changes.
62033318 20
a76c2acb 21The content to be added can be specified in several ways:
f9935bf9 22
ba020ef5 231. by using 'git-add' to incrementally "add" changes to the
a76c2acb 24 index before using the 'commit' command (Note: even modified
6c96753d 25 files must be "added");
5bfc4f23 26
ba020ef5 272. by using 'git-rm' to remove files from the working tree
a76c2acb 28 and the index, again before using the 'commit' command;
6c96753d 29
a76c2acb
BF
303. by listing files as arguments to the 'commit' command, in which
31 case the commit will ignore changes staged in the index, and instead
32 record the current content of the listed files;
6c96753d 33
a76c2acb
BF
344. by using the -a switch with the 'commit' command to automatically
35 "add" changes from all known files (i.e. all files that are already
36 listed in the index) and to automatically "rm" files in the index
37 that have been removed from the working tree, and then perform the
38 actual commit;
6c96753d 39
6cbf07ef
PB
405. by using the --interactive switch with the 'commit' command to decide one
41 by one which files should be part of the commit, before finalizing the
ba020ef5 42 operation. Currently, this is done by invoking 'git-add --interactive'.
6cbf07ef 43
ba020ef5 44The 'git-status' command can be used to obtain a
6c96753d
JH
45summary of what is included by any of the above for the next
46commit by giving the same set of parameters you would give to
47this command.
48
483bc4f0 49If you make a commit and then find a mistake immediately after
ba020ef5 50that, you can recover from it with 'git-reset'.
5bfc4f23 51
6d35cc76 52
62033318
JH
53OPTIONS
54-------
3240240f
SB
55-a::
56--all::
6c96753d
JH
57 Tell the command to automatically stage files that have
58 been modified and deleted, but new files you have not
59 told git about are not affected.
62033318 60
3240240f
SB
61-C <commit>::
62--reuse-message=<commit>::
bc47c29e 63 Take an existing commit object, and reuse the log message
62033318 64 and the authorship information (including the timestamp)
bc47c29e 65 when creating the commit.
62033318 66
3240240f
SB
67-c <commit>::
68--reedit-message=<commit>::
bc47c29e
SB
69 Like '-C', but with '-c' the editor is invoked, so that
70 the user can further edit the commit message.
71
3240240f
SB
72-F <file>::
73--file=<file>::
62033318
JH
74 Take the commit message from the given file. Use '-' to
75 read the message from the standard input.
76
c4a7ff52 77--author=<author>::
130fcca6
JH
78 Override the author name used in the commit. Use
79 `A U Thor <author@example.com>` format.
80
3240240f
SB
81-m <msg>::
82--message=<msg>::
62033318
JH
83 Use the given <msg> as the commit message.
84
3240240f
SB
85-t <file>::
86--template=<file>::
d1cc130a
SG
87 Use the contents of the given file as the initial version
88 of the commit message. The editor is invoked and you can
89 make subsequent changes. If a message is specified using
383e45ce
BG
90 the `-m` or `-F` options, this option has no effect. This
91 overrides the `commit.template` configuration variable.
d1cc130a 92
3240240f
SB
93-s::
94--signoff::
3f971fc4
JH
95 Add Signed-off-by line at the end of the commit message.
96
3240240f
SB
97-n::
98--no-verify::
aa6da6cd 99 This option bypasses the pre-commit and commit-msg hooks.
6998e4db 100 See also linkgit:githooks[5].
eaa54efc 101
36863af1
JH
102--allow-empty::
103 Usually recording a commit that has the exact same tree as its
17ef10d0
JH
104 sole parent commit is a mistake, and the command prevents you
105 from making such a commit. This option bypasses the safety, and
106 is primarily for use by foreign scm interface scripts.
36863af1 107
5f065737
AR
108--cleanup=<mode>::
109 This option sets how the commit message is cleaned up.
110 The '<mode>' can be one of 'verbatim', 'whitespace', 'strip',
111 and 'default'. The 'default' mode will strip leading and
112 trailing empty lines and #commentary from the commit message
113 only if the message is to be edited. Otherwise only whitespace
114 removed. The 'verbatim' mode does not change message at all,
115 'whitespace' removes just leading/trailing whitespace lines
116 and 'strip' removes both whitespace and commentary.
117
3240240f
SB
118-e::
119--edit::
6d35cc76
JH
120 The message taken from file with `-F`, command line with
121 `-m`, and from file with `-C` are usually used as the
122 commit log message unmodified. This option lets you
123 further edit the message taken from these sources.
124
ae5d8470 125--amend::
ae5d8470
MR
126 Used to amend the tip of the current branch. Prepare the tree
127 object you would want to replace the latest commit as usual
128 (this includes the usual -i/-o and explicit paths), and the
129 commit log editor is seeded with the commit message from the
130 tip of the current branch. The commit you create replaces the
131 current tip -- if it was a merge, it will have the parents of
132 the current tip as parents -- so the current top commit is
133 discarded.
134+
6cbd5d7d 135--
ae5d8470 136It is a rough equivalent for:
6cbd5d7d 137------
ae5d8470
MR
138 $ git reset --soft HEAD^
139 $ ... do something else to come up with the right tree ...
140 $ git commit -c ORIG_HEAD
6cbd5d7d
FD
141
142------
ae5d8470 143but can be used to amend a merge commit.
6cbd5d7d 144--
ae5d8470 145
3240240f
SB
146-i::
147--include::
6c96753d
JH
148 Before making a commit out of staged contents so far,
149 stage the contents of paths given on the command line
150 as well. This is usually not what you want unless you
151 are concluding a conflicted merge.
62033318 152
3240240f
SB
153-o::
154--only::
d4ba07ca
JS
155 Make a commit only from the paths specified on the
156 command line, disregarding any contents that have been
157 staged so far. This is the default mode of operation of
467c0197 158 'git-commit' if any paths are given on the command line,
d4ba07ca
JS
159 in which case this option can be omitted.
160 If this option is specified together with '--amend', then
161 no paths need be specified, which can be used to amend
162 the last commit without committing changes that have
163 already been staged.
164
1947bdbc
JH
165-u[<mode>]::
166--untracked-files[=<mode>]::
4bfee30a
MSO
167 Show untracked files (Default: 'all').
168+
169The mode parameter is optional, and is used to specify
170the handling of untracked files. The possible options are:
171+
172--
6c2ce048 173 - 'no' - Show no untracked files
4bfee30a
MSO
174 - 'normal' - Shows untracked files and directories
175 - 'all' - Also shows individual files in untracked directories.
176--
d6293d1f
MSO
177+
178See linkgit:git-config[1] for configuration variable
179used to change the default for when the option is not
180specified.
af83bed6 181
3240240f
SB
182-v::
183--verbose::
af83bed6
JN
184 Show unified diff between the HEAD commit and what
185 would be committed at the bottom of the commit message
186 template. Note that this diff output doesn't have its
187 lines prefixed with '#'.
188
3240240f
SB
189-q::
190--quiet::
23bfbb81 191 Suppress commit summary message.
ebd124c6 192
e994004f 193\--::
4170a195
JH
194 Do not interpret any more arguments as options.
195
196<file>...::
6c96753d
JH
197 When files are given on the command line, the command
198 commits the contents of the named files, without
199 recording the changes already staged. The contents of
200 these files are also staged for the next commit on top
201 of what have been staged before.
3ae854c3
JH
202
203
6c96753d
JH
204EXAMPLES
205--------
206When recording your own work, the contents of modified files in
207your working tree are temporarily stored to a staging area
ba020ef5 208called the "index" with 'git-add'. A file can be
97e9a221 209reverted back, only in the index but not in the working tree,
b1889c36 210to that of the last commit with `git reset HEAD -- <file>`,
ba020ef5 211which effectively reverts 'git-add' and prevents the changes to
97e9a221
JX
212this file from participating in the next commit. After building
213the state to be committed incrementally with these commands,
214`git commit` (without any pathname parameter) is used to record what
6c96753d
JH
215has been staged so far. This is the most basic form of the
216command. An example:
217
218------------
219$ edit hello.c
220$ git rm goodbye.c
221$ git add hello.c
222$ git commit
223------------
224
6c96753d
JH
225Instead of staging files after each individual change, you can
226tell `git commit` to notice the changes to the files whose
227contents are tracked in
228your working tree and do corresponding `git add` and `git rm`
229for you. That is, this example does the same as the earlier
230example if there is no other change in your working tree:
231
232------------
233$ edit hello.c
234$ rm goodbye.c
235$ git commit -a
236------------
237
238The command `git commit -a` first looks at your working tree,
239notices that you have modified hello.c and removed goodbye.c,
240and performs necessary `git add` and `git rm` for you.
241
242After staging changes to many files, you can alter the order the
243changes are recorded in, by giving pathnames to `git commit`.
244When pathnames are given, the command makes a commit that
245only records the changes made to the named paths:
246
247------------
248$ edit hello.c hello.h
249$ git add hello.c hello.h
250$ edit Makefile
251$ git commit Makefile
252------------
253
254This makes a commit that records the modification to `Makefile`.
255The changes staged for `hello.c` and `hello.h` are not included
256in the resulting commit. However, their changes are not lost --
257they are still staged and merely held back. After the above
258sequence, if you do:
259
260------------
261$ git commit
262------------
263
264this second commit would record the changes to `hello.c` and
265`hello.h` as expected.
266
ba020ef5 267After a merge (initiated by 'git-merge' or 'git-pull') stops
483bc4f0 268because of conflicts, cleanly merged
6c96753d
JH
269paths are already staged to be committed for you, and paths that
270conflicted are left in unmerged state. You would have to first
ba020ef5 271check which paths are conflicting with 'git-status'
6c96753d 272and after fixing them manually in your working tree, you would
ba020ef5 273stage the result as usual with 'git-add':
6c96753d
JH
274
275------------
276$ git status | grep unmerged
277unmerged: hello.c
278$ edit hello.c
279$ git add hello.c
280------------
281
282After resolving conflicts and staging the result, `git ls-files -u`
283would stop mentioning the conflicted path. When you are done,
284run `git commit` to finally record the merge:
285
286------------
287$ git commit
288------------
289
290As with the case to record your own changes, you can use `-a`
291option to save typing. One difference is that during a merge
292resolution, you cannot use `git commit` with pathnames to
293alter the order the changes are committed, because the merge
294should be recorded as a single commit. In fact, the command
295refuses to run when given pathnames (but see `-i` option).
296
297
5dc7bcc2
JH
298DISCUSSION
299----------
300
936f32d3
JH
301Though not required, it's a good idea to begin the commit message
302with a single short (less than 50 character) line summarizing the
303change, followed by a blank line and then a more thorough description.
304Tools that turn commits into email, for example, use the first line
305on the Subject: line and the rest of the commit in the body.
306
5dc7bcc2
JH
307include::i18n.txt[]
308
ef0c2abf
AR
309ENVIRONMENT AND CONFIGURATION VARIABLES
310---------------------------------------
311The editor used to edit the commit log message will be chosen from the
312GIT_EDITOR environment variable, the core.editor configuration variable, the
313VISUAL environment variable, or the EDITOR environment variable (in that
314order).
6c96753d
JH
315
316HOOKS
317-----
8089c85b 318This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`,
6998e4db 319and `post-commit` hooks. See linkgit:githooks[5] for more
6c96753d 320information.
130fcca6 321
130fcca6 322
6c96753d
JH
323SEE ALSO
324--------
5162e697
DM
325linkgit:git-add[1],
326linkgit:git-rm[1],
327linkgit:git-mv[1],
328linkgit:git-merge[1],
329linkgit:git-commit-tree[1]
130fcca6 330
62033318
JH
331Author
332------
3f971fc4
JH
333Written by Linus Torvalds <torvalds@osdl.org> and
334Junio C Hamano <junkio@cox.net>
335
62033318
JH
336
337GIT
338---
9e1f0a85 339Part of the linkgit:git[1] suite