Merge branch 'pb/cvsimport'
[gitweb.git] / Documentation / git-commit.txt
index 2187eee4164038346ed7a3ae32f563aeb74f23f7..b4ae61ff46f4b7ff9e71e9e91a999fdc8fc17560 100644 (file)
@@ -8,40 +8,46 @@ 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] [-s] [-v] [-u]
+          [(-c | -C) <commit> | -F <file> | -m <msg> | --amend]
+          [--allow-empty] [--no-verify] [-e] [--author <author>]
+          [--cleanup=<mode>] [--] [[-i | -o ]<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:
+Use 'git commit' to store the current contents of the index in a new
+commit along with a log message describing the changes you have made.
 
-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 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 gitlink:git-rm[1] to identify content removal for the next
-   commit, again before using the 'commit' command;
+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, in which
+   case the commit will ignore changes staged in the index, and instead
+   record the current content of the listed files;
 
-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 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
+The linkgit: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].
+that, you can recover from it with linkgit:git-reset[1].
 
 
 OPTIONS
@@ -66,16 +72,39 @@ OPTIONS
        Override the author name used in the commit.  Use
        `A U Thor <author@example.com>` format.
 
--m <msg>::
+-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 at the end of the commit message.
 
 --no-verify::
-       This option bypasses the pre-commit hook.
+       This option bypasses the pre-commit and commit-msg hooks.
        See also link:hooks.html[hooks].
 
+--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
@@ -110,6 +139,19 @@ but can be used to amend a merge commit.
        as well.  This is usually not what you want unless you
        are concluding a conflicted merge.
 
+-u|--untracked-files::
+       Show all untracked files, also those in uninteresting
+       directories, in the "Untracked files:" section of commit
+       message template.  Without this option only its name and
+       a trailing slash are displayed for each untracked
+       directory.
+
+-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.
 
@@ -128,10 +170,13 @@ 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 linkgit:git-add[1].  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 +229,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 either linkgit:git-merge[1] or
+linkgit: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]
+check which paths are conflicting with linkgit:git-status[1]
 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 linkgit:git-add[1]:
 
 ------------
 $ git status | grep unmerged
@@ -226,25 +271,27 @@ 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).
 
 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 link:hooks.html[hooks] for more
 information.
 
 
 SEE ALSO
 --------
-gitlink:git-add[1],
-gitlink:git-rm[1],
-gitlink:git-mv[1],
-gitlink:git-merge[1],
-gitlink:git-commit-tree[1]
+linkgit:git-add[1],
+linkgit:git-rm[1],
+linkgit:git-mv[1],
+linkgit:git-merge[1],
+linkgit:git-commit-tree[1]
 
 Author
 ------
@@ -254,4 +301,4 @@ Junio C Hamano <junkio@cox.net>
 
 GIT
 ---
-Part of the gitlink:git[7] suite
+Part of the linkgit:git[7] suite