diff options
Diffstat (limited to 'Documentation/git-commit.txt')
| -rw-r--r-- | Documentation/git-commit.txt | 346 |
1 files changed, 346 insertions, 0 deletions
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt new file mode 100644 index 0000000000..2e62165fa9 --- /dev/null +++ b/Documentation/git-commit.txt @@ -0,0 +1,346 @@ +git-commit(1) +============= + +NAME +---- +git-commit - Record changes to the repository + +SYNOPSIS +-------- +[verse] +'git commit' [-a | --interactive] [-s] [-v] [-u<mode>] [--amend] + [(-c | -C) <commit>] [-F <file> | -m <msg>] + [--allow-empty] [--no-verify] [-e] [--author=<author>] + [--cleanup=<mode>] [--] [[-i | -o ]<file>...] + +DESCRIPTION +----------- +Stores the current contents of the index in a new commit along +with a log message from the user describing the changes. + +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 '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; + +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 switch with the 'commit' command to decide one + by one which files should be part of the commit, before finalizing the + operation. Currently, this is done by invoking 'git-add --interactive'. + +The 'git-status' command 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. + +If you make a commit and then find a mistake immediately after +that, you can recover from it with 'git-reset'. + + +OPTIONS +------- +-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. + +-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. + +-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. You can use the + standard `A U Thor <author@example.com>` format. Otherwise, + an existing commit that matches the given string and its author + name is used. + +-m <msg>:: +--message=<msg>:: + Use the given <msg> as the commit message. + +-t <file>:: +--template=<file>:: + Use the contents of the given file as the initial version + of the commit message. The editor is invoked and you can + make subsequent changes. If a message is specified using + the `-m` or `-F` options, this option has no effect. This + overrides the `commit.template` configuration variable. + +-s:: +--signoff:: + Add Signed-off-by line by the commiter at the end of the commit + log message. + +-n:: +--no-verify:: + 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. + +--cleanup=<mode>:: + This option sets how the commit message is cleaned up. + The '<mode>' can be one of 'verbatim', 'whitespace', 'strip', + and 'default'. The 'default' mode will strip leading and + trailing empty lines and #commentary from the commit message + only if the message is to be edited. Otherwise only whitespace + removed. The 'verbatim' mode does not change message at all, + 'whitespace' removes just leading/trailing whitespace lines + and 'strip' removes both whitespace and commentary. + +-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 + further edit the message taken from these sources. + +--amend:: + 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. ++ +-- +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].) + +-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 only from the paths specified on the + command line, disregarding any contents that have been + staged so far. 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 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 (Default: 'all'). ++ +The mode parameter is optional, and is used to specify +the handling of untracked files. The possible options are: ++ +-- + - 'no' - Show no untracked files + - 'normal' - Shows untracked files and directories + - 'all' - Also shows individual files in untracked directories. +-- ++ +See linkgit:git-config[1] for configuration variable +used to change the default for when the option is not +specified. + +-v:: +--verbose:: + Show unified diff between the HEAD commit and what + would be committed at the bottom of the commit message + template. Note that this diff output doesn't have its + lines prefixed with '#'. + +-q:: +--quiet:: + Suppress commit summary message. + +\--:: + Do not interpret any more arguments as options. + +<file>...:: + When files are given on the command line, the command + commits the contents of the named files, without + recording the changes already staged. The contents of + these files are also staged for the next commit on top + of what have been staged before. + + +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 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: + +------------ +$ 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). + + +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. + +include::i18n.txt[] + +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). + +HOOKS +----- +This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`, +and `post-commit` hooks. See linkgit:githooks[5] for more +information. + + +SEE ALSO +-------- +linkgit:git-add[1], +linkgit:git-rm[1], +linkgit:git-mv[1], +linkgit:git-merge[1], +linkgit:git-commit-tree[1] + +Author +------ +Written by Linus Torvalds <torvalds@osdl.org> and +Junio C Hamano <gitster@pobox.com> + + +GIT +--- +Part of the linkgit:git[1] suite |