mirror of
https://github.com/git/git
synced 2024-08-27 03:29:21 +00:00
![Stephan Beyer](/assets/img/avatar_default.png)
The OPTIONS section of a documentation file contains a list of the options a git command accepts. Currently there are several variants to describe the case that different options (almost) do the same in the OPTIONS section. Some are: -f, --foo:: -f|--foo:: -f | --foo:: But AsciiDoc has the special form: -f:: --foo:: This patch applies this form to the documentation of the whole git suite, and removes useless em-dash prevention, so \--foo becomes --foo. Signed-off-by: Stephan Beyer <s-beyer@gmx.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
331 lines
10 KiB
Plaintext
331 lines
10 KiB
Plaintext
git-commit(1)
|
|
=============
|
|
|
|
NAME
|
|
----
|
|
git-commit - Record changes to the repository
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'git-commit' [-a | --interactive] [-s] [-v] [-u] [--amend]
|
|
[(-c | -C) <commit>] [-F <file> | -m <msg>]
|
|
[--allow-empty] [--no-verify] [-e] [--author=<author>]
|
|
[--cleanup=<mode>] [--] [[-i | -o ]<file>...]
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
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.
|
|
|
|
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 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;
|
|
|
|
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;
|
|
|
|
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 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 linkgit:git-reset[1].
|
|
|
|
|
|
OPTIONS
|
|
-------
|
|
-a::
|
|
--all::
|
|
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 <commit>::
|
|
--reuse-message=<commit>::
|
|
Take an existing commit object, and reuse the log message
|
|
and the authorship information (including the timestamp)
|
|
when creating the commit.
|
|
|
|
-c <commit>::
|
|
--reedit-message=<commit>::
|
|
Like '-C', but with '-c' the editor is invoked, so that
|
|
the user can further edit the commit message.
|
|
|
|
-F <file>::
|
|
--file=<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>::
|
|
--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.
|
|
|
|
-n::
|
|
--no-verify::
|
|
This option bypasses the pre-commit and commit-msg hooks.
|
|
See also linkgit:githooks[5][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
|
|
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::
|
|
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::
|
|
Make a commit only from the paths specified on the
|
|
command line, disregarding any contents that have been
|
|
staged so far. This is the default mode of operation of
|
|
'git commit' if any paths are given on the command line,
|
|
in which case this option can be omitted.
|
|
If this option is specified together with '--amend', then
|
|
no paths need be specified, which can be used to amend
|
|
the last commit without committing changes that have
|
|
already been staged.
|
|
|
|
-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.
|
|
|
|
\--::
|
|
Do not interpret any more arguments as options.
|
|
|
|
<file>...::
|
|
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.
|
|
|
|
|
|
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 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:
|
|
|
|
------------
|
|
$ 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 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 linkgit:git-status[1]
|
|
and after fixing them manually in your working tree, you would
|
|
stage the result as usual with linkgit: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
|
|
----------
|
|
|
|
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 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`, `prepare-commit-msg`, `pre-commit`,
|
|
and `post-commit` hooks. See linkgit:githooks[5][hooks] for more
|
|
information.
|
|
|
|
|
|
SEE ALSO
|
|
--------
|
|
linkgit:git-add[1],
|
|
linkgit:git-rm[1],
|
|
linkgit:git-mv[1],
|
|
linkgit:git-merge[1],
|
|
linkgit:git-commit-tree[1]
|
|
|
|
Author
|
|
------
|
|
Written by Linus Torvalds <torvalds@osdl.org> and
|
|
Junio C Hamano <junkio@cox.net>
|
|
|
|
|
|
GIT
|
|
---
|
|
Part of the linkgit:git[1] suite
|