Several trivial documentation touch ups.

[thirdparty/git.git] / Documentation / git-commit.txt

git-commit(1)
=============

NAME
----
git-commit - Record your changes

SYNOPSIS
--------
[verse]
'git-commit' [-a] [-s] [-v] [(-c | -C) <commit> | -F <file> | -m <msg>]
	   [--no-verify] [--amend] [-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.

Several environment variable are used during commits.  They are
documented in gitlink:git-commit-tree[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.

-c or -C <commit>::
	Take existing commit object, and reuse the log message
	and the authorship information (including the timestamp)
	when creating the commit.  With '-C', the editor is not
	invoked; with '-c' the user can further edit the commit
	message.

-F <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.  Use
	`A U Thor <author@example.com>` format.

-m <msg>::
	Use the given <msg> as the commit message.

-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`.

-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.
--

-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
	behaviour.

-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.

--::
	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].


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.

`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.

. 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.

. 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...`.

`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.


Author
------
Written by Linus Torvalds <torvalds@osdl.org> and
Junio C Hamano <junkio@cox.net>


GIT
---
Part of the gitlink:git[7] suite