git-commit: document log message formatting convention
[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-----------
6c96753d
JH
17Use 'git commit' when you want to record your changes into the repository
18along with a log message describing what the commit is about. All changes
19to be committed must be explicitly identified using one of the following
20methods:
62033318 21
6c96753d
JH
221. by using gitlink:git-add[1] to incrementally "add" changes to the
23 next commit before using the 'commit' command (Note: even modified
24 files must be "added");
5bfc4f23 25
6c96753d
JH
262. by using gitlink:git-rm[1] to identify content removal for the next
27 commit, again before using the 'commit' command;
28
293. by directly listing files containing changes to be committed as arguments
30 to the 'commit' command, in which cases only those files alone will be
31 considered for the commit;
32
334. by using the -a switch with the 'commit' command to automatically "add"
34 changes from all known files i.e. files that have already been committed
696b1b50
JH
35 before, and to automatically "rm" files that have been
36 removed from the working tree, and perform the actual commit.
6c96753d
JH
37
38The gitlink:git-status[1] command can be used to obtain a
39summary of what is included by any of the above for the next
40commit by giving the same set of parameters you would give to
41this command.
42
43If you make a commit and then found a mistake immediately after
44that, you can recover from it with gitlink:git-reset[1].
5bfc4f23 45
6d35cc76 46
62033318
JH
47OPTIONS
48-------
eaa54efc 49-a|--all::
6c96753d
JH
50 Tell the command to automatically stage files that have
51 been modified and deleted, but new files you have not
52 told git about are not affected.
62033318
JH
53
54-c or -C <commit>::
55 Take existing commit object, and reuse the log message
56 and the authorship information (including the timestamp)
57 when creating the commit. With '-C', the editor is not
58 invoked; with '-c' the user can further edit the commit
59 message.
60
61-F <file>::
62 Take the commit message from the given file. Use '-' to
63 read the message from the standard input.
64
130fcca6
JH
65--author <author>::
66 Override the author name used in the commit. Use
67 `A U Thor <author@example.com>` format.
68
62033318
JH
69-m <msg>::
70 Use the given <msg> as the commit message.
71
eaa54efc 72-s|--signoff::
3f971fc4
JH
73 Add Signed-off-by line at the end of the commit message.
74
6c96753d 75--no-verify::
fc41be3b
MT
76 This option bypasses the pre-commit hook.
77 See also link:hooks.html[hooks].
eaa54efc
NW
78
79-e|--edit::
6d35cc76
JH
80 The message taken from file with `-F`, command line with
81 `-m`, and from file with `-C` are usually used as the
82 commit log message unmodified. This option lets you
83 further edit the message taken from these sources.
84
ae5d8470
MR
85--amend::
86
87 Used to amend the tip of the current branch. Prepare the tree
88 object you would want to replace the latest commit as usual
89 (this includes the usual -i/-o and explicit paths), and the
90 commit log editor is seeded with the commit message from the
91 tip of the current branch. The commit you create replaces the
92 current tip -- if it was a merge, it will have the parents of
93 the current tip as parents -- so the current top commit is
94 discarded.
95+
6cbd5d7d 96--
ae5d8470 97It is a rough equivalent for:
6cbd5d7d 98------
ae5d8470
MR
99 $ git reset --soft HEAD^
100 $ ... do something else to come up with the right tree ...
101 $ git commit -c ORIG_HEAD
6cbd5d7d
FD
102
103------
ae5d8470 104but can be used to amend a merge commit.
6cbd5d7d 105--
ae5d8470 106
130fcca6 107-i|--include::
6c96753d
JH
108 Before making a commit out of staged contents so far,
109 stage the contents of paths given on the command line
110 as well. This is usually not what you want unless you
111 are concluding a conflicted merge.
62033318 112
ebd124c6
NP
113-q|--quiet::
114 Supress commit summary message.
115
e994004f 116\--::
4170a195
JH
117 Do not interpret any more arguments as options.
118
119<file>...::
6c96753d
JH
120 When files are given on the command line, the command
121 commits the contents of the named files, without
122 recording the changes already staged. The contents of
123 these files are also staged for the next commit on top
124 of what have been staged before.
3ae854c3
JH
125
126
6c96753d
JH
127EXAMPLES
128--------
129When recording your own work, the contents of modified files in
130your working tree are temporarily stored to a staging area
131called the "index" with gitlink:git-add[1]. Removal
132of a file is staged with gitlink:git-rm[1]. After building the
133state to be committed incrementally with these commands, `git
134commit` (without any pathname parameter) is used to record what
135has been staged so far. This is the most basic form of the
136command. An example:
137
138------------
139$ edit hello.c
140$ git rm goodbye.c
141$ git add hello.c
142$ git commit
143------------
144
6c96753d
JH
145Instead of staging files after each individual change, you can
146tell `git commit` to notice the changes to the files whose
147contents are tracked in
148your working tree and do corresponding `git add` and `git rm`
149for you. That is, this example does the same as the earlier
150example if there is no other change in your working tree:
151
152------------
153$ edit hello.c
154$ rm goodbye.c
155$ git commit -a
156------------
157
158The command `git commit -a` first looks at your working tree,
159notices that you have modified hello.c and removed goodbye.c,
160and performs necessary `git add` and `git rm` for you.
161
162After staging changes to many files, you can alter the order the
163changes are recorded in, by giving pathnames to `git commit`.
164When pathnames are given, the command makes a commit that
165only records the changes made to the named paths:
166
167------------
168$ edit hello.c hello.h
169$ git add hello.c hello.h
170$ edit Makefile
171$ git commit Makefile
172------------
173
174This makes a commit that records the modification to `Makefile`.
175The changes staged for `hello.c` and `hello.h` are not included
176in the resulting commit. However, their changes are not lost --
177they are still staged and merely held back. After the above
178sequence, if you do:
179
180------------
181$ git commit
182------------
183
184this second commit would record the changes to `hello.c` and
185`hello.h` as expected.
186
187After a merge (initiated by either gitlink:git-merge[1] or
188gitlink:git-pull[1]) stops because of conflicts, cleanly merged
189paths are already staged to be committed for you, and paths that
190conflicted are left in unmerged state. You would have to first
191check which paths are conflicting with gitlink:git-status[1]
192and after fixing them manually in your working tree, you would
193stage the result as usual with gitlink:git-add[1]:
194
195------------
196$ git status | grep unmerged
197unmerged: hello.c
198$ edit hello.c
199$ git add hello.c
200------------
201
202After resolving conflicts and staging the result, `git ls-files -u`
203would stop mentioning the conflicted path. When you are done,
204run `git commit` to finally record the merge:
205
206------------
207$ git commit
208------------
209
210As with the case to record your own changes, you can use `-a`
211option to save typing. One difference is that during a merge
212resolution, you cannot use `git commit` with pathnames to
213alter the order the changes are committed, because the merge
214should be recorded as a single commit. In fact, the command
215refuses to run when given pathnames (but see `-i` option).
216
217
5dc7bcc2
JH
218DISCUSSION
219----------
220
936f32d3
JH
221Though not required, it's a good idea to begin the commit message
222with a single short (less than 50 character) line summarizing the
223change, followed by a blank line and then a more thorough description.
224Tools that turn commits into email, for example, use the first line
225on the Subject: line and the rest of the commit in the body.
226
5dc7bcc2
JH
227include::i18n.txt[]
228
6c96753d
JH
229ENVIRONMENT VARIABLES
230---------------------
231The command specified by either the VISUAL or EDITOR environment
232variables is used to edit the commit log message.
233
234HOOKS
235-----
236This command can run `commit-msg`, `pre-commit`, and
237`post-commit` hooks. See link:hooks.html[hooks] for more
238information.
130fcca6 239
130fcca6 240
6c96753d
JH
241SEE ALSO
242--------
243gitlink:git-add[1],
244gitlink:git-rm[1],
245gitlink:git-mv[1],
246gitlink:git-merge[1],
247gitlink:git-commit-tree[1]
130fcca6 248
62033318
JH
249Author
250------
3f971fc4
JH
251Written by Linus Torvalds <torvalds@osdl.org> and
252Junio C Hamano <junkio@cox.net>
253
62033318
JH
254
255GIT
256---
a7154e91 257Part of the gitlink:git[7] suite