X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=Documentation%2Fgit-commit.txt;h=53a7bb0895036e4d66086b8c656e74588c82c38c;hb=957d6ea78fcbe71481a6f46a58768e100f7908e0;hp=0fe66f2d0c84003d285fed426181998063e86b96;hpb=0e84fb06a1022f99c96cfcd728e7bf029ef0b5e3;p=git.git diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 0fe66f2d0..53a7bb089 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -3,36 +3,58 @@ git-commit(1) NAME ---- -git-commit - Record your changes +git-commit - Record changes to the repository SYNOPSIS -------- [verse] -'git-commit' [-a] [-s] [-v] [(-c | -C) | -F | -m ] - [--no-verify] [--amend] [-e] [--author ] +'git-commit' [-a | --interactive] [-s] [-v] + [(-c | -C) | -F | -m | --amend] + [--no-verify] [-e] [--author ] [--] [[-i | -o ]...] DESCRIPTION ----------- -Updates the index file for given paths, or all modified files if -'-a' is specified, and makes a commit object. The command -VISUAL and EDITOR environment variables to edit the commit log -message. +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: -Several environment variable are used during commits. They are -documented in gitlink:git-commit-tree[1]. +1. by using gitlink:git-add[1] to incrementally "add" changes to the + next commit 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; + +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. 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 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 gitlink:git-status[1] 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 found a mistake immediately after +that, you can recover from it with gitlink:git-reset[1]. -This command can run `commit-msg`, `pre-commit`, and -`post-commit` hooks. See link:hooks.html[hooks] for more -information. OPTIONS ------- -a|--all:: - Update all paths in the index file. This flag notices - files that have been modified and deleted, but new files - you have not told git about are not affected. + 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 or -C :: Take existing commit object, and reuse the log message @@ -55,16 +77,9 @@ OPTIONS -s|--signoff:: Add Signed-off-by line at the end of the commit message. --v|--verify:: - Look for suspicious lines the commit introduces, and - abort committing if there is one. The definition of - 'suspicious lines' is currently the lines that has - trailing whitespaces, and the lines whose indentation - has a SP character immediately followed by a TAB - character. This is the default. - --n|--no-verify:: - The opposite of `--verify`. +--no-verify:: + This option bypasses the pre-commit hook. + See also link:hooks.html[hooks]. -e|--edit:: The message taken from file with `-F`, command line with @@ -95,69 +110,146 @@ but can be used to amend a merge commit. -- -i|--include:: - Instead of committing only the files specified on the - command line, update them in the index file and then - commit the whole index. This is the traditional - behavior. + 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:: - Commit only the files specified on the command line. - This format cannot be used during a merge, nor when the - index and the latest commit does not match on the - specified paths to avoid confusion. +-q|--quiet:: + Suppress commit summary message. \--:: Do not interpret any more arguments as options. ...:: - Files to be committed. The meaning of these is - different between `--include` and `--only`. Without - either, it defaults `--only` semantics. - -If you make a commit and then found a mistake immediately after -that, you can recover from it with gitlink:git-reset[1]. + 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. -Discussion +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 +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 either gitlink:git-merge[1] or +gitlink:git-pull[1]) 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] +and after fixing them manually in your working tree, you would +stage the result as usual with gitlink:git-add[1]: + +------------ +$ 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 ---------- -`git commit` without _any_ parameter commits the tree structure -recorded by the current index file. This is a whole-tree commit -even the command is invoked from a subdirectory. - -`git commit --include paths...` is equivalent to - - git update-index --remove paths... - git commit - -That is, update the specified paths to the index and then commit -the whole tree. +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. -`git commit paths...` largely bypasses the index file and -commits only the changes made to the specified paths. It has -however several safety valves to prevent confusion. +include::i18n.txt[] -. It refuses to run during a merge (i.e. when - `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users - that the traditional semantics now needs -i flag. +ENVIRONMENT VARIABLES +--------------------- +The command specified by either the VISUAL or EDITOR environment +variables is used to edit the commit log message. -. It refuses to run if named `paths...` are different in HEAD - and the index (ditto about reminding). Added paths are OK. - This is because an earlier `git diff` (not `git diff HEAD`) - would have shown the differences since the last `git - update-index paths...` to the user, and an inexperienced user - may mistakenly think that the changes between the index and - the HEAD (i.e. earlier changes made before the last `git - update-index paths...` was done) are not being committed. - -. It reads HEAD commit into a temporary index file, updates the - specified `paths...` and makes a commit. At the same time, - the real index file is also updated with the same `paths...`. +HOOKS +----- +This command can run `commit-msg`, `pre-commit`, and +`post-commit` hooks. See link:hooks.html[hooks] for more +information. -`git commit --all` updates the index file with _all_ changes to -the working tree, and makes a whole-tree commit, regardless of -which subdirectory the command is invoked in. +SEE ALSO +-------- +gitlink:git-add[1], +gitlink:git-rm[1], +gitlink:git-mv[1], +gitlink:git-merge[1], +gitlink:git-commit-tree[1] Author ------