mirror of
https://github.com/git/git
synced 2024-08-25 02:35:46 +00:00
![Paolo Bonzini](/assets/img/avatar_default.png)
The prepare-commit-msg hook is run whenever a "fresh" commit message is prepared, just before it is shown in the editor (if it is). Its purpose is to modify the commit message in-place. It takes one to three parameters. The first is the name of the file that the commit log message. The second is the source of the commit message, and can be: "message" (if a -m or -F option was given); "template" (if a -t option was given or the configuration option commit.template is set); "merge" (if the commit is a merge or a .git/MERGE_MSG file exists); "squash" (if a .git/SQUASH_MSG file exists); or "commit", followed by a commit SHA1 as the third parameter (if a -c, -C or --amend option was given). If its exit status is non-zero, git-commit will abort. The hook is not suppressed by the --no-verify option, so it should not be used as a replacement for the pre-commit hook. The sample prepare-commit-msg comments out the `Conflicts:` part of a merge's commit message; other examples are commented out, including adding a Signed-off-by line at the bottom of the commit messsage, that the user can then edit or discard altogether. Signed-off-by: Paolo Bonzini <bonzini@gnu.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
305 lines
9.9 KiB
Plaintext
305 lines
9.9 KiB
Plaintext
git-commit(1)
|
|
=============
|
|
|
|
NAME
|
|
----
|
|
git-commit - Record changes to the repository
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
'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' 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 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>|--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 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
|
|
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.
|
|
|
|
-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 link:hooks.html[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[7] suite
|