]>
Commit | Line | Data |
---|---|---|
215a7ad1 JH |
1 | git-commit(1) |
2 | ============= | |
62033318 JH |
3 | |
4 | NAME | |
5 | ---- | |
c3f0baac | 6 | git-commit - Record changes to the repository |
62033318 JH |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
353ce815 | 10 | [verse] |
b4bd4668 CI |
11 | 'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend] |
12 | [--dry-run] [(-c | -C | --fixup | --squash) <commit>] | |
13 | [-F <file> | -m <msg>] [--reset-author] [--allow-empty] | |
14 | [--allow-empty-message] [--no-verify] [-e] [--author=<author>] | |
0460ed2c | 15 | [--date=<date>] [--cleanup=<mode>] [--[no-]status] |
098bbdc3 | 16 | [-i | -o] [-S[<keyid>]] [--] [<file>...] |
62033318 JH |
17 | |
18 | DESCRIPTION | |
19 | ----------- | |
d69806d1 JN |
20 | Stores the current contents of the index in a new commit along |
21 | with a log message from the user describing the changes. | |
62033318 | 22 | |
a76c2acb | 23 | The content to be added can be specified in several ways: |
f9935bf9 | 24 | |
0b444cdb | 25 | 1. by using 'git add' to incrementally "add" changes to the |
a76c2acb | 26 | index before using the 'commit' command (Note: even modified |
6c96753d | 27 | files must be "added"); |
5bfc4f23 | 28 | |
0b444cdb | 29 | 2. by using 'git rm' to remove files from the working tree |
a76c2acb | 30 | and the index, again before using the 'commit' command; |
6c96753d | 31 | |
a76c2acb BF |
32 | 3. by listing files as arguments to the 'commit' command, in which |
33 | case the commit will ignore changes staged in the index, and instead | |
6fc4a7e5 | 34 | record the current content of the listed files (which must already |
2de9b711 | 35 | be known to Git); |
6c96753d | 36 | |
a76c2acb BF |
37 | 4. by using the -a switch with the 'commit' command to automatically |
38 | "add" changes from all known files (i.e. all files that are already | |
39 | listed in the index) and to automatically "rm" files in the index | |
40 | that have been removed from the working tree, and then perform the | |
41 | actual commit; | |
6c96753d | 42 | |
b4bd4668 CI |
43 | 5. by using the --interactive or --patch switches with the 'commit' command |
44 | to decide one by one which files or hunks should be part of the commit, | |
6cf378f0 | 45 | before finalizing the operation. See the ``Interactive Mode'' section of |
b4bd4668 | 46 | linkgit:git-add[1] to learn how to operate these modes. |
6cbf07ef | 47 | |
60c2993c | 48 | The `--dry-run` option can be used to obtain a |
6c96753d | 49 | summary of what is included by any of the above for the next |
60c2993c | 50 | commit by giving the same set of parameters (options and paths). |
6c96753d | 51 | |
483bc4f0 | 52 | If you make a commit and then find a mistake immediately after |
0b444cdb | 53 | that, you can recover from it with 'git reset'. |
5bfc4f23 | 54 | |
6d35cc76 | 55 | |
62033318 JH |
56 | OPTIONS |
57 | ------- | |
3240240f SB |
58 | -a:: |
59 | --all:: | |
6c96753d JH |
60 | Tell the command to automatically stage files that have |
61 | been modified and deleted, but new files you have not | |
2de9b711 | 62 | told Git about are not affected. |
62033318 | 63 | |
b4bd4668 CI |
64 | -p:: |
65 | --patch:: | |
66 | Use the interactive patch selection interface to chose | |
67 | which changes to commit. See linkgit:git-add[1] for | |
68 | details. | |
69 | ||
3240240f SB |
70 | -C <commit>:: |
71 | --reuse-message=<commit>:: | |
bc47c29e | 72 | Take an existing commit object, and reuse the log message |
62033318 | 73 | and the authorship information (including the timestamp) |
bc47c29e | 74 | when creating the commit. |
62033318 | 75 | |
3240240f SB |
76 | -c <commit>:: |
77 | --reedit-message=<commit>:: | |
bc47c29e SB |
78 | Like '-C', but with '-c' the editor is invoked, so that |
79 | the user can further edit the commit message. | |
80 | ||
d71b8ba7 PN |
81 | --fixup=<commit>:: |
82 | Construct a commit message for use with `rebase --autosquash`. | |
83 | The commit message will be the subject line from the specified | |
84 | commit with a prefix of "fixup! ". See linkgit:git-rebase[1] | |
85 | for details. | |
86 | ||
89ac1223 PN |
87 | --squash=<commit>:: |
88 | Construct a commit message for use with `rebase --autosquash`. | |
89 | The commit message subject line is taken from the specified | |
90 | commit with a prefix of "squash! ". Can be used with additional | |
91 | commit message options (`-m`/`-c`/`-C`/`-F`). See | |
92 | linkgit:git-rebase[1] for details. | |
93 | ||
c51f6cee | 94 | --reset-author:: |
37f7a857 JS |
95 | When used with -C/-c/--amend options, or when committing after a |
96 | a conflicting cherry-pick, declare that the authorship of the | |
97 | resulting commit now belongs of the committer. This also renews | |
98 | the author timestamp. | |
c51f6cee | 99 | |
7c9f7038 JK |
100 | --short:: |
101 | When doing a dry-run, give the output in the short-format. See | |
102 | linkgit:git-status[1] for details. Implies `--dry-run`. | |
103 | ||
e858af6d RR |
104 | --branch:: |
105 | Show the branch and tracking info even in short-format. | |
106 | ||
7c9f7038 JK |
107 | --porcelain:: |
108 | When doing a dry-run, give the output in a porcelain-ready | |
109 | format. See linkgit:git-status[1] for details. Implies | |
110 | `--dry-run`. | |
111 | ||
f3f47a1e JK |
112 | --long:: |
113 | When doing a dry-run, give the output in a the long-format. | |
114 | Implies `--dry-run`. | |
115 | ||
7c9f7038 | 116 | -z:: |
e858af6d | 117 | --null:: |
7c9f7038 JK |
118 | When showing `short` or `porcelain` status output, terminate |
119 | entries in the status output with NUL, instead of LF. If no | |
120 | format is given, implies the `--porcelain` output format. | |
121 | ||
3240240f SB |
122 | -F <file>:: |
123 | --file=<file>:: | |
62033318 JH |
124 | Take the commit message from the given file. Use '-' to |
125 | read the message from the standard input. | |
126 | ||
c4a7ff52 | 127 | --author=<author>:: |
3334729c JS |
128 | Override the commit author. Specify an explicit author using the |
129 | standard `A U Thor <author@example.com>` format. Otherwise <author> | |
130 | is assumed to be a pattern and is used to search for an existing | |
131 | commit by that author (i.e. rev-list --all -i --author=<author>); | |
132 | the commit author is then copied from the first such commit found. | |
130fcca6 | 133 | |
02b47cd7 MV |
134 | --date=<date>:: |
135 | Override the author date used in the commit. | |
136 | ||
3240240f SB |
137 | -m <msg>:: |
138 | --message=<msg>:: | |
62033318 | 139 | Use the given <msg> as the commit message. |
6bf6366c CH |
140 | If multiple `-m` options are given, their values are |
141 | concatenated as separate paragraphs. | |
62033318 | 142 | |
3240240f SB |
143 | -t <file>:: |
144 | --template=<file>:: | |
1f08c2c8 JH |
145 | When editing the commit message, start the editor with the |
146 | contents in the given file. The `commit.template` configuration | |
147 | variable is often used to give this option implicitly to the | |
148 | command. This mechanism can be used by projects that want to | |
149 | guide participants with some hints on what to write in the message | |
150 | in what order. If the user exits the editor without editing the | |
151 | message, the commit is aborted. This has no effect when a message | |
152 | is given by other means, e.g. with the `-m` or `-F` options. | |
d1cc130a | 153 | |
3240240f SB |
154 | -s:: |
155 | --signoff:: | |
a0178ae2 | 156 | Add Signed-off-by line by the committer at the end of the commit |
09cff066 | 157 | log message. |
3f971fc4 | 158 | |
3240240f SB |
159 | -n:: |
160 | --no-verify:: | |
aa6da6cd | 161 | This option bypasses the pre-commit and commit-msg hooks. |
6998e4db | 162 | See also linkgit:githooks[5]. |
eaa54efc | 163 | |
36863af1 JH |
164 | --allow-empty:: |
165 | Usually recording a commit that has the exact same tree as its | |
17ef10d0 JH |
166 | sole parent commit is a mistake, and the command prevents you |
167 | from making such a commit. This option bypasses the safety, and | |
6b677a28 | 168 | is primarily for use by foreign SCM interface scripts. |
36863af1 | 169 | |
c9b5fde7 ÆAB |
170 | --allow-empty-message:: |
171 | Like --allow-empty this command is primarily for use by foreign | |
6b677a28 | 172 | SCM interface scripts. It allows you to create a commit with an |
c9b5fde7 ÆAB |
173 | empty commit message without using plumbing commands like |
174 | linkgit:git-commit-tree[1]. | |
175 | ||
5f065737 | 176 | --cleanup=<mode>:: |
46fbf753 BC |
177 | This option determines how the supplied commit message should be |
178 | cleaned up before committing. The '<mode>' can be `strip`, | |
179 | `whitespace`, `verbatim`, or `default`. | |
180 | + | |
181 | -- | |
182 | strip:: | |
183 | Strip leading and trailing empty lines, trailing whitespace, and | |
184 | #commentary and collapse consecutive empty lines. | |
185 | whitespace:: | |
186 | Same as `strip` except #commentary is not removed. | |
187 | verbatim:: | |
188 | Do not change the message at all. | |
189 | default:: | |
190 | Same as `strip` if the message is to be edited. | |
191 | Otherwise `whitespace`. | |
192 | -- | |
193 | + | |
194 | The default can be changed by the 'commit.cleanup' configuration | |
195 | variable (see linkgit:git-config[1]). | |
5f065737 | 196 | |
3240240f SB |
197 | -e:: |
198 | --edit:: | |
6d35cc76 | 199 | The message taken from file with `-F`, command line with |
9a3e36cd AGB |
200 | `-m`, and from commit object with `-C` are usually used as |
201 | the commit log message unmodified. This option lets you | |
6d35cc76 JH |
202 | further edit the message taken from these sources. |
203 | ||
ae45320c MM |
204 | --no-edit:: |
205 | Use the selected commit message without launching an editor. | |
206 | For example, `git commit --amend --no-edit` amends a commit | |
207 | without changing its commit message. | |
208 | ||
ae5d8470 | 209 | --amend:: |
aa7b8c65 CMN |
210 | Replace the tip of the current branch by creating a new |
211 | commit. The recorded tree is prepared as usual (including | |
212 | the effect of the `-i` and `-o` options and explicit | |
213 | pathspec), and the message from the original commit is used | |
214 | as the starting point, instead of an empty message, when no | |
215 | other message is specified from the command line via options | |
216 | such as `-m`, `-F`, `-c`, etc. The new commit has the same | |
217 | parents and author as the current one (the `--reset-author` | |
218 | option can countermand this). | |
ae5d8470 | 219 | + |
6cbd5d7d | 220 | -- |
ae5d8470 | 221 | It is a rough equivalent for: |
6cbd5d7d | 222 | ------ |
ae5d8470 MR |
223 | $ git reset --soft HEAD^ |
224 | $ ... do something else to come up with the right tree ... | |
225 | $ git commit -c ORIG_HEAD | |
6cbd5d7d FD |
226 | |
227 | ------ | |
ae5d8470 | 228 | but can be used to amend a merge commit. |
6cbd5d7d | 229 | -- |
97c33c65 TR |
230 | + |
231 | You should understand the implications of rewriting history if you | |
232 | amend a commit that has already been published. (See the "RECOVERING | |
233 | FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) | |
ae5d8470 | 234 | |
77effefe AS |
235 | --no-post-rewrite:: |
236 | Bypass the post-rewrite hook. | |
237 | ||
3240240f SB |
238 | -i:: |
239 | --include:: | |
6c96753d JH |
240 | Before making a commit out of staged contents so far, |
241 | stage the contents of paths given on the command line | |
242 | as well. This is usually not what you want unless you | |
243 | are concluding a conflicted merge. | |
62033318 | 244 | |
3240240f SB |
245 | -o:: |
246 | --only:: | |
d4ba07ca JS |
247 | Make a commit only from the paths specified on the |
248 | command line, disregarding any contents that have been | |
249 | staged so far. This is the default mode of operation of | |
0b444cdb | 250 | 'git commit' if any paths are given on the command line, |
d4ba07ca JS |
251 | in which case this option can be omitted. |
252 | If this option is specified together with '--amend', then | |
04c8ce9c | 253 | no paths need to be specified, which can be used to amend |
d4ba07ca JS |
254 | the last commit without committing changes that have |
255 | already been staged. | |
256 | ||
1947bdbc JH |
257 | -u[<mode>]:: |
258 | --untracked-files[=<mode>]:: | |
4cc62606 | 259 | Show untracked files. |
4bfee30a | 260 | + |
4cc62606 CB |
261 | The mode parameter is optional (defaults to 'all'), and is used to |
262 | specify the handling of untracked files; when -u is not used, the | |
263 | default is 'normal', i.e. show untracked files and directories. | |
e9e92198 JH |
264 | + |
265 | The possible options are: | |
4bfee30a | 266 | + |
6c2ce048 | 267 | - 'no' - Show no untracked files |
4bfee30a MSO |
268 | - 'normal' - Shows untracked files and directories |
269 | - 'all' - Also shows individual files in untracked directories. | |
d6293d1f | 270 | + |
4cc62606 CB |
271 | The default can be changed using the status.showUntrackedFiles |
272 | configuration variable documented in linkgit:git-config[1]. | |
af83bed6 | 273 | |
3240240f SB |
274 | -v:: |
275 | --verbose:: | |
af83bed6 JN |
276 | Show unified diff between the HEAD commit and what |
277 | would be committed at the bottom of the commit message | |
278 | template. Note that this diff output doesn't have its | |
279 | lines prefixed with '#'. | |
280 | ||
3240240f SB |
281 | -q:: |
282 | --quiet:: | |
23bfbb81 | 283 | Suppress commit summary message. |
ebd124c6 | 284 | |
3a5d13a3 JH |
285 | --dry-run:: |
286 | Do not create a commit, but show a list of paths that are | |
287 | to be committed, paths with local changes that will be left | |
288 | uncommitted and paths that are untracked. | |
289 | ||
bed575e4 JHI |
290 | --status:: |
291 | Include the output of linkgit:git-status[1] in the commit | |
292 | message template when using an editor to prepare the commit | |
293 | message. Defaults to on, but can be used to override | |
294 | configuration variable commit.status. | |
295 | ||
296 | --no-status:: | |
297 | Do not include the output of linkgit:git-status[1] in the | |
298 | commit message template when using an editor to prepare the | |
299 | default commit message. | |
300 | ||
098bbdc3 TJ |
301 | -S[<keyid>]:: |
302 | --gpg-sign[=<keyid>]:: | |
303 | GPG-sign commit. | |
304 | ||
e994004f | 305 | \--:: |
4170a195 JH |
306 | Do not interpret any more arguments as options. |
307 | ||
308 | <file>...:: | |
6c96753d JH |
309 | When files are given on the command line, the command |
310 | commits the contents of the named files, without | |
311 | recording the changes already staged. The contents of | |
312 | these files are also staged for the next commit on top | |
313 | of what have been staged before. | |
3ae854c3 | 314 | |
788070a2 MV |
315 | :git-commit: 1 |
316 | include::date-formats.txt[] | |
3ae854c3 | 317 | |
6c96753d JH |
318 | EXAMPLES |
319 | -------- | |
320 | When recording your own work, the contents of modified files in | |
321 | your working tree are temporarily stored to a staging area | |
0b444cdb | 322 | called the "index" with 'git add'. A file can be |
97e9a221 | 323 | reverted back, only in the index but not in the working tree, |
6cf378f0 | 324 | to that of the last commit with `git reset HEAD -- <file>`, |
0b444cdb | 325 | which effectively reverts 'git add' and prevents the changes to |
97e9a221 JX |
326 | this file from participating in the next commit. After building |
327 | the state to be committed incrementally with these commands, | |
328 | `git commit` (without any pathname parameter) is used to record what | |
6c96753d JH |
329 | has been staged so far. This is the most basic form of the |
330 | command. An example: | |
331 | ||
332 | ------------ | |
333 | $ edit hello.c | |
334 | $ git rm goodbye.c | |
335 | $ git add hello.c | |
336 | $ git commit | |
337 | ------------ | |
338 | ||
6c96753d JH |
339 | Instead of staging files after each individual change, you can |
340 | tell `git commit` to notice the changes to the files whose | |
341 | contents are tracked in | |
342 | your working tree and do corresponding `git add` and `git rm` | |
343 | for you. That is, this example does the same as the earlier | |
344 | example if there is no other change in your working tree: | |
345 | ||
346 | ------------ | |
347 | $ edit hello.c | |
348 | $ rm goodbye.c | |
349 | $ git commit -a | |
350 | ------------ | |
351 | ||
352 | The command `git commit -a` first looks at your working tree, | |
353 | notices that you have modified hello.c and removed goodbye.c, | |
354 | and performs necessary `git add` and `git rm` for you. | |
355 | ||
356 | After staging changes to many files, you can alter the order the | |
357 | changes are recorded in, by giving pathnames to `git commit`. | |
358 | When pathnames are given, the command makes a commit that | |
359 | only records the changes made to the named paths: | |
360 | ||
361 | ------------ | |
362 | $ edit hello.c hello.h | |
363 | $ git add hello.c hello.h | |
364 | $ edit Makefile | |
365 | $ git commit Makefile | |
366 | ------------ | |
367 | ||
368 | This makes a commit that records the modification to `Makefile`. | |
369 | The changes staged for `hello.c` and `hello.h` are not included | |
370 | in the resulting commit. However, their changes are not lost -- | |
371 | they are still staged and merely held back. After the above | |
372 | sequence, if you do: | |
373 | ||
374 | ------------ | |
375 | $ git commit | |
376 | ------------ | |
377 | ||
378 | this second commit would record the changes to `hello.c` and | |
379 | `hello.h` as expected. | |
380 | ||
0b444cdb | 381 | After a merge (initiated by 'git merge' or 'git pull') stops |
483bc4f0 | 382 | because of conflicts, cleanly merged |
6c96753d JH |
383 | paths are already staged to be committed for you, and paths that |
384 | conflicted are left in unmerged state. You would have to first | |
0b444cdb | 385 | check which paths are conflicting with 'git status' |
6c96753d | 386 | and after fixing them manually in your working tree, you would |
0b444cdb | 387 | stage the result as usual with 'git add': |
6c96753d JH |
388 | |
389 | ------------ | |
390 | $ git status | grep unmerged | |
391 | unmerged: hello.c | |
392 | $ edit hello.c | |
393 | $ git add hello.c | |
394 | ------------ | |
395 | ||
396 | After resolving conflicts and staging the result, `git ls-files -u` | |
397 | would stop mentioning the conflicted path. When you are done, | |
398 | run `git commit` to finally record the merge: | |
399 | ||
400 | ------------ | |
401 | $ git commit | |
402 | ------------ | |
403 | ||
404 | As with the case to record your own changes, you can use `-a` | |
405 | option to save typing. One difference is that during a merge | |
406 | resolution, you cannot use `git commit` with pathnames to | |
407 | alter the order the changes are committed, because the merge | |
408 | should be recorded as a single commit. In fact, the command | |
409 | refuses to run when given pathnames (but see `-i` option). | |
410 | ||
411 | ||
5dc7bcc2 JH |
412 | DISCUSSION |
413 | ---------- | |
414 | ||
936f32d3 JH |
415 | Though not required, it's a good idea to begin the commit message |
416 | with a single short (less than 50 character) line summarizing the | |
417 | change, followed by a blank line and then a more thorough description. | |
52ffe995 | 418 | The text up to the first blank line in a commit message is treated |
2de9b711 | 419 | as the commit title, and that title is used throughout Git. |
52ffe995 JW |
420 | For example, linkgit:git-format-patch[1] turns a commit into email, and it uses |
421 | the title on the Subject line and the rest of the commit in the body. | |
936f32d3 | 422 | |
5dc7bcc2 JH |
423 | include::i18n.txt[] |
424 | ||
ef0c2abf AR |
425 | ENVIRONMENT AND CONFIGURATION VARIABLES |
426 | --------------------------------------- | |
427 | The editor used to edit the commit log message will be chosen from the | |
428 | GIT_EDITOR environment variable, the core.editor configuration variable, the | |
429 | VISUAL environment variable, or the EDITOR environment variable (in that | |
b4479f07 | 430 | order). See linkgit:git-var[1] for details. |
6c96753d JH |
431 | |
432 | HOOKS | |
433 | ----- | |
8089c85b | 434 | This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`, |
6998e4db | 435 | and `post-commit` hooks. See linkgit:githooks[5] for more |
6c96753d | 436 | information. |
130fcca6 | 437 | |
41f597d9 JK |
438 | FILES |
439 | ----- | |
440 | ||
441 | `$GIT_DIR/COMMIT_EDITMSG`:: | |
442 | This file contains the commit message of a commit in progress. | |
443 | If `git commit` exits due to an error before creating a commit, | |
444 | any commit message that has been provided by the user (e.g., in | |
445 | an editor session) will be available in this file, but will be | |
446 | overwritten by the next invocation of `git commit`. | |
130fcca6 | 447 | |
6c96753d JH |
448 | SEE ALSO |
449 | -------- | |
5162e697 DM |
450 | linkgit:git-add[1], |
451 | linkgit:git-rm[1], | |
452 | linkgit:git-mv[1], | |
453 | linkgit:git-merge[1], | |
454 | linkgit:git-commit-tree[1] | |
130fcca6 | 455 | |
62033318 JH |
456 | GIT |
457 | --- | |
9e1f0a85 | 458 | Part of the linkgit:git[1] suite |