git-commit(1)

NAME#

git-commit - Record changes to the repository

SYNOPSIS#

git commit\n [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
\n
           [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>]
\n
           [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
\n
           [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
\n
           [--date=<date>] [--cleanup=<mode>] [--[no-]status]
\n
           [-i | -o] [--pathspec-from-file=<file> [--pathspec-file-nul]]
\n
           [(--trailer <token>[(=|:)<value>])...] [-S[<keyid>]]
\n
           [--] [<pathspec>...]

DESCRIPTION#

Create a new commit containing the current contents of the index and the given log message describing the changes. The new commit is a direct child of HEAD, usually the tip of the current branch, and the branch is updated to point to it (unless no branch is associated with the working tree, in which case HEAD is "detached" as described in git-checkout(1)).

The content to be committed can be specified in several ways:

The --dry-run option 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 (options and paths).

If you make a commit and then find a mistake immediately after that, you can recover from it with git reset.

OPTIONS#

-a, --all

-p, --patch

-C <commit>, --reuse-message=<commit>

-c <commit>, --reedit-message=<commit>

--fixup=[(amend|reword):]<commit>

The commit created by plain --fixup=<commit> has a subject composed of "fixup!" followed by the subject line from <commit>, and is recognized specially by git rebase --autosquash. The -m option may be used to supplement the log message of the created commit, but the additional commentary will be thrown away once the "fixup!" commit is squashed into <commit> by git rebase --autosquash.

The commit created by --fixup=amend:<commit> is similar but its subject is instead prefixed with "amend!". The log message of <commit> is copied into the log message of the "amend!" commit and opened in an editor so it can be refined. When git rebase --autosquash squashes the "amend!" commit into <commit>, the log message of <commit> is replaced by the refined log message from the "amend!" commit. It is an error for the "amend!" commit’s log message to be empty unless --allow-empty-message is specified.

--fixup=reword:<commit> is shorthand for --fixup=amend:<commit> --only. It creates an "amend!" commit with only a log message (ignoring any changes staged in the index). When squashed by git rebase --autosquash, it replaces the log message of <commit> without making any other changes.

Neither "fixup!" nor "amend!" commits change authorship of <commit> when applied by git rebase --autosquash. See git-rebase(1) for details.

--squash=<commit>

--reset-author

--short

--branch

--porcelain

--long

-z, --null

-F <file>, --file=<file>

--author=<author>

--date=<date>

-m <msg>, --message=<msg>

The -m option is mutually exclusive with -c, -C, and -F.

-t <file>, --template=<file>

-s, --signoff, --no-signoff

The --no-signoff option can be used to countermand an earlier --signoff option on the command line.

--trailer <token>[(=|:)<value>]

-n, --[no-]verify

--allow-empty

--allow-empty-message

--cleanup=<mode>

strip

whitespace

verbatim

scissors

# ------------------------ >8 ------------------------

default

The default can be changed by the commit.cleanup configuration variable (see git-config(1)).

-e, --edit

--no-edit

--amend

It is a rough equivalent for:

\n
        $ git reset --soft HEAD^
\n
        $ ... do something else to come up with the right tree ...
\n
        $ git commit -c ORIG_HEAD

but can be used to amend a merge commit.

You should understand the implications of rewriting history if you amend a commit that has already been published. (See the "RECOVERING FROM UPSTREAM REBASE" section in git-rebase(1).)

--no-post-rewrite

-i, --include

-o, --only

--pathspec-from-file=<file>

--pathspec-file-nul

-u[<mode>], --untracked-files[=<mode>]

The mode parameter is optional (defaults to all), and is used to specify the handling of untracked files; when -u is not used, the default is normal, i.e. show untracked files and directories.

The possible options are:

All usual spellings for Boolean value true are taken as normal and false as no. The default can be changed using the status.showUntrackedFiles configuration variable documented in git-config(1).

-v, --verbose

If specified twice, show in addition the unified diff between what would be committed and the worktree files, i.e. the unstaged changes to tracked files.

-q, --quiet

--dry-run

--status

--no-status

-S[<keyid>], --gpg-sign[=<keyid>], --no-gpg-sign

--

<pathspec>...

For more details, see the pathspec entry in gitglossary(7).

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 git add. A file can be reverted back, only in the index but not in the working tree, to that of the last commit with git restore --staged <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 git merge or git pull) 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 git status and after fixing them manually in your working tree, you would stage the result as usual with git add:

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

COMMIT INFORMATION#

Author and committer information is taken from the following environment variables, if set:

GIT_AUTHOR_NAME
GIT_AUTHOR_EMAIL
GIT_AUTHOR_DATE
GIT_COMMITTER_NAME
GIT_COMMITTER_EMAIL
GIT_COMMITTER_DATE

(nb "<", ">" and "\n"s are stripped)

The author and committer names are by convention some form of a personal name (that is, the name by which other humans refer to you), although Git does not enforce or require any particular form. Arbitrary Unicode may be used, subject to the constraints listed above. This name has no effect on authentication; for that, see the credential.username variable in git-config(1).

In case (some of) these environment variables are not set, the information is taken from the configuration items user.name and user.email, or, if not present, the environment variable EMAIL, or, if that is not set, system user name and the hostname used for outgoing mail (taken from /etc/mailname and falling back to the fully qualified hostname when that file does not exist).

The author.name and committer.name and their corresponding email options override user.name and user.email if set and are overridden themselves by the environment variables.

The typical usage is to set just the user.name and user.email variables; the other options are provided for more complex use cases.

DATE FORMATS#

The GIT_AUTHOR_DATE and GIT_COMMITTER_DATE environment variables support the following date formats:

Git internal format

RFC 2822

ISO 8601

In addition to recognizing all date formats above, the --date option will also try to make sense of other, more human-centric date formats, such as relative dates like "yesterday" or "last Friday at noon".

DISCUSSION#

Though not required, it’s a good idea to begin the commit message with a single short (no more than 50 characters) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. For example, git-format-patch(1) turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body.

Git is to some extent character encoding agnostic.

Note that Git at the core level treats path names simply as sequences of non-NUL bytes, there are no path name encoding conversions (except on Mac and Windows). Therefore, using non-ASCII path names will mostly work even on platforms and file systems that use legacy extended ASCII encodings. However, repositories created on such systems will not work properly on UTF-8-based systems (e.g. Linux, Mac, Windows) and vice versa. Additionally, many Git-based tools simply assume path names to be UTF-8 and will fail to display other encodings correctly.

Although we encourage that the commit log messages are encoded in UTF-8, both the core and Git Porcelain are designed not to force UTF-8 on projects. If all participants of a particular project find it more convenient to use legacy encodings, Git does not forbid it. However, there are a few things to keep in mind.

[i18n]
\n
        commitEncoding = ISO-8859-1

Commit objects created with the above setting record the value of i18n.commitEncoding in their encoding header. This is to help other people who look at them later. Lack of this header implies that the commit log message is encoded in UTF-8.

[i18n]
\n
        logOutputEncoding = ISO-8859-1

If you do not have this configuration variable, the value of i18n.commitEncoding is used instead.

Note that we deliberately chose not to re-code the commit log message when a commit is made to force UTF-8 at the commit object level, because re-coding to UTF-8 is not necessarily a reversible operation.

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). See git-var(1) for details.

Everything above this line in this section isn’t included from the git-config(1) documentation. The content that follows is the same as what’s found there:

commit.cleanup

commit.gpgSign

commit.status

commit.template

commit.verbose

HOOKS#

This command can run commit-msg, prepare-commit-msg, pre-commit, post-commit and post-rewrite hooks. See githooks(5) for more information.

FILES#

$GIT_DIR/COMMIT_EDITMSG

SEE ALSO#

git-add(1), git-rm(1), git-mv(1), git-merge(1), git-commit-tree(1)

GIT#

Part of the git(1) suite