user-manual: use pithier example commit
[gitweb.git] / Documentation / git-commit.txt
index 0b74cd708ecaa63ccc19d2db40790b315539ce8b..53a7bb0895036e4d66086b8c656e74588c82c38c 100644 (file)
@@ -3,13 +3,14 @@ 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) <commit> | -F <file> | -m <msg>]
-          [--no-verify] [--amend] [-e] [--author <author>]
+'git-commit' [-a | --interactive] [-s] [-v]
+          [(-c | -C) <commit> | -F <file> | -m <msg> | --amend]
+          [--no-verify] [-e] [--author <author>]
           [--] [[-i | -o ]<file>...]
 
 DESCRIPTION
@@ -32,7 +33,12 @@ methods:
 
 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 perform the actual commit.
+   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
@@ -72,12 +78,8 @@ OPTIONS
        Add Signed-off-by line at the end of the commit message.
 
 --no-verify::
-       By default, the command looks for suspicious lines the
-       commit introduces, and aborts 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 option turns off the check.
+       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
@@ -114,7 +116,7 @@ but can be used to amend a merge commit.
        are concluding a conflicted merge.
 
 -q|--quiet::
-       Supress commit summary message.
+       Suppress commit summary message.
 
 \--::
        Do not interpret any more arguments as options.
@@ -145,11 +147,6 @@ $ git add hello.c
 $ git commit
 ------------
 
-////////////
-We should fix 'git rm' to remove goodbye.c from both index and
-working tree for the above example.
-////////////
-
 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
@@ -223,6 +220,17 @@ 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 VARIABLES
 ---------------------
 The command specified by either the VISUAL or EDITOR environment