diff options
Diffstat (limited to 'Documentation/git-commit.adoc')
| -rw-r--r-- | Documentation/git-commit.adoc | 591 |
1 files changed, 591 insertions, 0 deletions
diff --git a/Documentation/git-commit.adoc b/Documentation/git-commit.adoc new file mode 100644 index 0000000000..ae988a883b --- /dev/null +++ b/Documentation/git-commit.adoc @@ -0,0 +1,591 @@ +git-commit(1) +============= + +NAME +---- +git-commit - Record changes to the repository + +SYNOPSIS +-------- +[synopsis] +git commit [-a | --interactive | --patch] [-s] [-v] [-u[<mode>]] [--amend] + [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>] + [-F <file> | -m <msg>] [--reset-author] [--allow-empty] + [--allow-empty-message] [--no-verify] [-e] [--author=<author>] + [--date=<date>] [--cleanup=<mode>] [--[no-]status] + [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]] + [(--trailer <token>[(=|:)<value>])...] [-S[<keyid>]] + [--] [<pathspec>...] + +DESCRIPTION +----------- +Create a new commit containing the current contents of the index and +the given log message describing the changes. The new commit is a +direct child of HEAD, usually the tip of the current branch, and the +branch is updated to point to it (unless no branch is associated with +the working tree, in which case `HEAD` is "detached" as described in +linkgit:git-checkout[1]). + +The content to be committed can be specified in several ways: + +1. by using linkgit:git-add[1] to incrementally "add" changes to the + index before using the `commit` command (Note: even modified files + must be "added"); + +2. by using linkgit:git-rm[1] to remove files from the working tree + and the index, again before using the `commit` command; + +3. by listing files as arguments to the `commit` command + (without `--interactive` or `--patch` switch), in which + case the commit will ignore changes staged in the index, and instead + record the current content of the listed files (which must already + be known to Git); + +4. by using the `-a` switch with the `commit` command to automatically + "add" changes from all known files (i.e. all files that are already + listed in the index) and to automatically "rm" files in the index + that have been removed from the working tree, and then perform the + actual commit; + +5. by using the `--interactive` or `--patch` switches with the `commit` command + to decide one by one which files or hunks should be part of the commit + in addition to contents in the index, + before finalizing the operation. See the ``Interactive Mode'' section of + linkgit:git-add[1] to learn how to operate these modes. + +The `--dry-run` option can be used to obtain a +summary of what is included by any of the above for the next +commit by giving the same set of parameters (options and paths). + +If you make a commit and then find a mistake immediately after +that, you can recover from it with `git reset`. + +:git-commit: 1 + +OPTIONS +------- +`-a`:: +`--all`:: + Automatically stage files that have + been modified and deleted, but new files you have not + told Git about are not affected. + +`-p`:: +`--patch`:: + Use the interactive patch selection interface to choose + which changes to commit. See linkgit:git-add[1] for + details. + +include::diff-context-options.adoc[] + +`-C <commit>`:: +`--reuse-message=<commit>`:: + Take an existing _<commit>_ object, and reuse the log message + and the authorship information (including the timestamp) + when creating the commit. + +`-c <commit>`:: +`--reedit-message=<commit>`:: + Like `-C`, but with `-c` the editor is invoked, so that + the user can further edit the commit message. + +`--fixup=[(amend|reword):]<commit>`:: + Create a new commit which "fixes up" _<commit>_ when applied with + `git rebase --autosquash`. Plain `--fixup=<commit>` creates a + "fixup!" commit which changes the content of _<commit>_ but leaves + its log message untouched. `--fixup=amend:<commit>` is similar but + creates an "amend!" commit which also replaces the log message of + _<commit>_ with the log message of the "amend!" commit. + `--fixup=reword:<commit>` creates an "amend!" commit which + replaces the log message of _<commit>_ with its own log message + but makes no changes to the content of _<commit>_. ++ +The commit created by plain `--fixup=<commit>` has a title +composed of "fixup!" followed by the title of _<commit>_, +and is recognized specially by `git rebase --autosquash`. The `-m` +option may be used to supplement the log message of the created +commit, but the additional commentary will be thrown away once the +"fixup!" commit is squashed into _<commit>_ by +`git rebase --autosquash`. ++ +The commit created by `--fixup=amend:<commit>` is similar but its +title is instead prefixed with "amend!". The log message of +_<commit>_ is copied into the log message of the "amend!" commit and +opened in an editor so it can be refined. When `git rebase +--autosquash` squashes the "amend!" commit into _<commit>_, the +log message of _<commit>_ is replaced by the refined log message +from the "amend!" commit. It is an error for the "amend!" commit's +log message to be empty unless `--allow-empty-message` is +specified. ++ +`--fixup=reword:<commit>` is shorthand for `--fixup=amend:<commit> + --only`. It creates an "amend!" commit with only a log message +(ignoring any changes staged in the index). When squashed by `git +rebase --autosquash`, it replaces the log message of _<commit>_ +without making any other changes. ++ +Neither "fixup!" nor "amend!" commits change authorship of +_<commit>_ when applied by `git rebase --autosquash`. +See linkgit:git-rebase[1] for details. + +`--squash=<commit>`:: + Construct a commit message for use with `git rebase --autosquash`. + The commit message title is taken from the specified + commit with a prefix of "squash! ". Can be used with additional + commit message options (`-m`/`-c`/`-C`/`-F`). See + linkgit:git-rebase[1] for details. + +`--reset-author`:: + When used with `-C`/`-c`/`--amend` options, or when committing after a + conflicting cherry-pick, declare that the authorship of the + resulting commit now belongs to the committer. This also renews + the author timestamp. + +`--short`:: + When doing a dry-run, give the output in the short-format. See + linkgit:git-status[1] for details. Implies `--dry-run`. + +`--branch`:: + Show the branch and tracking info even in short-format. + +`--porcelain`:: + When doing a dry-run, give the output in a porcelain-ready + format. See linkgit:git-status[1] for details. Implies + `--dry-run`. + +`--long`:: + When doing a dry-run, give the output in the long-format. + Implies `--dry-run`. + +`-z`:: +`--null`:: + When showing `short` or `porcelain` status output, print the + filename verbatim and terminate the entries with _NUL_, instead of _LF_. + If no format is given, implies the `--porcelain` output format. + Without the `-z` option, filenames with "unusual" characters are + quoted as explained for the configuration variable `core.quotePath` + (see linkgit:git-config[1]). + +`-F <file>`:: +`--file=<file>`:: + Take the commit message from _<file>_. Use '-' to + read the message from the standard input. + +`--author=<author>`:: + Override the commit author. Specify an explicit author using the + standard `A U Thor <author@example.com>` format. Otherwise _<author>_ + is assumed to be a pattern and is used to search for an existing + commit by that author (i.e. `git rev-list --all -i --author=<author>`); + the commit author is then copied from the first such commit found. + +`--date=<date>`:: + Override the author date used in the commit. + +`-m <msg>`:: +`--message=<msg>`:: + Use _<msg>_ as the commit message. + If multiple `-m` options are given, their values are + concatenated as separate paragraphs. ++ +The `-m` option is mutually exclusive with `-c`, `-C`, and `-F`. + +`-t <file>`:: +`--template=<file>`:: + When editing the commit message, start the editor with the + contents in _<file>_. The `commit.template` configuration + variable is often used to give this option implicitly to the + command. This mechanism can be used by projects that want to + guide participants with some hints on what to write in the message + in what order. If the user exits the editor without editing the + message, the commit is aborted. This has no effect when a message + is given by other means, e.g. with the `-m` or `-F` options. + +include::signoff-option.adoc[] + +`--trailer <token>[(=|:)<value>]`:: + Specify a (_<token>_, _<value>_) pair that should be applied as a + trailer. (e.g. `git commit --trailer "Signed-off-by:C O Mitter \ + <committer@example.com>" --trailer "Helped-by:C O Mitter \ + <committer@example.com>"` will add the `Signed-off-by` trailer + and the `Helped-by` trailer to the commit message.) + The `trailer.*` configuration variables + (linkgit:git-interpret-trailers[1]) can be used to define if + a duplicated trailer is omitted, where in the run of trailers + each trailer would appear, and other details. + +`-n`:: +`--[no-]verify`:: + Bypass the `pre-commit` and `commit-msg` hooks. + See also linkgit:githooks[5]. + +`--allow-empty`:: + Usually recording a commit that has the exact same tree as its + sole parent commit is a mistake, and the command prevents you + from making such a commit. This option bypasses the safety, and + is primarily for use by foreign SCM interface scripts. + +`--allow-empty-message`:: + Create a commit with an empty commit message without using plumbing + commands like linkgit:git-commit-tree[1]. Like `--allow-empty`, this + command is primarily for use by foreign SCM interface scripts. + +`--cleanup=<mode>`:: + Determine how the supplied commit message should be + cleaned up before committing. The '<mode>' can be `strip`, + `whitespace`, `verbatim`, `scissors` or `default`. ++ +-- +`strip`:: + Strip leading and trailing empty lines, trailing whitespace, + commentary and collapse consecutive empty lines. +`whitespace`:: + Same as `strip` except #commentary is not removed. +`verbatim`:: + Do not change the message at all. +`scissors`:: + Same as `whitespace` except that everything from (and including) + the line found below is truncated, if the message is to be edited. + "`#`" can be customized with `core.commentChar`. + + # ------------------------ >8 ------------------------ + +`default`:: + Same as `strip` if the message is to be edited. + Otherwise `whitespace`. +-- ++ +The default can be changed by the `commit.cleanup` configuration +variable (see linkgit:git-config[1]). + +`-e`:: +`--edit`:: + Let the user further edit the message taken from _<file>_ + with `-F <file>`, command line with `-m <message>`, and + from _<commit>_ with `-C <commit>`. + +`--no-edit`:: + Use the selected commit message without launching an editor. + For example, `git commit --amend --no-edit` amends a commit + without changing its commit message. + +`--amend`:: + Replace the tip of the current branch by creating a new + commit. The recorded tree is prepared as usual (including + the effect of the `-i` and `-o` options and explicit + pathspec), and the message from the original commit is used + as the starting point, instead of an empty message, when no + other message is specified from the command line via options + such as `-m`, `-F`, `-c`, etc. The new commit has the same + parents and author as the current one (the `--reset-author` + option can countermand this). ++ +-- +It is a rough equivalent for: +------ + $ git reset --soft HEAD^ + $ ... do something else to come up with the right tree ... + $ git commit -c ORIG_HEAD + +------ +but can be used to amend a merge commit. +-- ++ +You should understand the implications of rewriting history if you +amend a commit that has already been published. (See the "RECOVERING +FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) + +`--no-post-rewrite`:: + Bypass the `post-rewrite` hook. + +`-i`:: +`--include`:: + Before making a commit out of staged contents so far, + stage the contents of paths given on the command line + as well. This is usually not what you want unless you + are concluding a conflicted merge. + +`-o`:: +`--only`:: + Make a commit by taking the updated working tree contents + of the paths specified on the + command line, disregarding any contents that have been + staged for other paths. This is the default mode of operation of + `git commit` if any paths are given on the command line, + in which case this option can be omitted. + If this option is specified together with `--amend`, then + no paths need to be specified, which can be used to amend + the last commit without committing changes that have + already been staged. If used together with `--allow-empty` + paths are also not required, and an empty commit will be created. + +`--pathspec-from-file=<file>`:: + Pass pathspec in _<file>_ instead of commandline args. If + _<file>_ is exactly `-` then standard input is used. Pathspec + elements are separated by _LF_ or _CR_/_LF_. Pathspec elements can be + quoted as explained for the configuration variable `core.quotePath` + (see linkgit:git-config[1]). See also `--pathspec-file-nul` and + global `--literal-pathspecs`. + +`--pathspec-file-nul`:: + Only meaningful with `--pathspec-from-file`. Pathspec elements are + separated with _NUL_ character and all other characters are taken + literally (including newlines and quotes). + +`-u[<mode>]`:: +`--untracked-files[=<mode>]`:: + Show untracked files. ++ +-- +The _<mode>_ parameter is optional (defaults to `all`), and is used to +specify the handling of untracked files; when `-u` is not used, the +default is `normal`, i.e. show untracked files and directories. + +The possible options are: + +`no`:: Show no untracked files +`normal`:: Shows untracked files and directories +`all`:: Also shows individual files in untracked directories. + +All usual spellings for Boolean value `true` are taken as `normal` +and `false` as `no`. +The default can be changed using the `status.showUntrackedFiles` +configuration variable documented in linkgit:git-config[1]. +-- + +`-v`:: +`--verbose`:: + Show unified diff between the `HEAD` commit and what + would be committed at the bottom of the commit message + template to help the user describe the commit by reminding + what changes the commit has. + Note that this diff output doesn't have its + lines prefixed with `#`. This diff will not be a part + of the commit message. See the `commit.verbose` configuration + variable in linkgit:git-config[1]. ++ +If specified twice, show in addition the unified diff between +what would be committed and the worktree files, i.e. the unstaged +changes to tracked files. + +`-q`:: +`--quiet`:: + Suppress commit summary message. + +`--dry-run`:: + Do not create a commit, but show a list of paths that are + to be committed, paths with local changes that will be left + uncommitted and paths that are untracked. + +`--status`:: + Include the output of linkgit:git-status[1] in the commit + message template when using an editor to prepare the commit + message. Defaults to on, but can be used to override + configuration variable `commit.status`. + +`--no-status`:: + Do not include the output of linkgit:git-status[1] in the + commit message template when using an editor to prepare the + default commit message. + +`-S[<key-id>]`:: +`--gpg-sign[=<key-id>]`:: +`--no-gpg-sign`:: + GPG-sign commits. The _<key-id>_ is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. `--no-gpg-sign` is useful to + countermand both `commit.gpgSign` configuration variable, and + earlier `--gpg-sign`. + +`--`:: + Do not interpret any more arguments as options. + +`<pathspec>...`:: + When _<pathspec>_ is given on the command line, commit the contents of + the files that match the pathspec without recording the changes + already added to the index. The contents of these files are also + staged for the next commit on top of what have been staged before. ++ +For more details, see the 'pathspec' entry in linkgit:gitglossary[7]. + +EXAMPLES +-------- +When recording your own work, the contents of modified files in +your working tree are temporarily stored to a staging area +called the "index" with `git add`. A file can be +reverted back, only in the index but not in the working tree, +to that of the last commit with `git restore --staged <file>`, +which effectively reverts `git add` and prevents the changes to +this file from participating in the next commit. After building +the state to be committed incrementally with these commands, +`git commit` (without any pathname parameter) is used to record what +has been staged so far. This is the most basic form of the +command. An example: + +------------ +$ edit hello.c +$ git rm goodbye.c +$ git add hello.c +$ git commit +------------ + +Instead of staging files after each individual change, you can +tell `git commit` to notice the changes to the files whose +contents are tracked in +your working tree and do corresponding `git add` and `git rm` +for you. That is, this example does the same as the earlier +example if there is no other change in your working tree: + +------------ +$ edit hello.c +$ rm goodbye.c +$ git commit -a +------------ + +The command `git commit -a` first looks at your working tree, +notices that you have modified `hello.c` and removed `goodbye.c`, +and performs necessary `git add` and `git rm` for you. + +After staging changes to many files, you can alter the order the +changes are recorded in, by giving pathnames to `git commit`. +When pathnames are given, the command makes a commit that +only records the changes made to the named paths: + +------------ +$ edit hello.c hello.h +$ git add hello.c hello.h +$ edit Makefile +$ git commit Makefile +------------ + +This makes a commit that records the modification to `Makefile`. +The changes staged for `hello.c` and `hello.h` are not included +in the resulting commit. However, their changes are not lost -- +they are still staged and merely held back. After the above +sequence, if you do: + +------------ +$ git commit +------------ + +this second commit would record the changes to `hello.c` and +`hello.h` as expected. + +After a merge (initiated by `git merge` or `git pull`) stops +because of conflicts, cleanly merged +paths are already staged to be committed for you, and paths that +conflicted are left in unmerged state. You would have to first +check which paths are conflicting with `git status` +and after fixing them manually in your working tree, you would +stage the result as usual with `git add`: + +------------ +$ git status | grep unmerged +unmerged: hello.c +$ edit hello.c +$ git add hello.c +------------ + +After resolving conflicts and staging the result, `git ls-files -u` +would stop mentioning the conflicted path. When you are done, +run `git commit` to finally record the merge: + +------------ +$ git commit +------------ + +As with the case to record your own changes, you can use `-a` +option to save typing. One difference is that during a merge +resolution, you cannot use `git commit` with pathnames to +alter the order the changes are committed, because the merge +should be recorded as a single commit. In fact, the command +refuses to run when given pathnames (but see `-i` option). + +COMMIT INFORMATION +------------------ + +Author and committer information is taken from the following environment +variables, if set: + + * `GIT_AUTHOR_NAME` + * `GIT_AUTHOR_EMAIL` + * `GIT_AUTHOR_DATE` + * `GIT_COMMITTER_NAME` + * `GIT_COMMITTER_EMAIL` + * `GIT_COMMITTER_DATE` + +(nb "<", ">" and "\n"s are stripped) + +The author and committer names are by convention some form of a personal name +(that is, the name by which other humans refer to you), although Git does not +enforce or require any particular form. Arbitrary Unicode may be used, subject +to the constraints listed above. This name has no effect on authentication; for +that, see the `credential.username` variable in linkgit:git-config[1]. + +In case (some of) these environment variables are not set, the information +is taken from the configuration items `user.name` and `user.email`, or, if not +present, the environment variable `EMAIL`, or, if that is not set, +system user name and the hostname used for outgoing mail (taken +from `/etc/mailname` and falling back to the fully qualified hostname when +that file does not exist). + +The `author.name` and `committer.name` and their corresponding email options +override `user.name` and `user.email` if set and are overridden themselves by +the environment variables. + +The typical usage is to set just the `user.name` and `user.email` variables; +the other options are provided for more complex use cases. + +:git-commit: 1 +include::date-formats.adoc[] + +DISCUSSION +---------- + +Though not required, it's a good idea to begin the commit message +with a single short (no more than 50 characters) line summarizing the +change, followed by a blank line and then a more thorough description. +The text up to the first blank line in a commit message is treated +as the commit title, and that title is used throughout Git. +For example, linkgit:git-format-patch[1] turns a commit into email, and it uses +the title on the Subject line and the rest of the commit in the body. + +include::i18n.adoc[] + +ENVIRONMENT AND CONFIGURATION VARIABLES +--------------------------------------- +The editor used to edit the commit log message will be chosen from the +`GIT_EDITOR` environment variable, the `core.editor` configuration variable, the +`VISUAL` environment variable, or the `EDITOR` environment variable (in that +order). See linkgit:git-var[1] for details. + +include::includes/cmd-config-section-rest.adoc[] + +include::config/commit.adoc[] + +HOOKS +----- +This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`, +`post-commit` and `post-rewrite` hooks. See linkgit:githooks[5] for more +information. + +FILES +----- + +`$GIT_DIR/COMMIT_EDITMSG`:: + This file contains the commit message of a commit in progress. + If `git commit` exits due to an error before creating a commit, + any commit message that has been provided by the user (e.g., in + an editor session) will be available in this file, but will be + overwritten by the next invocation of `git commit`. + +SEE ALSO +-------- +linkgit:git-add[1], +linkgit:git-rm[1], +linkgit:git-mv[1], +linkgit:git-merge[1], +linkgit:git-commit-tree[1] + +GIT +--- +Part of the linkgit:git[1] suite |