]>
Commit | Line | Data |
---|---|---|
1 | git-commit(1) | |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-commit - Record changes to the repository | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
10 | [verse] | |
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>] | |
15 | [--date=<date>] [--cleanup=<mode>] [--[no-]status] | |
16 | [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]] | |
17 | [-S[<keyid>]] [--] [<pathspec>...] | |
18 | ||
19 | DESCRIPTION | |
20 | ----------- | |
21 | Create a new commit containing the current contents of the index and | |
22 | the given log message describing the changes. The new commit is a | |
23 | direct child of HEAD, usually the tip of the current branch, and the | |
24 | branch is updated to point to it (unless no branch is associated with | |
25 | the working tree, in which case HEAD is "detached" as described in | |
26 | linkgit:git-checkout[1]). | |
27 | ||
28 | The content to be committed can be specified in several ways: | |
29 | ||
30 | 1. by using linkgit:git-add[1] to incrementally "add" changes to the | |
31 | index before using the 'commit' command (Note: even modified files | |
32 | must be "added"); | |
33 | ||
34 | 2. by using linkgit:git-rm[1] to remove files from the working tree | |
35 | and the index, again before using the 'commit' command; | |
36 | ||
37 | 3. by listing files as arguments to the 'commit' command | |
38 | (without --interactive or --patch switch), in which | |
39 | case the commit will ignore changes staged in the index, and instead | |
40 | record the current content of the listed files (which must already | |
41 | be known to Git); | |
42 | ||
43 | 4. by using the -a switch with the 'commit' command to automatically | |
44 | "add" changes from all known files (i.e. all files that are already | |
45 | listed in the index) and to automatically "rm" files in the index | |
46 | that have been removed from the working tree, and then perform the | |
47 | actual commit; | |
48 | ||
49 | 5. by using the --interactive or --patch switches with the 'commit' command | |
50 | to decide one by one which files or hunks should be part of the commit | |
51 | in addition to contents in the index, | |
52 | before finalizing the operation. See the ``Interactive Mode'' section of | |
53 | linkgit:git-add[1] to learn how to operate these modes. | |
54 | ||
55 | The `--dry-run` option can be used to obtain a | |
56 | summary of what is included by any of the above for the next | |
57 | commit by giving the same set of parameters (options and paths). | |
58 | ||
59 | If you make a commit and then find a mistake immediately after | |
60 | that, you can recover from it with 'git reset'. | |
61 | ||
62 | ||
63 | OPTIONS | |
64 | ------- | |
65 | -a:: | |
66 | --all:: | |
67 | Tell the command to automatically stage files that have | |
68 | been modified and deleted, but new files you have not | |
69 | told Git about are not affected. | |
70 | ||
71 | -p:: | |
72 | --patch:: | |
73 | Use the interactive patch selection interface to chose | |
74 | which changes to commit. See linkgit:git-add[1] for | |
75 | details. | |
76 | ||
77 | -C <commit>:: | |
78 | --reuse-message=<commit>:: | |
79 | Take an existing commit object, and reuse the log message | |
80 | and the authorship information (including the timestamp) | |
81 | when creating the commit. | |
82 | ||
83 | -c <commit>:: | |
84 | --reedit-message=<commit>:: | |
85 | Like '-C', but with `-c` the editor is invoked, so that | |
86 | the user can further edit the commit message. | |
87 | ||
88 | --fixup=<commit>:: | |
89 | Construct a commit message for use with `rebase --autosquash`. | |
90 | The commit message will be the subject line from the specified | |
91 | commit with a prefix of "fixup! ". See linkgit:git-rebase[1] | |
92 | for details. | |
93 | ||
94 | --squash=<commit>:: | |
95 | Construct a commit message for use with `rebase --autosquash`. | |
96 | The commit message subject line is taken from the specified | |
97 | commit with a prefix of "squash! ". Can be used with additional | |
98 | commit message options (`-m`/`-c`/`-C`/`-F`). See | |
99 | linkgit:git-rebase[1] for details. | |
100 | ||
101 | --reset-author:: | |
102 | When used with -C/-c/--amend options, or when committing after a | |
103 | conflicting cherry-pick, declare that the authorship of the | |
104 | resulting commit now belongs to the committer. This also renews | |
105 | the author timestamp. | |
106 | ||
107 | --short:: | |
108 | When doing a dry-run, give the output in the short-format. See | |
109 | linkgit:git-status[1] for details. Implies `--dry-run`. | |
110 | ||
111 | --branch:: | |
112 | Show the branch and tracking info even in short-format. | |
113 | ||
114 | --porcelain:: | |
115 | When doing a dry-run, give the output in a porcelain-ready | |
116 | format. See linkgit:git-status[1] for details. Implies | |
117 | `--dry-run`. | |
118 | ||
119 | --long:: | |
120 | When doing a dry-run, give the output in the long-format. | |
121 | Implies `--dry-run`. | |
122 | ||
123 | -z:: | |
124 | --null:: | |
125 | When showing `short` or `porcelain` status output, print the | |
126 | filename verbatim and terminate the entries with NUL, instead of LF. | |
127 | If no format is given, implies the `--porcelain` output format. | |
128 | Without the `-z` option, filenames with "unusual" characters are | |
129 | quoted as explained for the configuration variable `core.quotePath` | |
130 | (see linkgit:git-config[1]). | |
131 | ||
132 | -F <file>:: | |
133 | --file=<file>:: | |
134 | Take the commit message from the given file. Use '-' to | |
135 | read the message from the standard input. | |
136 | ||
137 | --author=<author>:: | |
138 | Override the commit author. Specify an explicit author using the | |
139 | standard `A U Thor <author@example.com>` format. Otherwise <author> | |
140 | is assumed to be a pattern and is used to search for an existing | |
141 | commit by that author (i.e. rev-list --all -i --author=<author>); | |
142 | the commit author is then copied from the first such commit found. | |
143 | ||
144 | --date=<date>:: | |
145 | Override the author date used in the commit. | |
146 | ||
147 | -m <msg>:: | |
148 | --message=<msg>:: | |
149 | Use the given <msg> as the commit message. | |
150 | If multiple `-m` options are given, their values are | |
151 | concatenated as separate paragraphs. | |
152 | + | |
153 | The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`. | |
154 | ||
155 | -t <file>:: | |
156 | --template=<file>:: | |
157 | When editing the commit message, start the editor with the | |
158 | contents in the given file. The `commit.template` configuration | |
159 | variable is often used to give this option implicitly to the | |
160 | command. This mechanism can be used by projects that want to | |
161 | guide participants with some hints on what to write in the message | |
162 | in what order. If the user exits the editor without editing the | |
163 | message, the commit is aborted. This has no effect when a message | |
164 | is given by other means, e.g. with the `-m` or `-F` options. | |
165 | ||
166 | -s:: | |
167 | --signoff:: | |
168 | Add Signed-off-by line by the committer at the end of the commit | |
169 | log message. The meaning of a signoff depends on the project, | |
170 | but it typically certifies that committer has | |
171 | the rights to submit this work under the same license and | |
172 | agrees to a Developer Certificate of Origin | |
173 | (see http://developercertificate.org/ for more information). | |
174 | ||
175 | -n:: | |
176 | --no-verify:: | |
177 | This option bypasses the pre-commit and commit-msg hooks. | |
178 | See also linkgit:githooks[5]. | |
179 | ||
180 | --allow-empty:: | |
181 | Usually recording a commit that has the exact same tree as its | |
182 | sole parent commit is a mistake, and the command prevents you | |
183 | from making such a commit. This option bypasses the safety, and | |
184 | is primarily for use by foreign SCM interface scripts. | |
185 | ||
186 | --allow-empty-message:: | |
187 | Like --allow-empty this command is primarily for use by foreign | |
188 | SCM interface scripts. It allows you to create a commit with an | |
189 | empty commit message without using plumbing commands like | |
190 | linkgit:git-commit-tree[1]. | |
191 | ||
192 | --cleanup=<mode>:: | |
193 | This option determines how the supplied commit message should be | |
194 | cleaned up before committing. The '<mode>' can be `strip`, | |
195 | `whitespace`, `verbatim`, `scissors` or `default`. | |
196 | + | |
197 | -- | |
198 | strip:: | |
199 | Strip leading and trailing empty lines, trailing whitespace, | |
200 | commentary and collapse consecutive empty lines. | |
201 | whitespace:: | |
202 | Same as `strip` except #commentary is not removed. | |
203 | verbatim:: | |
204 | Do not change the message at all. | |
205 | scissors:: | |
206 | Same as `whitespace` except that everything from (and including) | |
207 | the line found below is truncated, if the message is to be edited. | |
208 | "`#`" can be customized with core.commentChar. | |
209 | ||
210 | # ------------------------ >8 ------------------------ | |
211 | ||
212 | default:: | |
213 | Same as `strip` if the message is to be edited. | |
214 | Otherwise `whitespace`. | |
215 | -- | |
216 | + | |
217 | The default can be changed by the `commit.cleanup` configuration | |
218 | variable (see linkgit:git-config[1]). | |
219 | ||
220 | -e:: | |
221 | --edit:: | |
222 | The message taken from file with `-F`, command line with | |
223 | `-m`, and from commit object with `-C` are usually used as | |
224 | the commit log message unmodified. This option lets you | |
225 | further edit the message taken from these sources. | |
226 | ||
227 | --no-edit:: | |
228 | Use the selected commit message without launching an editor. | |
229 | For example, `git commit --amend --no-edit` amends a commit | |
230 | without changing its commit message. | |
231 | ||
232 | --amend:: | |
233 | Replace the tip of the current branch by creating a new | |
234 | commit. The recorded tree is prepared as usual (including | |
235 | the effect of the `-i` and `-o` options and explicit | |
236 | pathspec), and the message from the original commit is used | |
237 | as the starting point, instead of an empty message, when no | |
238 | other message is specified from the command line via options | |
239 | such as `-m`, `-F`, `-c`, etc. The new commit has the same | |
240 | parents and author as the current one (the `--reset-author` | |
241 | option can countermand this). | |
242 | + | |
243 | -- | |
244 | It is a rough equivalent for: | |
245 | ------ | |
246 | $ git reset --soft HEAD^ | |
247 | $ ... do something else to come up with the right tree ... | |
248 | $ git commit -c ORIG_HEAD | |
249 | ||
250 | ------ | |
251 | but can be used to amend a merge commit. | |
252 | -- | |
253 | + | |
254 | You should understand the implications of rewriting history if you | |
255 | amend a commit that has already been published. (See the "RECOVERING | |
256 | FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) | |
257 | ||
258 | --no-post-rewrite:: | |
259 | Bypass the post-rewrite hook. | |
260 | ||
261 | -i:: | |
262 | --include:: | |
263 | Before making a commit out of staged contents so far, | |
264 | stage the contents of paths given on the command line | |
265 | as well. This is usually not what you want unless you | |
266 | are concluding a conflicted merge. | |
267 | ||
268 | -o:: | |
269 | --only:: | |
270 | Make a commit by taking the updated working tree contents | |
271 | of the paths specified on the | |
272 | command line, disregarding any contents that have been | |
273 | staged for other paths. This is the default mode of operation of | |
274 | 'git commit' if any paths are given on the command line, | |
275 | in which case this option can be omitted. | |
276 | If this option is specified together with `--amend`, then | |
277 | no paths need to be specified, which can be used to amend | |
278 | the last commit without committing changes that have | |
279 | already been staged. If used together with `--allow-empty` | |
280 | paths are also not required, and an empty commit will be created. | |
281 | ||
282 | --pathspec-from-file=<file>:: | |
283 | Pathspec is passed in `<file>` instead of commandline args. If | |
284 | `<file>` is exactly `-` then standard input is used. Pathspec | |
285 | elements are separated by LF or CR/LF. Pathspec elements can be | |
286 | quoted as explained for the configuration variable `core.quotePath` | |
287 | (see linkgit:git-config[1]). See also `--pathspec-file-nul` and | |
288 | global `--literal-pathspecs`. | |
289 | ||
290 | --pathspec-file-nul:: | |
291 | Only meaningful with `--pathspec-from-file`. Pathspec elements are | |
292 | separated with NUL character and all other characters are taken | |
293 | literally (including newlines and quotes). | |
294 | ||
295 | -u[<mode>]:: | |
296 | --untracked-files[=<mode>]:: | |
297 | Show untracked files. | |
298 | + | |
299 | -- | |
300 | The mode parameter is optional (defaults to 'all'), and is used to | |
301 | specify the handling of untracked files; when -u is not used, the | |
302 | default is 'normal', i.e. show untracked files and directories. | |
303 | ||
304 | The possible options are: | |
305 | ||
306 | - 'no' - Show no untracked files | |
307 | - 'normal' - Shows untracked files and directories | |
308 | - 'all' - Also shows individual files in untracked directories. | |
309 | ||
310 | The default can be changed using the status.showUntrackedFiles | |
311 | configuration variable documented in linkgit:git-config[1]. | |
312 | -- | |
313 | ||
314 | -v:: | |
315 | --verbose:: | |
316 | Show unified diff between the HEAD commit and what | |
317 | would be committed at the bottom of the commit message | |
318 | template to help the user describe the commit by reminding | |
319 | what changes the commit has. | |
320 | Note that this diff output doesn't have its | |
321 | lines prefixed with '#'. This diff will not be a part | |
322 | of the commit message. See the `commit.verbose` configuration | |
323 | variable in linkgit:git-config[1]. | |
324 | + | |
325 | If specified twice, show in addition the unified diff between | |
326 | what would be committed and the worktree files, i.e. the unstaged | |
327 | changes to tracked files. | |
328 | ||
329 | -q:: | |
330 | --quiet:: | |
331 | Suppress commit summary message. | |
332 | ||
333 | --dry-run:: | |
334 | Do not create a commit, but show a list of paths that are | |
335 | to be committed, paths with local changes that will be left | |
336 | uncommitted and paths that are untracked. | |
337 | ||
338 | --status:: | |
339 | Include the output of linkgit:git-status[1] in the commit | |
340 | message template when using an editor to prepare the commit | |
341 | message. Defaults to on, but can be used to override | |
342 | configuration variable commit.status. | |
343 | ||
344 | --no-status:: | |
345 | Do not include the output of linkgit:git-status[1] in the | |
346 | commit message template when using an editor to prepare the | |
347 | default commit message. | |
348 | ||
349 | -S[<keyid>]:: | |
350 | --gpg-sign[=<keyid>]:: | |
351 | GPG-sign commits. The `keyid` argument is optional and | |
352 | defaults to the committer identity; if specified, it must be | |
353 | stuck to the option without a space. | |
354 | ||
355 | --no-gpg-sign:: | |
356 | Countermand `commit.gpgSign` configuration variable that is | |
357 | set to force each and every commit to be signed. | |
358 | ||
359 | \--:: | |
360 | Do not interpret any more arguments as options. | |
361 | ||
362 | <pathspec>...:: | |
363 | When pathspec is given on the command line, commit the contents of | |
364 | the files that match the pathspec without recording the changes | |
365 | already added to the index. The contents of these files are also | |
366 | staged for the next commit on top of what have been staged before. | |
367 | + | |
368 | For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. | |
369 | ||
370 | :git-commit: 1 | |
371 | include::date-formats.txt[] | |
372 | ||
373 | EXAMPLES | |
374 | -------- | |
375 | When recording your own work, the contents of modified files in | |
376 | your working tree are temporarily stored to a staging area | |
377 | called the "index" with 'git add'. A file can be | |
378 | reverted back, only in the index but not in the working tree, | |
379 | to that of the last commit with `git restore --staged <file>`, | |
380 | which effectively reverts 'git add' and prevents the changes to | |
381 | this file from participating in the next commit. After building | |
382 | the state to be committed incrementally with these commands, | |
383 | `git commit` (without any pathname parameter) is used to record what | |
384 | has been staged so far. This is the most basic form of the | |
385 | command. An example: | |
386 | ||
387 | ------------ | |
388 | $ edit hello.c | |
389 | $ git rm goodbye.c | |
390 | $ git add hello.c | |
391 | $ git commit | |
392 | ------------ | |
393 | ||
394 | Instead of staging files after each individual change, you can | |
395 | tell `git commit` to notice the changes to the files whose | |
396 | contents are tracked in | |
397 | your working tree and do corresponding `git add` and `git rm` | |
398 | for you. That is, this example does the same as the earlier | |
399 | example if there is no other change in your working tree: | |
400 | ||
401 | ------------ | |
402 | $ edit hello.c | |
403 | $ rm goodbye.c | |
404 | $ git commit -a | |
405 | ------------ | |
406 | ||
407 | The command `git commit -a` first looks at your working tree, | |
408 | notices that you have modified hello.c and removed goodbye.c, | |
409 | and performs necessary `git add` and `git rm` for you. | |
410 | ||
411 | After staging changes to many files, you can alter the order the | |
412 | changes are recorded in, by giving pathnames to `git commit`. | |
413 | When pathnames are given, the command makes a commit that | |
414 | only records the changes made to the named paths: | |
415 | ||
416 | ------------ | |
417 | $ edit hello.c hello.h | |
418 | $ git add hello.c hello.h | |
419 | $ edit Makefile | |
420 | $ git commit Makefile | |
421 | ------------ | |
422 | ||
423 | This makes a commit that records the modification to `Makefile`. | |
424 | The changes staged for `hello.c` and `hello.h` are not included | |
425 | in the resulting commit. However, their changes are not lost -- | |
426 | they are still staged and merely held back. After the above | |
427 | sequence, if you do: | |
428 | ||
429 | ------------ | |
430 | $ git commit | |
431 | ------------ | |
432 | ||
433 | this second commit would record the changes to `hello.c` and | |
434 | `hello.h` as expected. | |
435 | ||
436 | After a merge (initiated by 'git merge' or 'git pull') stops | |
437 | because of conflicts, cleanly merged | |
438 | paths are already staged to be committed for you, and paths that | |
439 | conflicted are left in unmerged state. You would have to first | |
440 | check which paths are conflicting with 'git status' | |
441 | and after fixing them manually in your working tree, you would | |
442 | stage the result as usual with 'git add': | |
443 | ||
444 | ------------ | |
445 | $ git status | grep unmerged | |
446 | unmerged: hello.c | |
447 | $ edit hello.c | |
448 | $ git add hello.c | |
449 | ------------ | |
450 | ||
451 | After resolving conflicts and staging the result, `git ls-files -u` | |
452 | would stop mentioning the conflicted path. When you are done, | |
453 | run `git commit` to finally record the merge: | |
454 | ||
455 | ------------ | |
456 | $ git commit | |
457 | ------------ | |
458 | ||
459 | As with the case to record your own changes, you can use `-a` | |
460 | option to save typing. One difference is that during a merge | |
461 | resolution, you cannot use `git commit` with pathnames to | |
462 | alter the order the changes are committed, because the merge | |
463 | should be recorded as a single commit. In fact, the command | |
464 | refuses to run when given pathnames (but see `-i` option). | |
465 | ||
466 | ||
467 | DISCUSSION | |
468 | ---------- | |
469 | ||
470 | Though not required, it's a good idea to begin the commit message | |
471 | with a single short (less than 50 character) line summarizing the | |
472 | change, followed by a blank line and then a more thorough description. | |
473 | The text up to the first blank line in a commit message is treated | |
474 | as the commit title, and that title is used throughout Git. | |
475 | For example, linkgit:git-format-patch[1] turns a commit into email, and it uses | |
476 | the title on the Subject line and the rest of the commit in the body. | |
477 | ||
478 | include::i18n.txt[] | |
479 | ||
480 | ENVIRONMENT AND CONFIGURATION VARIABLES | |
481 | --------------------------------------- | |
482 | The editor used to edit the commit log message will be chosen from the | |
483 | `GIT_EDITOR` environment variable, the core.editor configuration variable, the | |
484 | `VISUAL` environment variable, or the `EDITOR` environment variable (in that | |
485 | order). See linkgit:git-var[1] for details. | |
486 | ||
487 | HOOKS | |
488 | ----- | |
489 | This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`, | |
490 | `post-commit` and `post-rewrite` hooks. See linkgit:githooks[5] for more | |
491 | information. | |
492 | ||
493 | FILES | |
494 | ----- | |
495 | ||
496 | `$GIT_DIR/COMMIT_EDITMSG`:: | |
497 | This file contains the commit message of a commit in progress. | |
498 | If `git commit` exits due to an error before creating a commit, | |
499 | any commit message that has been provided by the user (e.g., in | |
500 | an editor session) will be available in this file, but will be | |
501 | overwritten by the next invocation of `git commit`. | |
502 | ||
503 | SEE ALSO | |
504 | -------- | |
505 | linkgit:git-add[1], | |
506 | linkgit:git-rm[1], | |
507 | linkgit:git-mv[1], | |
508 | linkgit:git-merge[1], | |
509 | linkgit:git-commit-tree[1] | |
510 | ||
511 | GIT | |
512 | --- | |
513 | Part of the linkgit:git[1] suite |