user-manual: use pithier example commit
[gitweb.git] / Documentation / git-commit.txt
index 0fe66f2d0c84003d285fed426181998063e86b96..53a7bb0895036e4d66086b8c656e74588c82c38c 100644 (file)
@@ -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) <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
 -----------
-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 <commit>::
        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.
 
 <file>...::
-       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
 ------