diff options
Diffstat (limited to 'Documentation/git-commit.txt')
| -rw-r--r-- | Documentation/git-commit.txt | 383 |
1 files changed, 302 insertions, 81 deletions
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 2187eee416..7f34a5b331 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -8,90 +8,220 @@ git-commit - Record changes to the repository SYNOPSIS -------- [verse] -'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg> | - --amend] [--no-verify] [-e] [--author <author>] - [--] [[-i | -o ]<file>...] +'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend] + [--dry-run] [(-c | -C | --fixup | --squash) <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] [-S[<keyid>]] [--] [<file>...] DESCRIPTION ----------- -Use 'git commit' when you want to record your changes into the repository -along with a log message describing what the commit is about. All changes -to be committed must be explicitly identified using one of the following -methods: +Stores the current contents of the index in a new commit along +with a log message from the user describing the changes. -1. by using gitlink:git-add[1] to incrementally "add" changes to the - next commit before using the 'commit' command (Note: even modified +The content to be added can be specified in several ways: + +1. by using 'git add' to incrementally "add" changes to the + index before using the 'commit' command (Note: even modified files must be "added"); -2. by using gitlink:git-rm[1] to identify content removal for the next - commit, again before using the 'commit' command; +2. by using 'git rm' 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, 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); -3. by directly listing files containing changes to be committed as arguments - to the 'commit' command, in which cases only those files alone will be - considered for the commit; +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; -4. by using the -a switch with the 'commit' command to automatically "add" - changes from all known files i.e. files that have already been committed - before, and to automatically "rm" files that have been - removed from the working tree, and 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, + before finalizing the operation. See the ``Interactive Mode'' section of + linkgit:git-add[1] to learn how to operate these modes. -The gitlink:git-status[1] command can be used to obtain a +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 you would give to -this command. +commit by giving the same set of parameters (options and paths). -If you make a commit and then found a mistake immediately after -that, you can recover from it with gitlink:git-reset[1]. +If you make a commit and then find a mistake immediately after +that, you can recover from it with 'git reset'. OPTIONS ------- --a|--all:: +-a:: +--all:: Tell the command to automatically stage files that have been modified and deleted, but new files you have not - told git about are not affected. + told Git about are not affected. --c or -C <commit>:: - Take existing commit object, and reuse the log message +-p:: +--patch:: + Use the interactive patch selection interface to chose + which changes to commit. See linkgit:git-add[1] for + details. + +-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. With '-C', the editor is not - invoked; with '-c' the user can further edit the commit - message. + 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=<commit>:: + Construct a commit message for use with `rebase --autosquash`. + The commit message will be the subject line from the specified + commit with a prefix of "fixup! ". See linkgit:git-rebase[1] + for details. + +--squash=<commit>:: + Construct a commit message for use with `rebase --autosquash`. + The commit message subject line 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 + 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 a the long-format. + Implies `--dry-run`. + +-z:: +--null:: + When showing `short` or `porcelain` status output, terminate + entries in the status output with NUL, instead of LF. If no + format is given, implies the `--porcelain` output format. -F <file>:: +--file=<file>:: Take the commit message from the given file. Use '-' to read the message from the standard input. ---author <author>:: - Override the author name used in the commit. Use - `A U Thor <author@example.com>` format. +--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. 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 the given <msg> as the commit message. - --s|--signoff:: - Add Signed-off-by line at the end of the commit message. - + If multiple `-m` options are given, their values are + concatenated as separate paragraphs. + +-t <file>:: +--template=<file>:: + When editing the commit message, start the editor with the + contents in the given 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. + +-s:: +--signoff:: + Add Signed-off-by line by the committer at the end of the commit + log message. + +-n:: --no-verify:: - This option bypasses the pre-commit hook. - See also link:hooks.html[hooks]. + This option bypasses 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:: + Like --allow-empty this command is primarily for use by foreign + SCM interface scripts. It allows you to create a commit with an + empty commit message without using plumbing commands like + linkgit:git-commit-tree[1]. + +--cleanup=<mode>:: + This option determines 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 + "`# ------------------------ >8 ------------------------`" + is truncated if the message is to be edited. "`#`" can be + customized with core.commentChar. +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:: +-e:: +--edit:: The message taken from file with `-F`, command line with - `-m`, and from file with `-C` are usually used as the - commit log message unmodified. This option lets you + `-m`, and from commit object with `-C` are usually used as + the commit log message unmodified. This option lets you further edit the message taken from these sources. ---amend:: +--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. - Used to amend the tip of the current branch. Prepare the tree - object you would want to replace the latest commit as usual - (this includes the usual -i/-o and explicit paths), and the - commit log editor is seeded with the commit message from the - tip of the current branch. The commit you create replaces the - current tip -- if it was a merge, it will have the parents of - the current tip as parents -- so the current top commit is - discarded. +--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: @@ -103,16 +233,95 @@ It is a rough equivalent for: ------ 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:: +-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. --q|--quiet:: +-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. + +-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. ++ +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. ++ +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[<keyid>]:: +--gpg-sign[=<keyid>]:: + GPG-sign commits. The `keyid` argument is optional and + defaults to the committer identity; if specified, it must be + stuck to the option without a space. + +--no-gpg-sign:: + Countermand `commit.gpgSign` configuration variable that is + set to force each and every commit to be signed. + \--:: Do not interpret any more arguments as options. @@ -123,15 +332,20 @@ but can be used to amend a merge commit. these files are also staged for the next commit on top of what have been staged before. +:git-commit: 1 +include::date-formats.txt[] 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 gitlink:git-add[1]. Removal -of a file is staged with gitlink:git-rm[1]. After building the -state to be committed incrementally with these commands, `git -commit` (without any pathname parameter) is used to record what +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 reset HEAD -- <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: @@ -184,13 +398,13 @@ $ git commit this second commit would record the changes to `hello.c` and `hello.h` as expected. -After a merge (initiated by either gitlink:git-merge[1] or -gitlink:git-pull[1]) stops because of conflicts, cleanly merged +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 gitlink:git-status[1] +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 gitlink:git-add[1]: +stage the result as usual with 'git add': ------------ $ git status | grep unmerged @@ -221,37 +435,44 @@ DISCUSSION Though not required, it's a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. -Tools that turn commits into email, for example, use the first line -on the Subject: line and the rest of the commit in the body. +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.txt[] -ENVIRONMENT VARIABLES ---------------------- -The command specified by either the VISUAL or EDITOR environment -variables is used to edit the commit log message. +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. HOOKS ----- -This command can run `commit-msg`, `pre-commit`, and -`post-commit` hooks. See link:hooks.html[hooks] for more +This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`, +and `post-commit` 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 -------- -gitlink:git-add[1], -gitlink:git-rm[1], -gitlink:git-mv[1], -gitlink:git-merge[1], -gitlink:git-commit-tree[1] - -Author ------- -Written by Linus Torvalds <torvalds@osdl.org> and -Junio C Hamano <junkio@cox.net> - +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 gitlink:git[7] suite +Part of the linkgit:git[1] suite |