G.3. Git Command Reference

TortoiseGit

G.3. Git Command Reference

G.3.1. git(1)

NAME

git - the stupid content tracker

SYNOPSIS

git [--version] [--help] [-C <path>] [-c <name>=<value>]
    [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
    [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
    [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
    <command> [<args>]

DESCRIPTION

Git is a fast, scalable, distributed revision control system with an unusually rich command set that provides both high-level operations and full access to internals.

See Section G.2.1, “gittutorial(7)” to get started, then see Section G.2.5, “giteveryday(7)” for a useful minimum set of commands. The Git User's Manual has a more in-depth introduction.

After you mastered the basic concepts, you can come back to this page to learn what commands Git offers. You can learn more about individual Git commands with "git help command". Section G.4.1, “gitcli(7)” manual page gives you an overview of the command-line command syntax.

Formatted and hyperlinked version of the latest Git documentation can be viewed at http://git-htmldocs.googlecode.com/git/git.html.

OPTIONS

--version
Prints the Git suite version that the git program came from.
--help

Prints the synopsis and a list of the most commonly used commands. If the option --all or -a is given then all available commands are printed. If a Git command is named this option will bring up the manual page for that command.

Other options are available to control how the manual page is displayed. See Section G.3.58, “git-help(1)” for more information, because git --help ... is converted internally into git help ....

-C <path>

Run as if git was started in <path> instead of the current working directory. When multiple -C options are given, each subsequent non-absolute -C <path> is interpreted relative to the preceding -C <path>.

This option affects options that expect path name like --git-dir and --work-tree in that their interpretations of the path names would be made relative to the working directory caused by the -C option. For example the following invocations are equivalent:

git --git-dir=a.git --work-tree=b -C c status
git --git-dir=c/a.git --work-tree=c/b status
-c <name>=<value>

Pass a configuration parameter to the command. The value given will override values from configuration files. The <name> is expected in the same format as listed by git config (subkeys separated by dots).

Note that omitting the = in git -c foo.bar ... is allowed and sets foo.bar to the boolean true value (just like [foo]bar would in a config file). Including the equals but with an empty value (like git -c foo.bar= ...) sets foo.bar to the empty string.

--exec-path[=<path>]
Path to wherever your core Git programs are installed. This can also be controlled by setting the GIT_EXEC_PATH environment variable. If no path is given, git will print the current setting and then exit.
--html-path
Print the path, without trailing slash, where Git's HTML documentation is installed and exit.
--man-path
Print the manpath (see man(1)) for the man pages for this version of Git and exit.
--info-path
Print the path where the Info files documenting this version of Git are installed and exit.
-p , --paginate
Pipe all output into less (or if set, $PAGER) if standard output is a terminal. This overrides the pager.<cmd> configuration options (see the "Configuration Mechanism" section below).
--no-pager
Do not pipe Git output into a pager.
--git-dir=<path>
Set the path to the repository. This can also be controlled by setting the GIT_DIR environment variable. It can be an absolute path or relative path to current working directory.
--work-tree=<path>
Set the path to the working tree. It can be an absolute path or a path relative to the current working directory. This can also be controlled by setting the GIT_WORK_TREE environment variable and the core.worktree configuration variable (see core.worktree in Section G.3.27, “git-config(1)” for a more detailed discussion).
--namespace=<path>
Set the Git namespace. See Section G.4.9, “gitnamespaces(7)” for more details. Equivalent to setting the GIT_NAMESPACE environment variable.
--bare
Treat the repository as a bare repository. If GIT_DIR environment is not set, it is set to the current working directory.
--no-replace-objects
Do not use replacement refs to replace Git objects. See Section G.3.108, “git-replace(1)” for more information.
--literal-pathspecs
Treat pathspecs literally (i.e. no globbing, no pathspec magic). This is equivalent to setting the GIT_LITERAL_PATHSPECS environment variable to 1.
--glob-pathspecs
Add "glob" magic to all pathspec. This is equivalent to setting the GIT_GLOB_PATHSPECS environment variable to 1. Disabling globbing on individual pathspecs can be done using pathspec magic ":(literal)"
--noglob-pathspecs
Add "literal" magic to all pathspec. This is equivalent to setting the GIT_NOGLOB_PATHSPECS environment variable to 1. Enabling globbing on individual pathspecs can be done using pathspec magic ":(glob)"
--icase-pathspecs
Add "icase" magic to all pathspec. This is equivalent to setting the GIT_ICASE_PATHSPECS environment variable to 1.

GIT COMMANDS

We divide Git into high level ("porcelain") commands and low level ("plumbing") commands.

High-level commands (porcelain)

We separate the porcelain commands into the main commands and some ancillary user utilities.

1. Main porcelain commands

Section G.3.2, “git-add(1)”
Add file contents to the index.
Section G.3.3, “git-am(1)”
Apply a series of patches from a mailbox.
Section G.3.7, “git-archive(1)”
Create an archive of files from a named tree.
Section G.3.8, “git-bisect(1)”
Use binary search to find the commit that introduced a bug.
Section G.3.10, “git-branch(1)”
List, create, or delete branches.
Section G.3.11, “git-bundle(1)”
Move objects and refs by archive.
Section G.3.18, “git-checkout(1)”
Switch branches or restore working tree files.
Section G.3.19, “git-cherry-pick(1)”
Apply the changes introduced by some existing commits.
Section G.3.21, “git-citool(1)”
Graphical alternative to git-commit.
Section G.3.22, “git-clean(1)”
Remove untracked files from the working tree.
Section G.3.23, “git-clone(1)”
Clone a repository into a new directory.
Section G.3.26, “git-commit(1)”
Record changes to the repository.
Section G.3.37, “git-describe(1)”
Describe a commit using the most recent tag reachable from it.
Section G.3.41, “git-diff(1)”
Show changes between commits, commit and working tree, etc.
Section G.3.46, “git-fetch(1)”
Download objects and refs from another repository.
Section G.3.50, “git-format-patch(1)”
Prepare patches for e-mail submission.
Section G.3.53, “git-gc(1)”
Cleanup unnecessary files and optimize the local repository.
Section G.3.55, “git-grep(1)”
Print lines matching a pattern.
Section G.3.56, “git-gui(1)”
A portable graphical interface to Git.
Section G.3.65, “git-init(1)”
Create an empty Git repository or reinitialize an existing one.
Section G.3.68, “git-log(1)”
Show commit logs.
Section G.3.79, “git-merge(1)”
Join two or more development histories together.
Section G.3.84, “git-mv(1)”
Move or rename a file, a directory, or a symlink.
Section G.3.86, “git-notes(1)”
Add or inspect object notes.
Section G.3.95, “git-pull(1)”
Fetch from and integrate with another repository or a local branch.
Section G.3.96, “git-push(1)”
Update remote refs along with associated objects.
Section G.3.99, “git-rebase(1)”
Reapply commits on top of another base tip.
Section G.3.111, “git-reset(1)”
Reset current HEAD to the specified state.
Section G.3.114, “git-revert(1)”
Revert some existing commits.
Section G.3.115, “git-rm(1)”
Remove files from the working tree and from the index.
Section G.3.122, “git-shortlog(1)”
Summarize git log output.
Section G.3.126, “git-show(1)”
Show various types of objects.
Section G.3.128, “git-stash(1)”
Stash the changes in a dirty working directory away.
Section G.3.129, “git-status(1)”
Show the working tree status.
Section G.3.131, “git-submodule(1)”
Initialize, update or inspect submodules.
Section G.3.134, “git-tag(1)”
Create, list, delete or verify a tag object signed with GPG.
Section G.3.148, “git-worktree(1)”
Manage multiple working trees.
Section G.4.7, “gitk(1)”
The Git repository browser.

2. Ancillary Commands

Manipulators:

Section G.3.27, “git-config(1)”
Get and set repository or global options.
Section G.3.43, “git-fast-export(1)”
Git data exporter.
Section G.3.44, “git-fast-import(1)”
Backend for fast Git data importers.
Section G.3.47, “git-filter-branch(1)”
Rewrite branches.
Section G.3.81, “git-mergetool(1)”
Run merge conflict resolution tools to resolve merge conflicts.
Section G.3.90, “git-pack-refs(1)”
Pack heads and tags for efficient repository access.
Section G.3.94, “git-prune(1)”
Prune all unreachable objects from the object database.
Section G.3.101, “git-reflog(1)”
Manage reflog information.
Section G.3.102, “git-relink(1)”
Hardlink common objects in local repositories.
Section G.3.106, “git-remote(1)”
Manage set of tracked repositories.
Section G.3.107, “git-repack(1)”
Pack unpacked objects in a repository.
Section G.3.108, “git-replace(1)”
Create, list, delete refs to replace objects.

Interrogators:

Section G.3.4, “git-annotate(1)”
Annotate file lines with commit information.
Section G.3.9, “git-blame(1)”
Show what revision and author last modified each line of a file.
Section G.3.20, “git-cherry(1)”
Find commits yet to be applied to upstream.
Section G.3.28, “git-count-objects(1)”
Count unpacked number of objects and their disk consumption.
Section G.3.42, “git-difftool(1)”
Show changes using common diff tools.
Section G.3.52, “git-fsck(1)”
Verifies the connectivity and validity of the objects in the database.
Section G.3.54, “git-get-tar-commit-id(1)”
Extract commit ID from an archive created using git-archive.
Section G.3.58, “git-help(1)”
Display help information about Git.
Section G.3.66, “git-instaweb(1)”
Instantly browse your working repository in gitweb.
Section G.3.78, “git-merge-tree(1)”
Show three-way merge without touching index.
Section G.3.110, “git-rerere(1)”
Reuse recorded resolution of conflicted merges.
Section G.3.113, “git-rev-parse(1)”
Pick out and massage parameters.
Section G.3.123, “git-show-branch(1)”
Show branches and their commits.
Section G.3.143, “git-verify-commit(1)”
Check the GPG signature of commits.
Section G.3.145, “git-verify-tag(1)”
Check the GPG signature of tags.
Section G.3.147, “git-whatchanged(1)”
Show logs with difference each commit introduces.
Section G.4.13, “gitweb(1)”
Git web interface (web frontend to Git repositories).

3. Interacting with Others

These commands are to interact with foreign SCM and with other people via patch over e-mail.

Section G.3.6, “git-archimport(1)”
Import an Arch repository into Git.
Section G.3.33, “git-cvsexportcommit(1)”
Export a single commit to a CVS checkout.
Section G.3.34, “git-cvsimport(1)”
Salvage your data out of another SCM people love to hate.
Section G.3.35, “git-cvsserver(1)”
A CVS server emulator for Git.
Section G.3.62, “git-imap-send(1)”
Send a collection of patches from stdin to an IMAP folder.
Section G.3.87, “git-p4(1)”
Import from and submit to Perforce repositories.
Section G.3.97, “git-quiltimport(1)”
Applies a quilt patchset onto the current branch.
Section G.3.109, “git-request-pull(1)”
Generates a summary of pending changes.
Section G.3.116, “git-send-email(1)”
Send a collection of patches as emails.
Section G.3.132, “git-svn(1)”
Bidirectional operation between a Subversion repository and Git.

Low-level commands (plumbing)

Although Git includes its own porcelain layer, its low-level commands are sufficient to support development of alternative porcelains. Developers of such porcelains might start by reading about Section G.3.137, “git-update-index(1)” and Section G.3.98, “git-read-tree(1)”.

The interface (input, output, set of options and the semantics) to these low-level commands are meant to be a lot more stable than Porcelain level commands, because these commands are primarily for scripted use. The interface to Porcelain commands on the other hand are subject to change in order to improve the end user experience.

The following description divides the low-level commands into commands that manipulate objects (in the repository, index, and working tree), commands that interrogate and compare objects, and commands that move objects and references between repositories.

1. Manipulation commands

Section G.3.5, “git-apply(1)”
Apply a patch to files and/or to the index.
Section G.3.17, “git-checkout-index(1)”
Copy files from the index to the working tree.
Section G.3.25, “git-commit-tree(1)”
Create a new commit object.
Section G.3.57, “git-hash-object(1)”
Compute object ID and optionally creates a blob from a file.
Section G.3.63, “git-index-pack(1)”
Build pack index file for an existing packed archive.
Section G.3.75, “git-merge-file(1)”
Run a three-way file merge.
Section G.3.76, “git-merge-index(1)”
Run a merge for files needing merging.
Section G.3.82, “git-mktag(1)”
Creates a tag object.
Section G.3.83, “git-mktree(1)”
Build a tree-object from ls-tree formatted text.
Section G.3.88, “git-pack-objects(1)”
Create a packed archive of objects.
Section G.3.93, “git-prune-packed(1)”
Remove extra objects that are already in pack files.
Section G.3.98, “git-read-tree(1)”
Reads tree information into the index.
Section G.3.133, “git-symbolic-ref(1)”
Read, modify and delete symbolic refs.
Section G.3.136, “git-unpack-objects(1)”
Unpack objects from a packed archive.
Section G.3.137, “git-update-index(1)”
Register file contents in the working tree to the index.
Section G.3.138, “git-update-ref(1)”
Update the object name stored in a ref safely.
Section G.3.149, “git-write-tree(1)”
Create a tree object from the current index.

2. Interrogation commands

Section G.3.12, “git-cat-file(1)”
Provide content or type and size information for repository objects.
Section G.3.38, “git-diff-files(1)”
Compares files in the working tree and the index.
Section G.3.39, “git-diff-index(1)”
Compare a tree to the working tree or index.
Section G.3.40, “git-diff-tree(1)”
Compares the content and mode of blobs found via two tree objects.
Section G.3.49, “git-for-each-ref(1)”
Output information on each ref.
Section G.3.69, “git-ls-files(1)”
Show information about files in the index and the working tree.
Section G.3.70, “git-ls-remote(1)”
List references in a remote repository.
Section G.3.71, “git-ls-tree(1)”
List the contents of a tree object.
Section G.3.74, “git-merge-base(1)”
Find as good common ancestors as possible for a merge.
Section G.3.85, “git-name-rev(1)”
Find symbolic names for given revs.
Section G.3.89, “git-pack-redundant(1)”
Find redundant pack files.
Section G.3.112, “git-rev-list(1)”
Lists commit objects in reverse chronological order.
Section G.3.124, “git-show-index(1)”
Show packed archive index.
Section G.3.125, “git-show-ref(1)”
List references in a local repository.
Section G.3.135, “git-unpack-file(1)”
Creates a temporary file with a blob's contents.
Section G.3.142, “git-var(1)”
Show a Git logical variable.
Section G.3.144, “git-verify-pack(1)”
Validate packed Git archive files.

In general, the interrogate commands do not touch the files in the working tree.

3. Synching repositories

Section G.3.36, “git-daemon(1)”
A really simple server for Git repositories.
Section G.3.45, “git-fetch-pack(1)”
Receive missing objects from another repository.
Section G.3.59, “git-http-backend(1)”
Server side implementation of Git over HTTP.
Section G.3.117, “git-send-pack(1)”
Push objects over Git protocol to another repository.
Section G.3.139, “git-update-server-info(1)”
Update auxiliary info file to help dumb servers.

The following are helper commands used by the above; end users typically do not use them directly.

Section G.3.60, “git-http-fetch(1)”
Download from a remote Git repository via HTTP.
Section G.3.61, “git-http-push(1)”
Push objects over HTTP/DAV to another repository.
Section G.3.91, “git-parse-remote(1)”
Routines to help parsing remote repository access parameters.
Section G.3.100, “git-receive-pack(1)”
Receive what is pushed into the repository.
Section G.3.121, “git-shell(1)”
Restricted login shell for Git-only SSH access.
Section G.3.140, “git-upload-archive(1)”
Send archive back to git-archive.
Section G.3.141, “git-upload-pack(1)”
Send objects packed back to git-fetch-pack.

4. Internal helper commands

These are internal helper commands used by other commands; end users typically do not use them directly.

Section G.3.13, “git-check-attr(1)”
Display gitattributes information.
Section G.3.14, “git-check-ignore(1)”
Debug gitignore / exclude files.
Section G.3.15, “git-check-mailmap(1)”
Show canonical names and email addresses of contacts.
Section G.3.16, “git-check-ref-format(1)”
Ensures that a reference name is well formed.
Section G.3.24, “git-column(1)”
Display data in columns.
Section G.3.29, “git-credential(1)”
Retrieve and store user credentials.
Section G.3.31, “git-credential-cache(1)”
Helper to temporarily store passwords in memory.
Section G.3.32, “git-credential-store(1)”
Helper to store credentials on disk.
Section G.3.48, “git-fmt-merge-msg(1)”
Produce a merge commit message.
Section G.3.67, “git-interpret-trailers(1)”
help add structured information into commit messages.
Section G.3.72, “git-mailinfo(1)”
Extracts patch and authorship from a single e-mail message.
Section G.3.73, “git-mailsplit(1)”
Simple UNIX mbox splitter program.
Section G.3.77, “git-merge-one-file(1)”
The standard helper program to use with git-merge-index.
Section G.3.92, “git-patch-id(1)”
Compute unique ID for a patch.
Section G.3.119, “git-sh-i18n(1)”
Git's i18n setup code for shell scripts.
Section G.3.120, “git-sh-setup(1)”
Common Git shell script setup code.
Section G.3.130, “git-stripspace(1)”
Remove unnecessary whitespace.

Configuration Mechanism

Git uses a simple text format to store customizations that are per repository and are per user. Such a configuration file may look like this:

#
# A '#' or ';' character indicates a comment.
#

; core variables
[core]
        ; Don't trust file modes
        filemode = false

; user identity
[user]
        name = "Junio C Hamano"
        email = "[email protected]"

Various commands read from the configuration file and adjust their operation accordingly. See Section G.3.27, “git-config(1)” for a list and more details about the configuration mechanism.

Identifier Terminology

<object>
Indicates the object name for any type of object.
<blob>
Indicates a blob object name.
<tree>
Indicates a tree object name.
<commit>
Indicates a commit object name.
<tree-ish>
Indicates a tree, commit or tag object name. A command that takes a <tree-ish> argument ultimately wants to operate on a <tree> object but automatically dereferences <commit> and <tag> objects that point at a <tree>.
<commit-ish>
Indicates a commit or tag object name. A command that takes a <commit-ish> argument ultimately wants to operate on a <commit> object but automatically dereferences <tag> objects that point at a <commit>.
<type>
Indicates that an object type is required. Currently one of: blob, tree, commit, or tag.
<file>
Indicates a filename - almost always relative to the root of the tree structure GIT_INDEX_FILE describes.

Symbolic Identifiers

Any Git command accepting any <object> can also use the following symbolic notation:

HEAD
indicates the head of the current branch.
<tag>
a valid tag name (i.e. a refs/tags/<tag> reference).
<head>
a valid head name (i.e. a refs/heads/<head> reference).

For a more complete list of ways to spell object names, see "SPECIFYING REVISIONS" section in Section G.4.12, “gitrevisions(7)”.

File/Directory Structure

Please see the Section G.4.11, “gitrepository-layout(5)” document.

Read Section G.4.6, “githooks(5)” for more details about each hook.

Higher level SCMs may provide and manage additional information in the $GIT_DIR.

Terminology

Please see Section G.4.16, “gitglossary(7)”.

Environment Variables

Various Git commands use the following environment variables:

1. The Git Repository

These environment variables apply to all core Git commands. Nb: it is worth noting that they may be used/overridden by SCMS sitting above Git so take care if using a foreign front-end.

GIT_INDEX_FILE
This environment allows the specification of an alternate index file. If not specified, the default of $GIT_DIR/index is used.
GIT_INDEX_VERSION
This environment variable allows the specification of an index version for new repositories. It won't affect existing index files. By default index file version 2 or 3 is used. See Section G.3.137, “git-update-index(1)” for more information.
GIT_OBJECT_DIRECTORY
If the object storage directory is specified via this environment variable then the sha1 directories are created underneath - otherwise the default $GIT_DIR/objects directory is used.
GIT_ALTERNATE_OBJECT_DIRECTORIES
Due to the immutable nature of Git objects, old objects can be archived into shared, read-only directories. This variable specifies a ":" separated (on Windows ";" separated) list of Git object directories which can be used to search for Git objects. New objects will not be written to these directories.
GIT_DIR
If the GIT_DIR environment variable is set then it specifies a path to use instead of the default .git for the base of the repository. The --git-dir command-line option also sets this value.
GIT_WORK_TREE
Set the path to the root of the working tree. This can also be controlled by the --work-tree command-line option and the core.worktree configuration variable.
GIT_NAMESPACE
Set the Git namespace; see Section G.4.9, “gitnamespaces(7)” for details. The --namespace command-line option also sets this value.
GIT_CEILING_DIRECTORIES
This should be a colon-separated list of absolute paths. If set, it is a list of directories that Git should not chdir up into while looking for a repository directory (useful for excluding slow-loading network directories). It will not exclude the current working directory or a GIT_DIR set on the command line or in the environment. Normally, Git has to read the entries in this list and resolve any symlink that might be present in order to compare them with the current directory. However, if even this access is slow, you can add an empty entry to the list to tell Git that the subsequent entries are not symlinks and needn't be resolved; e.g., GIT_CEILING_DIRECTORIES=/maybe/symlink::/very/slow/non/symlink.
GIT_DISCOVERY_ACROSS_FILESYSTEM
When run in a directory that does not have ".git" repository directory, Git tries to find such a directory in the parent directories to find the top of the working tree, but by default it does not cross filesystem boundaries. This environment variable can be set to true to tell Git not to stop at filesystem boundaries. Like GIT_CEILING_DIRECTORIES, this will not affect an explicit repository directory set via GIT_DIR or on the command line.
GIT_COMMON_DIR
If this variable is set to a path, non-worktree files that are normally in $GIT_DIR will be taken from this path instead. Worktree-specific files such as HEAD or index are taken from $GIT_DIR. See Section G.4.11, “gitrepository-layout(5)” and Section G.3.148, “git-worktree(1)” for details. This variable has lower precedence than other path variables such as GIT_INDEX_FILE, GIT_OBJECT_DIRECTORY…

2. Git Commits

GIT_AUTHOR_NAME , GIT_AUTHOR_EMAIL , GIT_AUTHOR_DATE , GIT_COMMITTER_NAME , GIT_COMMITTER_EMAIL , GIT_COMMITTER_DATE , EMAIL
see Section G.3.25, “git-commit-tree(1)”

3. Git Diffs

GIT_DIFF_OPTS
Only valid setting is "--unified=??" or "-u??" to set the number of context lines shown when a unified diff is created. This takes precedence over any "-U" or "--unified" option value passed on the Git diff command line.
GIT_EXTERNAL_DIFF

When the environment variable GIT_EXTERNAL_DIFF is set, the program named by it is called, instead of the diff invocation described above. For a path that is added, removed, or modified, GIT_EXTERNAL_DIFF is called with 7 parameters:

path old-file old-hex old-mode new-file new-hex new-mode

where:

<old|new>-file
are files GIT_EXTERNAL_DIFF can use to read the contents of <old|new>,
<old|new>-hex
are the 40-hexdigit SHA-1 hashes,
<old|new>-mode

are the octal representation of the file modes.

The file parameters can point at the user's working file (e.g. new-file in "git-diff-files"), /dev/null (e.g. old-file when a new file is added), or a temporary file (e.g. old-file in the index). GIT_EXTERNAL_DIFF should not worry about unlinking the temporary file --- it is removed when GIT_EXTERNAL_DIFF exits.

For a path that is unmerged, GIT_EXTERNAL_DIFF is called with 1 parameter, <path>.

For each path GIT_EXTERNAL_DIFF is called, two environment variables, GIT_DIFF_PATH_COUNTER and GIT_DIFF_PATH_TOTAL are set.

GIT_DIFF_PATH_COUNTER
A 1-based counter incremented by one for every path.
GIT_DIFF_PATH_TOTAL
The total number of paths.

4. other

GIT_MERGE_VERBOSITY
A number controlling the amount of output shown by the recursive merge strategy. Overrides merge.verbosity. See Section G.3.79, “git-merge(1)”
GIT_PAGER
This environment variable overrides $PAGER. If it is set to an empty string or to the value "cat", Git will not launch a pager. See also the core.pager option in Section G.3.27, “git-config(1)”.
GIT_EDITOR
This environment variable overrides $EDITOR and $VISUAL. It is used by several Git commands when, on interactive mode, an editor is to be launched. See also Section G.3.142, “git-var(1)” and the core.editor option in Section G.3.27, “git-config(1)”.
GIT_SSH , GIT_SSH_COMMAND

If either of these environment variables is set then git fetch and git push will use the specified command instead of ssh when they need to connect to a remote system. The command will be given exactly two or four arguments: the [email protected] (or just host) from the URL and the shell command to execute on that remote system, optionally preceded by -p (literally) and the port from the URL when it specifies something other than the default SSH port.

$GIT_SSH_COMMAND takes precedence over $GIT_SSH, and is interpreted by the shell, which allows additional arguments to be included. $GIT_SSH on the other hand must be just the path to a program (which can be a wrapper shell script, if additional arguments are needed).

Usually it is easier to configure any desired options through your personal .ssh/config file. Please consult your ssh documentation for further details.

GIT_ASKPASS
If this environment variable is set, then Git commands which need to acquire passwords or passphrases (e.g. for HTTP or IMAP authentication) will call this program with a suitable prompt as command-line argument and read the password from its STDOUT. See also the core.askPass option in Section G.3.27, “git-config(1)”.
GIT_TERMINAL_PROMPT
If this environment variable is set to 0, git will not prompt on the terminal (e.g., when asking for HTTP authentication).
GIT_CONFIG_NOSYSTEM
Whether to skip reading settings from the system-wide $(prefix)/etc/gitconfig file. This environment variable can be used along with $HOME and $XDG_CONFIG_HOME to create a predictable environment for a picky script, or you can set it temporarily to avoid using a buggy /etc/gitconfig file while waiting for someone with sufficient permissions to fix it.
GIT_FLUSH
If this environment variable is set to "1", then commands such as git blame (in incremental mode), git rev-list, git log, git check-attr and git check-ignore will force a flush of the output stream after each record have been flushed. If this variable is set to "0", the output of these commands will be done using completely buffered I/O. If this environment variable is not set, Git will choose buffered or record-oriented flushing based on whether stdout appears to be redirected to a file or not.
GIT_TRACE

Enables general trace messages, e.g. alias expansion, built-in command execution and external command execution.

If this variable is set to "1", "2" or "true" (comparison is case insensitive), trace messages will be printed to stderr.

If the variable is set to an integer value greater than 2 and lower than 10 (strictly) then Git will interpret this value as an open file descriptor and will try to write the trace messages into this file descriptor.

Alternatively, if the variable is set to an absolute path (starting with a / character), Git will interpret this as a file path and will try to write the trace messages into it.

Unsetting the variable, or setting it to empty, "0" or "false" (case insensitive) disables trace messages.

GIT_TRACE_PACK_ACCESS
Enables trace messages for all accesses to any packs. For each access, the pack file name and an offset in the pack is recorded. This may be helpful for troubleshooting some pack-related performance problems. See GIT_TRACE for available trace output options.
GIT_TRACE_PACKET
Enables trace messages for all packets coming in or out of a given program. This can help with debugging object negotiation or other protocol issues. Tracing is turned off at a packet starting with "PACK" (but see GIT_TRACE_PACKFILE below). See GIT_TRACE for available trace output options.
GIT_TRACE_PACKFILE

Enables tracing of packfiles sent or received by a given program. Unlike other trace output, this trace is verbatim: no headers, and no quoting of binary data. You almost certainly want to direct into a file (e.g., GIT_TRACE_PACKFILE=/tmp/my.pack) rather than displaying it on the terminal or mixing it with other trace output.

Note that this is currently only implemented for the client side of clones and fetches.

GIT_TRACE_PERFORMANCE
Enables performance related trace messages, e.g. total execution time of each Git command. See GIT_TRACE for available trace output options.
GIT_TRACE_SETUP
Enables trace messages printing the .git, working tree and current working directory after Git has completed its setup phase. See GIT_TRACE for available trace output options.
GIT_TRACE_SHALLOW
Enables trace messages that can help debugging fetching / cloning of shallow repositories. See GIT_TRACE for available trace output options.
GIT_LITERAL_PATHSPECS
Setting this variable to 1 will cause Git to treat all pathspecs literally, rather than as glob patterns. For example, running GIT_LITERAL_PATHSPECS=1 git log -- '*.c' will search for commits that touch the path *.c, not any paths that the glob *.c matches. You might want this if you are feeding literal paths to Git (e.g., paths previously given to you by git ls-tree, --raw diff output, etc).
GIT_GLOB_PATHSPECS
Setting this variable to 1 will cause Git to treat all pathspecs as glob patterns (aka "glob" magic).
GIT_NOGLOB_PATHSPECS
Setting this variable to 1 will cause Git to treat all pathspecs as literal (aka "literal" magic).
GIT_ICASE_PATHSPECS
Setting this variable to 1 will cause Git to treat all pathspecs as case-insensitive.
GIT_REFLOG_ACTION
When a ref is updated, reflog entries are created to keep track of the reason why the ref was updated (which is typically the name of the high-level command that updated the ref), in addition to the old and new values of the ref. A scripted Porcelain command can use set_reflog_action helper function in git-sh-setup to set its name to this variable when it is invoked as the top level command by the end user, to be recorded in the body of the reflog.
GIT_REF_PARANOIA
If set to 1, include broken or badly named refs when iterating over lists of refs. In a normal, non-corrupted repository, this does nothing. However, enabling it may help git to detect and abort some operations in the presence of broken refs. Git sets this variable automatically when performing destructive operations like Section G.3.94, “git-prune(1)”. You should not need to set it yourself unless you want to be paranoid about making sure an operation has touched every ref (e.g., because you are cloning a repository to make a backup).
GIT_ALLOW_PROTOCOL

If set, provide a colon-separated list of protocols which are allowed to be used with fetch/push/clone. This is useful to restrict recursive submodule initialization from an untrusted repository. Any protocol not mentioned will be disallowed (i.e., this is a whitelist, not a blacklist). If the variable is not set at all, all protocols are enabled. The protocol names currently used by git are:

  • file: any local file-based path (including file:// URLs, or local paths)
  • git: the anonymous git protocol over a direct TCP connection (or proxy, if configured)
  • ssh: git over ssh (including host:path syntax, ssh://, etc).
  • http: git over http, both "smart http" and "dumb http". Note that this does not include https; if you want both, you should specify both as http:https.
  • any external helpers are named by their protocol (e.g., use hg to allow the git-remote-hg helper)

Discussion

More detail on the following is available from the Git concepts chapter of the user-manual and Section G.2.3, “gitcore-tutorial(7)”.

A Git project normally consists of a working directory with a ".git" subdirectory at the top level. The .git directory contains, among other things, a compressed object database representing the complete history of the project, an "index" file which links that history to the current contents of the working tree, and named pointers into that history such as tags and branch heads.

The object database contains objects of three main types: blobs, which hold file data; trees, which point to blobs and other trees to build up directory hierarchies; and commits, which each reference a single tree and some number of parent commits.

The commit, equivalent to what other systems call a "changeset" or "version", represents a step in the project's history, and each parent represents an immediately preceding step. Commits with more than one parent represent merges of independent lines of development.

All objects are named by the SHA-1 hash of their contents, normally written as a string of 40 hex digits. Such names are globally unique. The entire history leading up to a commit can be vouched for by signing just that commit. A fourth object type, the tag, is provided for this purpose.

When first created, objects are stored in individual files, but for efficiency may later be compressed together into "pack files".

Named pointers called refs mark interesting points in history. A ref may contain the SHA-1 name of an object or the name of another ref. Refs with names beginning ref/head/ contain the SHA-1 name of the most recent commit (or "head") of a branch under development. SHA-1 names of tags of interest are stored under ref/tags/. A special ref named HEAD contains the name of the currently checked-out branch.

The index file is initialized with a list of all paths and, for each path, a blob object and a set of attributes. The blob object represents the contents of the file as of the head of the current branch. The attributes (last modified time, size, etc.) are taken from the corresponding file in the working tree. Subsequent changes to the working tree can be found by comparing these attributes. The index may be updated with new content, and new commits may be created from the content stored in the index.

The index is also capable of storing multiple entries (called "stages") for a given pathname. These stages are used to hold the various unmerged version of a file when a merge is in progress.

FURTHER DOCUMENTATION

See the references in the "description" section to get started using Git. The following is probably more detail than necessary for a first-time user.

The Git concepts chapter of the user-manual and Section G.2.3, “gitcore-tutorial(7)” both provide introductions to the underlying Git architecture.

See Section G.4.15, “gitworkflows(7)” for an overview of recommended workflows.

See also the howto documents for some useful examples.

The internals are documented in the Git API documentation.

Users migrating from CVS may also want to read Section G.2.4, “gitcvs-migration(7)”.

Authors

Git was started by Linus Torvalds, and is currently maintained by Junio C Hamano. Numerous contributions have come from the Git mailing list <[email protected]>. http://www.openhub.net/p/git/contributors/summary gives you a more complete list of contributors.

If you have a clone of git.git itself, the output of Section G.3.122, “git-shortlog(1)” and Section G.3.9, “git-blame(1)” can show you the authors for specific parts of the project.

Reporting Bugs

Report bugs to the Git mailing list <[email protected]> where the development and maintenance is primarily done. You do not have to be subscribed to the list to send a message there.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.2. git-add(1)

NAME

git-add - Add file contents to the index

SYNOPSIS

git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p]
          [--edit | -e] [--[no-]all | --[no-]ignore-removal | [--update | -u]]
          [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing]
          [--] [<pathspec>…]

DESCRIPTION

This command updates the index using the current content found in the working tree, to prepare the content staged for the next commit. It typically adds the current content of existing paths as a whole, but with some options it can also be used to add content with only part of the changes made to the working tree files applied, or remove paths that do not exist in the working tree anymore.

The "index" holds a snapshot of the content of the working tree, and it is this snapshot that is taken as the contents of the next commit. Thus after making any changes to the working tree, and before running the commit command, you must use the add command to add any new or modified files to the index.

This command can be performed multiple times before a commit. It only adds the content of the specified file(s) at the time the add command is run; if you want subsequent changes included in the next commit, then you must run git add again to add the new content to the index.

The git status command can be used to obtain a summary of which files have changes that are staged for the next commit.

The git add command will not add ignored files by default. If any ignored files were explicitly specified on the command line, git add will fail with a list of ignored files. Ignored files reached by directory recursion or filename globbing performed by Git (quote your globs before the shell) will be silently ignored. The git add command can be used to add ignored files with the -f (force) option.

Please see Section G.3.26, “git-commit(1)” for alternative ways to add content to a commit.

OPTIONS

<pathspec>…
Files to add content from. Fileglobs (e.g. *.c) can be given to add all matching files. Also a leading directory name (e.g. dir to add dir/file1 and dir/file2) can be given to update the index to match the current state of the directory as a whole (e.g. specifying dir will record not just a file dir/file1 modified in the working tree, a file dir/file2 added to the working tree, but also a file dir/file3 removed from the working tree. Note that older versions of Git used to ignore removed files; use --no-all option if you want to add modified or new files but ignore removed ones.
-n , --dry-run
Don't actually add the file(s), just show if they exist and/or will be ignored.
-v , --verbose
Be verbose.
-f , --force
Allow adding otherwise ignored files.
-i , --interactive
Add modified contents in the working tree interactively to the index. Optional path arguments may be supplied to limit operation to a subset of the working tree. See Interactive mode for details.
-p , --patch

Interactively choose hunks of patch between the index and the work tree and add them to the index. This gives the user a chance to review the difference before adding modified contents to the index.

This effectively runs add --interactive, but bypasses the initial command menu and directly jumps to the patch subcommand. See Interactive mode for details.

-e , --edit

Open the diff vs. the index in an editor and let the user edit it. After the editor was closed, adjust the hunk headers and apply the patch to the index.

The intent of this option is to pick and choose lines of the patch to apply, or even to modify the contents of lines to be staged. This can be quicker and more flexible than using the interactive hunk selector. However, it is easy to confuse oneself and create a patch that does not apply to the index. See EDITING PATCHES below.

-u , --update

Update the index just where it already has an entry matching <pathspec>. This removes as well as modifies index entries to match the working tree, but adds no new files.

If no <pathspec> is given when -u option is used, all tracked files in the entire working tree are updated (old versions of Git used to limit the update to the current directory and its subdirectories).

-A , --all , --no-ignore-removal

Update the index not only where the working tree has a file matching <pathspec> but also where the index already has an entry. This adds, modifies, and removes index entries to match the working tree.

If no <pathspec> is given when -A option is used, all files in the entire working tree are updated (old versions of Git used to limit the update to the current directory and its subdirectories).

--no-all , --ignore-removal

Update the index by adding new files that are unknown to the index and files modified in the working tree, but ignore files that have been removed from the working tree. This option is a no-op when no <pathspec> is used.

This option is primarily to help users who are used to older versions of Git, whose "git add <pathspec>…" was a synonym for "git add --no-all <pathspec>…", i.e. ignored removed files.

-N , --intent-to-add
Record only the fact that the path will be added later. An entry for the path is placed in the index with no content. This is useful for, among other things, showing the unstaged content of such files with git diff and committing them with git commit -a.
--refresh
Don't add the file(s), but only refresh their stat() information in the index.
--ignore-errors
If some files could not be added because of errors indexing them, do not abort the operation, but continue adding the others. The command shall still exit with non-zero status. The configuration variable add.ignoreErrors can be set to true to make this the default behaviour.
--ignore-missing
This option can only be used together with --dry-run. By using this option the user can check if any of the given files would be ignored, no matter if they are already present in the work tree or not.
--
This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken for command-line options).

Configuration

The optional configuration variable core.excludesFile indicates a path to a file containing patterns of file names to exclude from git-add, similar to $GIT_DIR/info/exclude. Patterns in the exclude file are used in addition to those in info/exclude. See Section G.4.5, “gitignore(5)”.

EXAMPLES

  • Adds content from all *.txt files under Documentation directory and its subdirectories:

    $ git add Documentation/\*.txt

    Note that the asterisk * is quoted from the shell in this example; this lets the command include the files from subdirectories of Documentation/ directory.

  • Considers adding content from all git-*.sh scripts:

    $ git add git-*.sh

    Because this example lets the shell expand the asterisk (i.e. you are listing the files explicitly), it does not consider subdir/git-foo.sh.

Interactive mode

When the command enters the interactive mode, it shows the output of the status subcommand, and then goes into its interactive command loop.

The command loop shows the list of subcommands available, and gives a prompt "What now> ". In general, when the prompt ends with a single >, you can pick only one of the choices given and type return, like this:

    *** Commands ***
      1: status       2: update       3: revert       4: add untracked
      5: patch        6: diff         7: quit         8: help
    What now> 1

You also could say s or sta or status above as long as the choice is unique.

The main command loop has 6 subcommands (plus help and quit).

status

This shows the change between HEAD and index (i.e. what will be committed if you say git commit), and between index and working tree files (i.e. what you could stage further before git commit using git add) for each path. A sample output looks like this:

              staged     unstaged path
     1:       binary      nothing foo.png
     2:     +403/-35        +1/-1 git-add--interactive.perl

It shows that foo.png has differences from HEAD (but that is binary so line count cannot be shown) and there is no difference between indexed copy and the working tree version (if the working tree version were also different, binary would have been shown in place of nothing). The other file, git-add--interactive.perl, has 403 lines added and 35 lines deleted if you commit what is in the index, but working tree file has further modifications (one addition and one deletion).

update

This shows the status information and issues an "Update>>" prompt. When the prompt ends with double >>, you can make more than one selection, concatenated with whitespace or comma. Also you can say ranges. E.g. "2-5 7,9" to choose 2,3,4,5,7,9 from the list. If the second number in a range is omitted, all remaining patches are taken. E.g. "7-" to choose 7,8,9 from the list. You can say * to choose everything.

What you chose are then highlighted with *, like this:

           staged     unstaged path
  1:       binary      nothing foo.png
* 2:     +403/-35        +1/-1 git-add--interactive.perl

To remove selection, prefix the input with - like this:

Update>> -2

After making the selection, answer with an empty line to stage the contents of working tree files for selected paths in the index.

revert
This has a very similar UI to update, and the staged information for selected paths are reverted to that of the HEAD version. Reverting new paths makes them untracked.
add untracked
This has a very similar UI to update and revert, and lets you add untracked paths to the index.
patch

This lets you choose one path out of a status like selection. After choosing the path, it presents the diff between the index and the working tree file and asks you if you want to stage the change of each hunk. You can select one of the following options and type return:

y - stage this hunk
n - do not stage this hunk
q - quit; do not stage this hunk or any of the remaining ones
a - stage this hunk and all later hunks in the file
d - do not stage this hunk or any of the later hunks in the file
g - select a hunk to go to
/ - search for a hunk matching the given regex
j - leave this hunk undecided, see next undecided hunk
J - leave this hunk undecided, see next hunk
k - leave this hunk undecided, see previous undecided hunk
K - leave this hunk undecided, see previous hunk
s - split the current hunk into smaller hunks
e - manually edit the current hunk
? - print help

After deciding the fate for all hunks, if there is any hunk that was chosen, the index is updated with the selected hunks.

You can omit having to type return here, by setting the configuration variable interactive.singleKey to true.

diff
This lets you review what will be committed (i.e. between HEAD and index).

EDITING PATCHES

Invoking git add -e or selecting e from the interactive hunk selector will open a patch in your editor; after the editor exits, the result is applied to the index. You are free to make arbitrary changes to the patch, but note that some changes may have confusing results, or even result in a patch that cannot be applied. If you want to abort the operation entirely (i.e., stage nothing new in the index), simply delete all lines of the patch. The list below describes some common things you may see in a patch, and which editing operations make sense on them.

added content
Added content is represented by lines beginning with "+". You can prevent staging any addition lines by deleting them.
removed content
Removed content is represented by lines beginning with "-". You can prevent staging their removal by converting the "-" to a " " (space).
modified content
Modified content is represented by "-" lines (removing the old content) followed by "+" lines (adding the replacement content). You can prevent staging the modification by converting "-" lines to " ", and removing "+" lines. Beware that modifying only half of the pair is likely to introduce confusing changes to the index.

There are also more complex operations that can be performed. But beware that because the patch is applied only to the index and not the working tree, the working tree will appear to "undo" the change in the index. For example, introducing a new line into the index that is in neither the HEAD nor the working tree will stage the new line for commit, but the line will appear to be reverted in the working tree.

Avoid using these constructs, or do so with extreme caution.

removing untouched content
Content which does not differ between the index and working tree may be shown on context lines, beginning with a " " (space). You can stage context lines for removal by converting the space to a "-". The resulting working tree file will appear to re-add the content.
modifying existing content
One can also modify context lines by staging them for removal (by converting " " to "-") and adding a "+" line with the new content. Similarly, one can modify "+" lines for existing additions or modifications. In all cases, the new modification will appear reverted in the working tree.
new content
You may also add new content that does not exist in the patch; simply add new lines, each starting with "+". The addition will appear reverted in the working tree.

There are also several operations which should be avoided entirely, as they will make the patch impossible to apply:

  • adding context (" ") or removal ("-") lines
  • deleting context or removal lines
  • modifying the contents of context or removal lines

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.3. git-am(1)

NAME

git-am - Apply a series of patches from a mailbox

SYNOPSIS

git am [--signoff] [--keep] [--[no-]keep-cr] [--[no-]utf8]
         [--[no-]3way] [--interactive] [--committer-date-is-author-date]
         [--ignore-date] [--ignore-space-change | --ignore-whitespace]
         [--whitespace=<option>] [-C<n>] [-p<n>] [--directory=<dir>]
         [--exclude=<path>] [--include=<path>] [--reject] [-q | --quiet]
         [--[no-]scissors] [-S[<keyid>]] [--patch-format=<format>]
         [(<mbox> | <Maildir>)…]
git am (--continue | --skip | --abort)

DESCRIPTION

Splits mail messages in a mailbox into commit log message, authorship information and patches, and applies them to the current branch.

OPTIONS

(<mbox>|<Maildir>)…
The list of mailbox files to read patches from. If you do not supply this argument, the command reads from the standard input. If you supply directories, they will be treated as Maildirs.
-s , --signoff
Add a Signed-off-by: line to the commit message, using the committer identity of yourself. See the signoff option in Section G.3.26, “git-commit(1)” for more information.
-k , --keep
Pass -k flag to git mailinfo (see Section G.3.72, “git-mailinfo(1)”).
--keep-non-patch
Pass -b flag to git mailinfo (see Section G.3.72, “git-mailinfo(1)”).
--[no-]keep-cr
With --keep-cr, call git mailsplit (see Section G.3.73, “git-mailsplit(1)”) with the same option, to prevent it from stripping CR at the end of lines. am.keepcr configuration variable can be used to specify the default behaviour. --no-keep-cr is useful to override am.keepcr.
-c , --scissors
Remove everything in body before a scissors line (see Section G.3.72, “git-mailinfo(1)”). Can be activated by default using the mailinfo.scissors configuration variable.
--no-scissors
Ignore scissors lines (see Section G.3.72, “git-mailinfo(1)”).
-m , --message-id
Pass the -m flag to git mailinfo (see Section G.3.72, “git-mailinfo(1)”), so that the Message-ID header is added to the commit message. The am.messageid configuration variable can be used to specify the default behaviour.
--no-message-id
Do not add the Message-ID header to the commit message. no-message-id is useful to override am.messageid.
-q , --quiet
Be quiet. Only print error messages.
-u , --utf8

Pass -u flag to git mailinfo (see Section G.3.72, “git-mailinfo(1)”). The proposed commit log message taken from the e-mail is re-coded into UTF-8 encoding (configuration variable i18n.commitencoding can be used to specify project's preferred encoding if it is not UTF-8).

This was optional in prior versions of git, but now it is the default. You can use --no-utf8 to override this.

--no-utf8
Pass -n flag to git mailinfo (see Section G.3.72, “git-mailinfo(1)”).
-3 , --3way , --no-3way
When the patch does not apply cleanly, fall back on 3-way merge if the patch records the identity of blobs it is supposed to apply to and we have those blobs available locally. --no-3way can be used to override am.threeWay configuration variable. For more information, see am.threeWay in Section G.3.27, “git-config(1)”.
--ignore-space-change , --ignore-whitespace , --whitespace=<option> , -C<n> , -p<n> , --directory=<dir> , --exclude=<path> , --include=<path> , --reject
These flags are passed to the git apply (see Section G.3.5, “git-apply(1)”) program that applies the patch.
--patch-format
By default the command will try to detect the patch format automatically. This option allows the user to bypass the automatic detection and specify the patch format that the patch(es) should be interpreted as. Valid formats are mbox, stgit, stgit-series and hg.
-i , --interactive
Run interactively.
--committer-date-is-author-date
By default the command records the date from the e-mail message as the commit author date, and uses the time of commit creation as the committer date. This allows the user to lie about the committer date by using the same value as the author date.
--ignore-date
By default the command records the date from the e-mail message as the commit author date, and uses the time of commit creation as the committer date. This allows the user to lie about the author date by using the same value as the committer date.
--skip
Skip the current patch. This is only meaningful when restarting an aborted patch.
-S[<keyid>] , --gpg-sign[=<keyid>]
GPG-sign commits. The keyid argument is optional and defaults to the committer identity; if specified, it must be stuck to the option without a space.
--continue , -r , --resolved
After a patch failure (e.g. attempting to apply conflicting patch), the user has applied it by hand and the index file stores the result of the application. Make a commit using the authorship and commit log extracted from the e-mail message and the current index file, and continue.
--resolvemsg=<msg>
When a patch failure occurs, <msg> will be printed to the screen before exiting. This overrides the standard message informing you to use --continue or --skip to handle the failure. This is solely for internal use between git rebase and git am.
--abort
Restore the original branch and abort the patching operation.

DISCUSSION

The commit author name is taken from the "From: " line of the message, and commit author date is taken from the "Date: " line of the message. The "Subject: " line is used as the title of the commit, after stripping common prefix "[PATCH <anything>]". The "Subject: " line is supposed to concisely describe what the commit is about in one line of text.

"From: " and "Subject: " lines starting the body override the respective commit author name and title values taken from the headers.

The commit message is formed by the title taken from the "Subject: ", a blank line and the body of the message up to where the patch begins. Excess whitespace at the end of each line is automatically stripped.

The patch is expected to be inline, directly following the message. Any line that is of the form:

  • three-dashes and end-of-line, or
  • a line that begins with "diff -", or
  • a line that begins with "Index: "

is taken as the beginning of a patch, and the commit log message is terminated before the first occurrence of such a line.

When initially invoking git am, you give it the names of the mailboxes to process. Upon seeing the first patch that does not apply, it aborts in the middle. You can recover from this in one of two ways:

  1. skip the current patch by re-running the command with the --skip option.
  2. hand resolve the conflict in the working directory, and update the index file to bring it into a state that the patch should have produced. Then run the command with the --continue option.

The command refuses to process new mailboxes until the current operation is finished, so if you decide to start over from scratch, run git am --abort before running the command with mailbox names.

Before any patches are applied, ORIG_HEAD is set to the tip of the current branch. This is useful if you have problems with multiple commits, like running git am on the wrong branch or an error in the commits that is more easily fixed by changing the mailbox (e.g. errors in the "From:" lines).

HOOKS

This command can run applypatch-msg, pre-applypatch, and post-applypatch hooks. See Section G.4.6, “githooks(5)” for more information.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.4. git-annotate(1)

NAME

git-annotate - Annotate file lines with commit information

SYNOPSIS

git annotate [options] file [revision]

DESCRIPTION

Annotates each line in the given file with information from the commit which introduced the line. Optionally annotates from a given revision.

The only difference between this command and Section G.3.9, “git-blame(1)” is that they use slightly different output formats, and this command exists only for backward compatibility to support existing scripts, and provide a more familiar command name for people coming from other SCM systems.

OPTIONS

-b
Show blank SHA-1 for boundary commits. This can also be controlled via the blame.blankboundary config option.
--root
Do not treat root commits as boundaries. This can also be controlled via the blame.showRoot config option.
--show-stats
Include additional statistics at the end of blame output.
-L <start>,<end> , -L :<funcname>

Annotate only the given line range. May be specified multiple times. Overlapping ranges are allowed.

<start> and <end> are optional. -L <start> or -L <start>, spans from <start> to end of file. -L ,<end> spans from start of file to <end>.

<start> and <end> can take one of these forms:

  • number

    If <start> or <end> is a number, it specifies an absolute line number (lines count from 1).

  • /regex/

    This form will use the first line matching the given POSIX regex. If <start> is a regex, it will search from the end of the previous -L range, if any, otherwise from the start of file. If <start> is ^/regex/, it will search from the start of file. If <end> is a regex, it will search starting at the line given by <start>.

  • +offset or -offset

    This is only valid for <end> and will specify a number of lines before or after the line given by <start>.

If :<funcname> is given in place of <start> and <end>, it is a regular expression that denotes the range from the first funcname line that matches <funcname>, up to the next funcname line. :<funcname> searches from the end of the previous -L range, if any, otherwise from the start of file. ^:<funcname> searches from the start of file.

-l
Show long rev (Default: off).
-t
Show raw timestamp (Default: off).
-S <revs-file>
Use revisions from revs-file instead of calling Section G.3.112, “git-rev-list(1)”.
--reverse
Walk history forward instead of backward. Instead of showing the revision in which a line appeared, this shows the last revision in which a line has existed. This requires a range of revision like START..END where the path to blame exists in START.
-p , --porcelain
Show in a format designed for machine consumption.
--line-porcelain
Show the porcelain format, but output commit information for each line, not just the first time a commit is referenced. Implies --porcelain.
--incremental
Show the result incrementally in a format designed for machine consumption.
--encoding=<encoding>
Specifies the encoding used to output author names and commit summaries. Setting it to none makes blame output unconverted data. For more information see the discussion about encoding in the Section G.3.68, “git-log(1)” manual page.
--contents <file>
When <rev> is not specified, the command annotates the changes starting backwards from the working tree copy. This flag makes the command pretend as if the working tree copy has the contents of the named file (specify - to make the command read from the standard input).
--date <format>
Specifies the format used to output dates. If --date is not provided, the value of the blame.date config variable is used. If the blame.date config variable is also not set, the iso format is used. For supported values, see the discussion of the --date option at Section G.3.68, “git-log(1)”.
--[no-]progress
Progress status is reported on the standard error stream by default when it is attached to a terminal. This flag enables progress reporting even if not attached to a terminal. Can't use --progress together with --porcelain or --incremental.
-M|<num>|

Detect moved or copied lines within a file. When a commit moves or copies a block of lines (e.g. the original file has A and then B, and the commit changes it to B and then A), the traditional blame algorithm notices only half of the movement and typically blames the lines that were moved up (i.e. B) to the parent and assigns blame to the lines that were moved down (i.e. A) to the child commit. With this option, both groups of lines are blamed on the parent by running extra passes of inspection.

<num> is optional but it is the lower bound on the number of alphanumeric characters that Git must detect as moving/copying within a file for it to associate those lines with the parent commit. The default value is 20.

-C|<num>|

In addition to -M, detect lines moved or copied from other files that were modified in the same commit. This is useful when you reorganize your program and move code around across files. When this option is given twice, the command additionally looks for copies from other files in the commit that creates the file. When this option is given three times, the command additionally looks for copies from other files in any commit.

<num> is optional but it is the lower bound on the number of alphanumeric characters that Git must detect as moving/copying between files for it to associate those lines with the parent commit. And the default value is 40. If there are more than one -C options given, the <num> argument of the last -C will take effect.

-h
Show help message.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.5. git-apply(1)

NAME

git-apply - Apply a patch to files and/or to the index

SYNOPSIS

git apply [--stat] [--numstat] [--summary] [--check] [--index] [--3way]
          [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
          [--allow-binary-replacement | --binary] [--reject] [-z]
          [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
          [--ignore-space-change | --ignore-whitespace]
          [--whitespace=(nowarn|warn|fix|error|error-all)]
          [--exclude=<path>] [--include=<path>] [--directory=<root>]
          [--verbose] [--unsafe-paths] [<patch>…]

DESCRIPTION

Reads the supplied diff output (i.e. "a patch") and applies it to files. When running from a subdirectory in a repository, patched paths outside the directory are ignored. With the --index option the patch is also applied to the index, and with the --cached option the patch is only applied to the index. Without these options, the command applies the patch only to files, and does not require them to be in a Git repository.

This command applies the patch but does not create a commit. Use Section G.3.3, “git-am(1)” to create commits from patches generated by Section G.3.50, “git-format-patch(1)” and/or received by email.

OPTIONS

<patch>…
The files to read the patch from. - can be used to read from the standard input.
--stat
Instead of applying the patch, output diffstat for the input. Turns off "apply".
--numstat
Similar to --stat, but shows the number of added and deleted lines in decimal notation and the pathname without abbreviation, to make it more machine friendly. For binary files, outputs two - instead of saying 0 0. Turns off "apply".
--summary
Instead of applying the patch, output a condensed summary of information obtained from git diff extended headers, such as creations, renames and mode changes. Turns off "apply".
--check
Instead of applying the patch, see if the patch is applicable to the current working tree and/or the index file and detects errors. Turns off "apply".
--index
When --check is in effect, or when applying the patch (which is the default when none of the options that disables it is in effect), make sure the patch is applicable to what the current index file records. If the file to be patched in the working tree is not up-to-date, it is flagged as an error. This flag also causes the index file to be updated.
--cached
Apply a patch without touching the working tree. Instead take the cached data, apply the patch, and store the result in the index without using the working tree. This implies --index.
-3 , --3way
When the patch does not apply cleanly, fall back on 3-way merge if the patch records the identity of blobs it is supposed to apply to, and we have those blobs available locally, possibly leaving the conflict markers in the files in the working tree for the user to resolve. This option implies the --index option, and is incompatible with the --reject and the --cached options.
--build-fake-ancestor=<file>

Newer git diff output has embedded index information for each blob to help identify the original version that the patch applies to. When this flag is given, and if the original versions of the blobs are available locally, builds a temporary index containing those blobs.

When a pure mode change is encountered (which has no index information), the information is read from the current index instead.

-R , --reverse
Apply the patch in reverse.
--reject
For atomicity, git apply by default fails the whole patch and does not touch the working tree when some of the hunks do not apply. This option makes it apply the parts of the patch that are applicable, and leave the rejected hunks in corresponding *.rej files.
-z

When --numstat has been given, do not munge pathnames, but use a NUL-terminated machine-readable format.

Without this option, each pathname output will have TAB, LF, double quotes, and backslash characters replaced with \t, \n, \", and \\, respectively, and the pathname will be enclosed in double quotes if any of those replacements occurred.

-p<n>
Remove <n> leading slashes from traditional diff paths. The default is 1.
-C<n>
Ensure at least <n> lines of surrounding context match before and after each change. When fewer lines of surrounding context exist they all must match. By default no context is ever ignored.
--unidiff-zero

By default, git apply expects that the patch being applied is a unified diff with at least one line of context. This provides good safety measures, but breaks down when applying a diff generated with --unified=0. To bypass these checks use --unidiff-zero.

Note, for the reasons stated above usage of context-free patches is discouraged.

--apply
If you use any of the options marked "Turns off apply" above, git apply reads and outputs the requested information without actually applying the patch. Give this flag after those flags to also apply the patch.
--no-add
When applying a patch, ignore additions made by the patch. This can be used to extract the common part between two files by first running diff on them and applying the result with this option, which would apply the deletion part but not the addition part.
--allow-binary-replacement , --binary
Historically we did not allow binary patch applied without an explicit permission from the user, and this flag was the way to do so. Currently we always allow binary patch application, so this is a no-op.
--exclude=<path-pattern>
Don't apply changes to files matching the given path pattern. This can be useful when importing patchsets, where you want to exclude certain files or directories.
--include=<path-pattern>

Apply changes to files matching the given path pattern. This can be useful when importing patchsets, where you want to include certain files or directories.

When --exclude and --include patterns are used, they are examined in the order they appear on the command line, and the first match determines if a patch to each path is used. A patch to a path that does not match any include/exclude pattern is used by default if there is no include pattern on the command line, and ignored if there is any include pattern.

--ignore-space-change , --ignore-whitespace
When applying a patch, ignore changes in whitespace in context lines if necessary. Context lines will preserve their whitespace, and they will not undergo whitespace fixing regardless of the value of the --whitespace option. New lines will still be fixed, though.
--whitespace=<action>

When applying a patch, detect a new or modified line that has whitespace errors. What are considered whitespace errors is controlled by core.whitespace configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the initial indent of the line are considered whitespace errors.

By default, the command outputs warning messages but applies the patch. When git-apply is used for statistics and not applying a patch, it defaults to nowarn.

You can use different <action> values to control this behavior:

  • nowarn turns off the trailing whitespace warning.
  • warn outputs warnings for a few such errors, but applies the patch as-is (default).
  • fix outputs warnings for a few such errors, and applies the patch after fixing them (strip is a synonym --- the tool used to consider only trailing whitespace characters as errors, and the fix involved stripping them, but modern Gits do more).
  • error outputs warnings for a few such errors, and refuses to apply the patch.
  • error-all is similar to error but shows all errors.
--inaccurate-eof
Under certain circumstances, some versions of diff do not correctly detect a missing new-line at the end of the file. As a result, patches created by such diff programs do not record incomplete lines correctly. This option adds support for applying such patches by working around this bug.
-v , --verbose
Report progress to stderr. By default, only a message about the current patch being applied will be printed. This option will cause additional information to be reported.
--recount
Do not trust the line counts in the hunk headers, but infer them by inspecting the patch (e.g. after editing the patch without adjusting the hunk headers appropriately).
--directory=<root>

Prepend <root> to all filenames. If a "-p" argument was also passed, it is applied before prepending the new root.

For example, a patch that talks about updating a/git-gui.sh to b/git-gui.sh can be applied to the file in the working tree modules/git-gui/git-gui.sh by running git apply --directory=modules/git-gui.

--unsafe-paths

By default, a patch that affects outside the working area (either a Git controlled working tree, or the current working directory when "git apply" is used as a replacement of GNU patch) is rejected as a mistake (or a mischief).

When git apply is used as a "better GNU patch", the user can pass the --unsafe-paths option to override this safety check. This option has no effect when --index or --cached is in use.

Configuration

apply.ignoreWhitespace
Set to change if you want changes in whitespace to be ignored by default. Set to one of: no, none, never, false if you want changes in whitespace to be significant.
apply.whitespace
When no --whitespace flag is given from the command line, this configuration item is used as the default.

Submodules

If the patch contains any changes to submodules then git apply treats these changes as follows.

If --index is specified (explicitly or implicitly), then the submodule commits must match the index exactly for the patch to apply. If any of the submodules are checked-out, then these check-outs are completely ignored, i.e., they are not required to be up-to-date or clean and they are not updated.

If --index is not specified, then the submodule commits in the patch are ignored and only the absence or presence of the corresponding subdirectory is checked and (if possible) updated.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.6. git-archimport(1)

NAME

git-archimport - Import an Arch repository into Git

SYNOPSIS

git archimport [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir]
               <archive/branch>[:<git-branch>] …

DESCRIPTION

Imports a project from one or more Arch repositories. It will follow branches and repositories within the namespaces defined by the <archive/branch> parameters supplied. If it cannot find the remote branch a merge comes from it will just import it as a regular commit. If it can find it, it will mark it as a merge whenever possible (see discussion below).

The script expects you to provide the key roots where it can start the import from an initial import or tag type of Arch commit. It will follow and import new branches within the provided roots.

It expects to be dealing with one project only. If it sees branches that have different roots, it will refuse to run. In that case, edit your <archive/branch> parameters to define clearly the scope of the import.

git archimport uses tla extensively in the background to access the Arch repository. Make sure you have a recent version of tla available in the path. tla must know about the repositories you pass to git archimport.

For the initial import, git archimport expects to find itself in an empty directory. To follow the development of a project that uses Arch, rerun git archimport with the same parameters as the initial import to perform incremental imports.

While git archimport will try to create sensible branch names for the archives that it imports, it is also possible to specify Git branch names manually. To do so, write a Git branch name after each <archive/branch> parameter, separated by a colon. This way, you can shorten the Arch branch names and convert Arch jargon to Git jargon, for example mapping a "PROJECT--devo--VERSION" branch to "master".

Associating multiple Arch branches to one Git branch is possible; the result will make the most sense only if no commits are made to the first branch, after the second branch is created. Still, this is useful to convert Arch repositories that had been rotated periodically.

MERGES

Patch merge data from Arch is used to mark merges in Git as well. Git does not care much about tracking patches, and only considers a merge when a branch incorporates all the commits since the point they forked. The end result is that Git will have a good idea of how far branches have diverged. So the import process does lose some patch-trading metadata.

Fortunately, when you try and merge branches imported from Arch, Git will find a good merge base, and it has a good chance of identifying patches that have been traded out-of-sequence between the branches.

OPTIONS

-h
Display usage.
-v
Verbose output.
-T
Many tags. Will create a tag for every commit, reflecting the commit name in the Arch repository.
-f
Use the fast patchset import strategy. This can be significantly faster for large trees, but cannot handle directory renames or permissions changes. The default strategy is slow and safe.
-o
Use this for compatibility with old-style branch names used by earlier versions of git archimport. Old-style branch names were category--branch, whereas new-style branch names are archive,category--branch--version. In both cases, names given on the command-line will override the automatically-generated ones.
-D <depth>
Follow merge ancestry and attempt to import trees that have been merged from. Specify a depth greater than 1 if patch logs have been pruned.
-a
Attempt to auto-register archives at http://mirrors.sourcecontrol.net This is particularly useful with the -D option.
-t <tmpdir>
Override the default tempdir.
<archive/branch>
Archive/branch identifier in a format that tla log understands.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.7. git-archive(1)

NAME

git-archive - Create an archive of files from a named tree

SYNOPSIS

git archive [--format=<fmt>] [--list] [--prefix=<prefix>/] [<extra>]
              [-o <file> | --output=<file>] [--worktree-attributes]
              [--remote=<repo> [--exec=<git-upload-archive>]] <tree-ish>
              [<path>…]

DESCRIPTION

Creates an archive of the specified format containing the tree structure for the named tree, and writes it out to the standard output. If <prefix> is specified it is prepended to the filenames in the archive.

git archive behaves differently when given a tree ID versus when given a commit ID or tag ID. In the first case the current time is used as the modification time of each file in the archive. In the latter case the commit time as recorded in the referenced commit object is used instead. Additionally the commit ID is stored in a global extended pax header if the tar format is used; it can be extracted using git get-tar-commit-id. In ZIP files it is stored as a file comment.

OPTIONS

--format=<fmt>
Format of the resulting archive: tar or zip. If this option is not given, and the output file is specified, the format is inferred from the filename if possible (e.g. writing to "foo.zip" makes the output to be in the zip format). Otherwise the output format is tar.
-l , --list
Show all available formats.
-v , --verbose
Report progress to stderr.
--prefix=<prefix>/
Prepend <prefix>/ to each filename in the archive.
-o <file> , --output=<file>
Write the archive to <file> instead of stdout.
--worktree-attributes
Look for attributes in .gitattributes files in the working tree as well (see the section called “ATTRIBUTES”).
<extra>
This can be any options that the archiver backend understands. See next section.
--remote=<repo>
Instead of making a tar archive from the local repository, retrieve a tar archive from a remote repository. Note that the remote repository may place restrictions on which sha1 expressions may be allowed in <tree-ish>. See Section G.3.140, “git-upload-archive(1)” for details.
--exec=<git-upload-archive>
Used with --remote to specify the path to the git-upload-archive on the remote side.
<tree-ish>
The tree or commit to produce an archive for.
<path>
Without an optional path parameter, all files and subdirectories of the current working directory are included in the archive. If one or more paths are specified, only these are included.

BACKEND EXTRA OPTIONS

1. zip

-0
Store the files instead of deflating them.
-9
Highest and slowest compression level. You can specify any number from 1 to 9 to adjust compression speed and ratio.

CONFIGURATION

tar.umask
This variable can be used to restrict the permission bits of tar archive entries. The default is 0002, which turns off the world write bit. The special value "user" indicates that the archiving user's umask will be used instead. See umask(2) for details. If --remote is used then only the configuration of the remote repository takes effect.
tar.<format>.command

This variable specifies a shell command through which the tar output generated by git archive should be piped. The command is executed using the shell with the generated tar file on its standard input, and should produce the final output on its standard output. Any compression-level options will be passed to the command (e.g., "-9"). An output file with the same extension as <format> will be use this format if no other format is given.

The "tar.gz" and "tgz" formats are defined automatically and default to gzip -cn. You may override them with custom commands.

tar.<format>.remote
If true, enable <format> for use by remote clients via Section G.3.140, “git-upload-archive(1)”. Defaults to false for user-defined formats, but true for the "tar.gz" and "tgz" formats.

ATTRIBUTES

export-ignore
Files and directories with the attribute export-ignore won't be added to archive files. See Section G.4.2, “gitattributes(5)” for details.
export-subst
If the attribute export-subst is set for a file then Git will expand several placeholders when adding this file to an archive. See Section G.4.2, “gitattributes(5)” for details.

Note that attributes are by default taken from the .gitattributes files in the tree that is being archived. If you want to tweak the way the output is generated after the fact (e.g. you committed without adding an appropriate export-ignore in its .gitattributes), adjust the checked out .gitattributes file as necessary and use --worktree-attributes option. Alternatively you can keep necessary attributes that should apply while archiving any tree in your $GIT_DIR/info/attributes file.

EXAMPLES

git archive --format=tar --prefix=junk/ HEAD | (cd /var/tmp/ && tar xf -)
Create a tar archive that contains the contents of the latest commit on the current branch, and extract it in the /var/tmp/junk directory.
git archive --format=tar --prefix=git-1.4.0/ v1.4.0 | gzip >git-1.4.0.tar.gz
Create a compressed tarball for v1.4.0 release.
git archive --format=tar.gz --prefix=git-1.4.0/ v1.4.0 >git-1.4.0.tar.gz
Same as above, but using the builtin tar.gz handling.
git archive --prefix=git-1.4.0/ -o git-1.4.0.tar.gz v1.4.0
Same as above, but the format is inferred from the output file.
git archive --format=tar --prefix=git-1.4.0/ v1.4.0^{tree} | gzip >git-1.4.0.tar.gz
Create a compressed tarball for v1.4.0 release, but without a global extended pax header.
git archive --format=zip --prefix=git-docs/ HEAD:Documentation/ > git-1.4.0-docs.zip
Put everything in the current head's Documentation/ directory into git-1.4.0-docs.zip, with the prefix git-docs/.
git archive -o latest.zip HEAD
Create a Zip archive that contains the contents of the latest commit on the current branch. Note that the output format is inferred by the extension of the output file.
git config tar.tar.xz.command "xz -c"
Configure a "tar.xz" format for making LZMA-compressed tarfiles. You can use it specifying --format=tar.xz, or by creating an output file like -o foo.tar.xz.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.8. git-bisect(1)

NAME

git-bisect - Use binary search to find the commit that introduced a bug

SYNOPSIS

git bisect <subcommand> <options>

DESCRIPTION

The command takes various subcommands, and different options depending on the subcommand:

git bisect start [--term-{old,good}=<term> --term-{new,bad}=<term>]
                 [--no-checkout] [<bad> [<good>...]] [--] [<paths>...]
git bisect (bad|new) [<rev>]
git bisect (good|old) [<rev>...]
git bisect terms [--term-good | --term-bad]
git bisect skip [(<rev>|<range>)...]
git bisect reset [<commit>]
git bisect visualize
git bisect replay <logfile>
git bisect log
git bisect run <cmd>...
git bisect help

This command uses a binary search algorithm to find which commit in your project's history introduced a bug. You use it by first telling it a "bad" commit that is known to contain the bug, and a "good" commit that is known to be before the bug was introduced. Then git bisect picks a commit between those two endpoints and asks you whether the selected commit is "good" or "bad". It continues narrowing down the range until it finds the exact commit that introduced the change.

In fact, git bisect can be used to find the commit that changed any property of your project; e.g., the commit that fixed a bug, or the commit that caused a benchmark's performance to improve. To support this more general usage, the terms "old" and "new" can be used in place of "good" and "bad", or you can choose your own terms. See section "Alternate terms" below for more information.

1. Basic bisect commands: start, bad, good

As an example, suppose you are trying to find the commit that broke a feature that was known to work in version v2.6.13-rc2 of your project. You start a bisect session as follows:

$ git bisect start
$ git bisect bad                 # Current version is bad
$ git bisect good v2.6.13-rc2    # v2.6.13-rc2 is known to be good

Once you have specified at least one bad and one good commit, git bisect selects a commit in the middle of that range of history, checks it out, and outputs something similar to the following:

Bisecting: 675 revisions left to test after this (roughly 10 steps)

You should now compile the checked-out version and test it. If that version works correctly, type

$ git bisect good

If that version is broken, type

$ git bisect bad

Then git bisect will respond with something like

Bisecting: 337 revisions left to test after this (roughly 9 steps)

Keep repeating the process: compile the tree, test it, and depending on whether it is good or bad run git bisect good or git bisect bad to ask for the next commit that needs testing.

Eventually there will be no more revisions left to inspect, and the command will print out a description of the first bad commit. The reference refs/bisect/bad will be left pointing at that commit.

2. Bisect reset

After a bisect session, to clean up the bisection state and return to the original HEAD, issue the following command:

$ git bisect reset

By default, this will return your tree to the commit that was checked out before git bisect start. (A new git bisect start will also do that, as it cleans up the old bisection state.)

With an optional argument, you can return to a different commit instead:

$ git bisect reset <commit>

For example, git bisect reset bisect/bad will check out the first bad revision, while git bisect reset HEAD will leave you on the current bisection commit and avoid switching commits at all.

3. Alternate terms

Sometimes you are not looking for the commit that introduced a breakage, but rather for a commit that caused a change between some other "old" state and "new" state. For example, you might be looking for the commit that introduced a particular fix. Or you might be looking for the first commit in which the source-code filenames were finally all converted to your company's naming standard. Or whatever.

In such cases it can be very confusing to use the terms "good" and "bad" to refer to "the state before the change" and "the state after the change". So instead, you can use the terms "old" and "new", respectively, in place of "good" and "bad". (But note that you cannot mix "good" and "bad" with "old" and "new" in a single session.)

In this more general usage, you provide git bisect with a "new" commit has some property and an "old" commit that doesn't have that property. Each time git bisect checks out a commit, you test if that commit has the property. If it does, mark the commit as "new"; otherwise, mark it as "old". When the bisection is done, git bisect will report which commit introduced the property.

To use "old" and "new" instead of "good" and bad, you must run git bisect start without commits as argument and then run the following commands to add the commits:

git bisect old [<rev>]

to indicate that a commit was before the sought change, or

git bisect new [<rev>...]

to indicate that it was after.

To get a reminder of the currently used terms, use

git bisect terms

You can get just the old (respectively new) term with git bisect term --term-old or git bisect term --term-good.

If you would like to use your own terms instead of "bad"/"good" or "new"/"old", you can choose any names you like (except existing bisect subcommands like reset, start, …) by starting the bisection using

git bisect start --term-old <term-old> --term-new <term-new>

For example, if you are looking for a commit that introduced a performance regression, you might use

git bisect start --term-old fast --term-new slow

Or if you are looking for the commit that fixed a bug, you might use

git bisect start --term-new fixed --term-old broken

Then, use git bisect <term-old> and git bisect <term-new> instead of git bisect good and git bisect bad to mark commits.

4. Bisect visualize

To see the currently remaining suspects in gitk, issue the following command during the bisection process:

$ git bisect visualize

view may also be used as a synonym for visualize.

If the DISPLAY environment variable is not set, git log is used instead. You can also give command-line options such as -p and --stat.

$ git bisect view --stat

5. Bisect log and bisect replay

After having marked revisions as good or bad, issue the following command to show what has been done so far:

$ git bisect log

If you discover that you made a mistake in specifying the status of a revision, you can save the output of this command to a file, edit it to remove the incorrect entries, and then issue the following commands to return to a corrected state:

$ git bisect reset
$ git bisect replay that-file

6. Avoiding testing a commit

If, in the middle of a bisect session, you know that the suggested revision is not a good one to test (e.g. it fails to build and you know that the failure does not have anything to do with the bug you are chasing), you can manually select a nearby commit and test that one instead.

For example:

$ git bisect good/bad                   # previous round was good or bad.
Bisecting: 337 revisions left to test after this (roughly 9 steps)
$ git bisect visualize                  # oops, that is uninteresting.
$ git reset --hard HEAD~3               # try 3 revisions before what
                                        # was suggested

Then compile and test the chosen revision, and afterwards mark the revision as good or bad in the usual manner.

7. Bisect skip

Instead of choosing a nearby commit by yourself, you can ask Git to do it for you by issuing the command:

$ git bisect skip                 # Current version cannot be tested

However, if you skip a commit adjacent to the one you are looking for, Git will be unable to tell exactly which of those commits was the first bad one.

You can also skip a range of commits, instead of just one commit, using range notation. For example:

$ git bisect skip v2.5..v2.6

This tells the bisect process that no commit after v2.5, up to and including v2.6, should be tested.

Note that if you also want to skip the first commit of the range you would issue the command:

$ git bisect skip v2.5 v2.5..v2.6

This tells the bisect process that the commits between v2.5 and v2.6 (inclusive) should be skipped.

8. Cutting down bisection by giving more parameters to bisect start

You can further cut down the number of trials, if you know what part of the tree is involved in the problem you are tracking down, by specifying path parameters when issuing the bisect start command:

$ git bisect start -- arch/i386 include/asm-i386

If you know beforehand more than one good commit, you can narrow the bisect space down by specifying all of the good commits immediately after the bad commit when issuing the bisect start command:

$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 --
                   # v2.6.20-rc6 is bad
                   # v2.6.20-rc4 and v2.6.20-rc1 are good

9. Bisect run

If you have a script that can tell if the current source code is good or bad, you can bisect by issuing the command:

$ git bisect run my_script arguments

Note that the script (my_script in the above example) should exit with code 0 if the current source code is good/old, and exit with a code between 1 and 127 (inclusive), except 125, if the current source code is bad/new.

Any other exit code will abort the bisect process. It should be noted that a program that terminates via exit(-1) leaves $? = 255, (see the exit(3) manual page), as the value is chopped with & 0377.

The special exit code 125 should be used when the current source code cannot be tested. If the script exits with this code, the current revision will be skipped (see git bisect skip above). 125 was chosen as the highest sensible value to use for this purpose, because 126 and 127 are used by POSIX shells to signal specific error status (127 is for command not found, 126 is for command found but not executable--these details do not matter, as they are normal errors in the script, as far as bisect run is concerned).

You may often find that during a bisect session you want to have temporary modifications (e.g. s/#define DEBUG 0/#define DEBUG 1/ in a header file, or "revision that does not have this commit needs this patch applied to work around another problem this bisection is not interested in") applied to the revision being tested.

To cope with such a situation, after the inner git bisect finds the next revision to test, the script can apply the patch before compiling, run the real test, and afterwards decide if the revision (possibly with the needed patch) passed the test and then rewind the tree to the pristine state. Finally the script should exit with the status of the real test to let the git bisect run command loop determine the eventual outcome of the bisect session.

OPTIONS

--no-checkout

Do not checkout the new working tree at each iteration of the bisection process. Instead just update a special reference named BISECT_HEAD to make it point to the commit that should be tested.

This option may be useful when the test you would perform in each step does not require a checked out tree.

If the repository is bare, --no-checkout is assumed.

EXAMPLES

  • Automatically bisect a broken build between v1.2 and HEAD:

    $ git bisect start HEAD v1.2 --      # HEAD is bad, v1.2 is good
    $ git bisect run make                # "make" builds the app
    $ git bisect reset                   # quit the bisect session
  • Automatically bisect a test failure between origin and HEAD:

    $ git bisect start HEAD origin --    # HEAD is bad, origin is good
    $ git bisect run make test           # "make test" builds and tests
    $ git bisect reset                   # quit the bisect session
  • Automatically bisect a broken test case:

    $ cat ~/test.sh
    #!/bin/sh
    make || exit 125                     # this skips broken builds
    ~/check_test_case.sh                 # does the test case pass?
    $ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
    $ git bisect run ~/test.sh
    $ git bisect reset                   # quit the bisect session

    Here we use a test.sh custom script. In this script, if make fails, we skip the current commit. check_test_case.sh should exit 0 if the test case passes, and exit 1 otherwise.

    It is safer if both test.sh and check_test_case.sh are outside the repository to prevent interactions between the bisect, make and test processes and the scripts.

  • Automatically bisect with temporary modifications (hot-fix):

    $ cat ~/test.sh
    #!/bin/sh
    
    # tweak the working tree by merging the hot-fix branch
    # and then attempt a build
    if      git merge --no-commit hot-fix &&
            make
    then
            # run project specific test and report its status
            ~/check_test_case.sh
            status=$?
    else
            # tell the caller this is untestable
            status=125
    fi
    
    # undo the tweak to allow clean flipping to the next commit
    git reset --hard
    
    # return control
    exit $status

    This applies modifications from a hot-fix branch before each test run, e.g. in case your build or test environment changed so that older revisions may need a fix which newer ones have already. (Make sure the hot-fix branch is based off a commit which is contained in all revisions which you are bisecting, so that the merge does not pull in too much, or use git cherry-pick instead of git merge.)

  • Automatically bisect a broken test case:

    $ git bisect start HEAD HEAD~10 --   # culprit is among the last 10
    $ git bisect run sh -c "make || exit 125; ~/check_test_case.sh"
    $ git bisect reset                   # quit the bisect session

    This shows that you can do without a run script if you write the test on a single line.

  • Locate a good region of the object graph in a damaged repository

    $ git bisect start HEAD <known-good-commit> [ <boundary-commit> ... ] --no-checkout
    $ git bisect run sh -c '
            GOOD=$(git for-each-ref "--format=%(objectname)" refs/bisect/good-*) &&
            git rev-list --objects BISECT_HEAD --not $GOOD >tmp.$$ &&
            git pack-objects --stdout >/dev/null <tmp.$$
            rc=$?
            rm -f tmp.$$
            test $rc = 0'
    
    $ git bisect reset                   # quit the bisect session

    In this case, when git bisect run finishes, bisect/bad will refer to a commit that has at least one parent whose reachable graph is fully traversable in the sense required by git pack objects.

  • Look for a fix instead of a regression in the code

    $ git bisect start
    $ git bisect new HEAD    # current commit is marked as new
    $ git bisect old HEAD~10 # the tenth commit from now is marked as old

    or:

$ git bisect start --term-old broken --term-new fixed
$ git bisect fixed
$ git bisect broken HEAD~10

1. Getting help

Use git bisect to get a short usage description, and git bisect help or git bisect -h to get a long usage description.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.9. git-blame(1)

NAME

git-blame - Show what revision and author last modified each line of a file

SYNOPSIS

git blame [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental]
            [-L <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>]
            [--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>]
            [--] <file>

DESCRIPTION

Annotates each line in the given file with information from the revision which last modified the line. Optionally, start annotating from the given revision.

When specified one or more times, -L restricts annotation to the requested lines.

The origin of lines is automatically followed across whole-file renames (currently there is no option to turn the rename-following off). To follow lines moved from one file to another, or to follow lines that were copied and pasted from another file, etc., see the -C and -M options.

The report does not tell you anything about lines which have been deleted or replaced; you need to use a tool such as git diff or the "pickaxe" interface briefly mentioned in the following paragraph.

Apart from supporting file annotation, Git also supports searching the development history for when a code snippet occurred in a change. This makes it possible to track when a code snippet was added to a file, moved or copied between files, and eventually deleted or replaced. It works by searching for a text string in the diff. A small example of the pickaxe interface that searches for blame_usage:

$ git log --pretty=oneline -S'blame_usage'
5040f17eba15504bad66b14a645bddd9b015ebb7 blame -S <ancestry-file>
ea4c7f9bf69e781dd0cd88d2bccb2bf5cc15c9a7 git-blame: Make the output

OPTIONS

-b
Show blank SHA-1 for boundary commits. This can also be controlled via the blame.blankboundary config option.
--root
Do not treat root commits as boundaries. This can also be controlled via the blame.showRoot config option.
--show-stats
Include additional statistics at the end of blame output.
-L <start>,<end> , -L :<funcname>

Annotate only the given line range. May be specified multiple times. Overlapping ranges are allowed.

<start> and <end> are optional. -L <start> or -L <start>, spans from <start> to end of file. -L ,<end> spans from start of file to <end>.

<start> and <end> can take one of these forms:

  • number

    If <start> or <end> is a number, it specifies an absolute line number (lines count from 1).

  • /regex/

    This form will use the first line matching the given POSIX regex. If <start> is a regex, it will search from the end of the previous -L range, if any, otherwise from the start of file. If <start> is ^/regex/, it will search from the start of file. If <end> is a regex, it will search starting at the line given by <start>.

  • +offset or -offset

    This is only valid for <end> and will specify a number of lines before or after the line given by <start>.

If :<funcname> is given in place of <start> and <end>, it is a regular expression that denotes the range from the first funcname line that matches <funcname>, up to the next funcname line. :<funcname> searches from the end of the previous -L range, if any, otherwise from the start of file. ^:<funcname> searches from the start of file.

-l
Show long rev (Default: off).
-t
Show raw timestamp (Default: off).
-S <revs-file>
Use revisions from revs-file instead of calling Section G.3.112, “git-rev-list(1)”.
--reverse
Walk history forward instead of backward. Instead of showing the revision in which a line appeared, this shows the last revision in which a line has existed. This requires a range of revision like START..END where the path to blame exists in START.
-p , --porcelain
Show in a format designed for machine consumption.
--line-porcelain
Show the porcelain format, but output commit information for each line, not just the first time a commit is referenced. Implies --porcelain.
--incremental
Show the result incrementally in a format designed for machine consumption.
--encoding=<encoding>
Specifies the encoding used to output author names and commit summaries. Setting it to none makes blame output unconverted data. For more information see the discussion about encoding in the Section G.3.68, “git-log(1)” manual page.
--contents <file>
When <rev> is not specified, the command annotates the changes starting backwards from the working tree copy. This flag makes the command pretend as if the working tree copy has the contents of the named file (specify - to make the command read from the standard input).
--date <format>
Specifies the format used to output dates. If --date is not provided, the value of the blame.date config variable is used. If the blame.date config variable is also not set, the iso format is used. For supported values, see the discussion of the --date option at Section G.3.68, “git-log(1)”.
--[no-]progress
Progress status is reported on the standard error stream by default when it is attached to a terminal. This flag enables progress reporting even if not attached to a terminal. Can't use --progress together with --porcelain or --incremental.
-M|<num>|

Detect moved or copied lines within a file. When a commit moves or copies a block of lines (e.g. the original file has A and then B, and the commit changes it to B and then A), the traditional blame algorithm notices only half of the movement and typically blames the lines that were moved up (i.e. B) to the parent and assigns blame to the lines that were moved down (i.e. A) to the child commit. With this option, both groups of lines are blamed on the parent by running extra passes of inspection.

<num> is optional but it is the lower bound on the number of alphanumeric characters that Git must detect as moving/copying within a file for it to associate those lines with the parent commit. The default value is 20.

-C|<num>|

In addition to -M, detect lines moved or copied from other files that were modified in the same commit. This is useful when you reorganize your program and move code around across files. When this option is given twice, the command additionally looks for copies from other files in the commit that creates the file. When this option is given three times, the command additionally looks for copies from other files in any commit.

<num> is optional but it is the lower bound on the number of alphanumeric characters that Git must detect as moving/copying between files for it to associate those lines with the parent commit. And the default value is 40. If there are more than one -C options given, the <num> argument of the last -C will take effect.

-h
Show help message.
-c
Use the same output mode as Section G.3.4, “git-annotate(1)” (Default: off).
--score-debug
Include debugging information related to the movement of lines between files (see -C) and lines moved within a file (see -M). The first number listed is the score. This is the number of alphanumeric characters detected as having been moved between or within files. This must be above a certain threshold for git blame to consider those lines of code to have been moved.
-f , --show-name
Show the filename in the original commit. By default the filename is shown if there is any line that came from a file with a different name, due to rename detection.
-n , --show-number
Show the line number in the original commit (Default: off).
-s
Suppress the author name and timestamp from the output.
-e , --show-email
Show the author email instead of author name (Default: off). This can also be controlled via the blame.showEmail config option.
-w
Ignore whitespace when comparing the parent's version and the child's to find where the lines came from.
--abbrev=<n>
Instead of using the default 7+1 hexadecimal digits as the abbreviated object name, use <n>+1 digits. Note that 1 column is used for a caret to mark the boundary commit.

THE PORCELAIN FORMAT

In this format, each line is output after a header; the header at the minimum has the first line which has:

  • 40-byte SHA-1 of the commit the line is attributed to;
  • the line number of the line in the original file;
  • the line number of the line in the final file;
  • on a line that starts a group of lines from a different commit than the previous one, the number of lines in this group. On subsequent lines this field is absent.

This header line is followed by the following information at least once for each commit:

  • the author name ("author"), email ("author-mail"), time ("author-time"), and time zone ("author-tz"); similarly for committer.
  • the filename in the commit that the line is attributed to.
  • the first line of the commit log message ("summary").

The contents of the actual line is output after the above header, prefixed by a TAB. This is to allow adding more header elements later.

The porcelain format generally suppresses commit information that has already been seen. For example, two lines that are blamed to the same commit will both be shown, but the details for that commit will be shown only once. This is more efficient, but may require more state be kept by the reader. The --line-porcelain option can be used to output full commit information for each line, allowing simpler (but less efficient) usage like:

# count the number of lines attributed to each author
git blame --line-porcelain file |
sed -n 's/^author //p' |
sort | uniq -c | sort -rn

SPECIFYING RANGES

Unlike git blame and git annotate in older versions of git, the extent of the annotation can be limited to both line ranges and revision ranges. The -L option, which limits annotation to a range of lines, may be specified multiple times.

When you are interested in finding the origin for lines 40-60 for file foo, you can use the -L option like so (they mean the same thing -- both ask for 21 lines starting at line 40):

git blame -L 40,60 foo
git blame -L 40,+21 foo

Also you can use a regular expression to specify the line range:

git blame -L '/^sub hello {/,/^}$/' foo

which limits the annotation to the body of the hello subroutine.

When you are not interested in changes older than version v2.6.18, or changes older than 3 weeks, you can use revision range specifiers similar to git rev-list:

git blame v2.6.18.. -- foo
git blame --since=3.weeks -- foo

When revision range specifiers are used to limit the annotation, lines that have not changed since the range boundary (either the commit v2.6.18 or the most recent commit that is more than 3 weeks old in the above example) are blamed for that range boundary commit.

A particularly useful way is to see if an added file has lines created by copy-and-paste from existing files. Sometimes this indicates that the developer was being sloppy and did not refactor the code properly. You can first find the commit that introduced the file with:

git log --diff-filter=A --pretty=short -- foo

and then annotate the change between the commit and its parents, using commit^! notation:

git blame -C -C -f $commit^! -- foo

INCREMENTAL OUTPUT

When called with --incremental option, the command outputs the result as it is built. The output generally will talk about lines touched by more recent commits first (i.e. the lines will be annotated out of order) and is meant to be used by interactive viewers.

The output format is similar to the Porcelain format, but it does not contain the actual lines from the file that is being annotated.

  1. Each blame entry always starts with a line of:

    <40-byte hex sha1> <sourceline> <resultline> <num_lines>

    Line numbers count from 1.

  2. The first time that a commit shows up in the stream, it has various other information about it printed out with a one-word tag at the beginning of each line describing the extra commit information (author, email, committer, dates, summary, etc.).
  3. Unlike the Porcelain format, the filename information is always given and terminates the entry:

    "filename" <whitespace-quoted-filename-goes-here>

    and thus it is really quite easy to parse for some line- and word-oriented parser (which should be quite natural for most scripting languages).

    [Note] Note

    For people who do parsing: to make it more robust, just ignore any lines between the first and last one ("<sha1>" and "filename" lines) where you do not recognize the tag words (or care about that particular one) at the beginning of the "extended information" lines. That way, if there is ever added information (like the commit encoding or extended commit commentary), a blame viewer will not care.

MAPPING AUTHORS

If the file .mailmap exists at the toplevel of the repository, or at the location pointed to by the mailmap.file or mailmap.blob configuration options, it is used to map author and committer names and email addresses to canonical real names and email addresses.

In the simple form, each line in the file consists of the canonical real name of an author, whitespace, and an email address used in the commit (enclosed by < and >) to map to the name. For example:

Proper Name <[email protected]>

The more complex forms are:

<[email protected]> <[email protected]>

which allows mailmap to replace only the email part of a commit, and:

Proper Name <[email protected]> <[email protected]>

which allows mailmap to replace both the name and the email of a commit matching the specified commit email address, and:

Proper Name <[email protected]> Commit Name <[email protected]>

which allows mailmap to replace both the name and the email of a commit matching both the specified commit name and email address.

Example 1: Your history contains commits by two authors, Jane and Joe, whose names appear in the repository under several forms:

Joe Developer <[email protected]>
Joe R. Developer <[email protected]>
Jane Doe <[email protected]>
Jane Doe <[email protected](none)>
Jane D. <[email protected](none)>

Now suppose that Joe wants his middle name initial used, and Jane prefers her family name fully spelled out. A proper .mailmap file would look like:

Jane Doe         <[email protected](none)>
Joe R. Developer <[email protected]>

Note how there is no need for an entry for <[email protected](none)>, because the real name of that author is already correct.

Example 2: Your repository contains commits from the following authors:

nick1 <[email protected]>
nick2 <[email protected]>
nick2 <[email protected]>
santa <[email protected]>
claus <[email protected]>
CTO <[email protected]>

Then you might want a .mailmap file that looks like:

<[email protected]>                       <[email protected]>
Some Dude <[email protected]>         nick1 <[email protected]>
Other Author <[email protected]>   nick2 <[email protected]>
Other Author <[email protected]>         <[email protected]>
Santa Claus <[email protected]> <[email protected]>

Use hash # for comments that are either on their own line, or after the email address.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.10. git-branch(1)

NAME

git-branch - List, create, or delete branches

SYNOPSIS

git branch [--color[=<when>] | --no-color] [-r | -a]
        [--list] [-v [--abbrev=<length> | --no-abbrev]]
        [--column[=<options>] | --no-column]
        [(--merged | --no-merged | --contains) [<commit>]] [--sort=<key>]
        [--points-at <object>] [<pattern>…]
git branch [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]
git branch (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
git branch --unset-upstream [<branchname>]
git branch (-m | -M) [<oldbranch>] <newbranch>
git branch (-d | -D) [-r] <branchname>…
git branch --edit-description [<branchname>]

DESCRIPTION

If --list is given, or if there are no non-option arguments, existing branches are listed; the current branch will be highlighted with an asterisk. Option -r causes the remote-tracking branches to be listed, and option -a shows both local and remote branches. If a <pattern> is given, it is used as a shell wildcard to restrict the output to matching branches. If multiple patterns are given, a branch is shown if it matches any of the patterns. Note that when providing a <pattern>, you must use --list; otherwise the command is interpreted as branch creation.

With --contains, shows only the branches that contain the named commit (in other words, the branches whose tip commits are descendants of the named commit). With --merged, only branches merged into the named commit (i.e. the branches whose tip commits are reachable from the named commit) will be listed. With --no-merged only branches not merged into the named commit will be listed. If the <commit> argument is missing it defaults to HEAD (i.e. the tip of the current branch).

The command's second form creates a new branch head named <branchname> which points to the current HEAD, or <start-point> if given.

Note that this will create the new branch, but it will not switch the working tree to it; use "git checkout <newbranch>" to switch to the new branch.

When a local branch is started off a remote-tracking branch, Git sets up the branch (specifically the branch.<name>.remote and branch.<name>.merge configuration entries) so that git pull will appropriately merge from the remote-tracking branch. This behavior may be changed via the global branch.autoSetupMerge configuration flag. That setting can be overridden by using the --track and --no-track options, and changed later using git branch --set-upstream-to.

With a -m or -M option, <oldbranch> will be renamed to <newbranch>. If <oldbranch> had a corresponding reflog, it is renamed to match <newbranch>, and a reflog entry is created to remember the branch renaming. If <newbranch> exists, -M must be used to force the rename to happen.

With a -d or -D option, <branchname> will be deleted. You may specify more than one branch for deletion. If the branch currently has a reflog then the reflog will also be deleted.

Use -r together with -d to delete remote-tracking branches. Note, that it only makes sense to delete remote-tracking branches if they no longer exist in the remote repository or if git fetch was configured not to fetch them again. See also the prune subcommand of Section G.3.106, “git-remote(1)” for a way to clean up all obsolete remote-tracking branches.

OPTIONS

-d , --delete
Delete a branch. The branch must be fully merged in its upstream branch, or in HEAD if no upstream was set with --track or --set-upstream.
-D
Shortcut for --delete --force.
-l , --create-reflog
Create the branch's reflog. This activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as "<branchname>@{yesterday}". Note that in non-bare repositories, reflogs are usually enabled by default by the core.logallrefupdates config option.
-f , --force
Reset <branchname> to <startpoint> if <branchname> exists already. Without -f git branch refuses to change an existing branch. In combination with -d (or --delete), allow deleting the branch irrespective of its merged status. In combination with -m (or --move), allow renaming the branch even if the new branch name already exists.
-m , --move
Move/rename a branch and the corresponding reflog.
-M
Shortcut for --move --force.
--color[=<when>]
Color branches to highlight current, local, and remote-tracking branches. The value must be always (the default), never, or auto.
--no-color
Turn off branch colors, even when the configuration file gives the default to color output. Same as --color=never.
--column[=<options>] , --no-column

Display branch listing in columns. See configuration variable column.branch for option syntax.--column and --no-column without options are equivalent to always and never respectively.

This option is only applicable in non-verbose mode.

-r , --remotes
List or delete (if used with -d) the remote-tracking branches.
-a , --all
List both remote-tracking branches and local branches.
--list
Activate the list mode. git branch <pattern> would try to create a branch, use git branch --list <pattern> to list matching branches.
-v , -vv , --verbose
When in list mode, show sha1 and commit subject line for each head, along with relationship to upstream branch (if any). If given twice, print the name of the upstream branch, as well (see also git remote show <remote>).
-q , --quiet
Be more quiet when creating or deleting a branch, suppressing non-error messages.
--abbrev=<length>
Alter the sha1's minimum display length in the output listing. The default value is 7 and can be overridden by the core.abbrev config option.
--no-abbrev
Display the full sha1s in the output listing rather than abbreviating them.
-t , --track

When creating a new branch, set up branch.<name>.remote and branch.<name>.merge configuration entries to mark the start-point branch as "upstream" from the new branch. This configuration will tell git to show the relationship between the two branches in git status and git branch -v. Furthermore, it directs git pull without arguments to pull from the upstream when the new branch is checked out.

This behavior is the default when the start point is a remote-tracking branch. Set the branch.autoSetupMerge configuration variable to false if you want git checkout and git branch to always behave as if --no-track were given. Set it to always if you want this behavior when the start-point is either a local or remote-tracking branch.

--no-track
Do not set up "upstream" configuration, even if the branch.autoSetupMerge configuration variable is true.
--set-upstream
If specified branch does not exist yet or if --force has been given, acts exactly like --track. Otherwise sets up configuration like --track would when creating the branch, except that where branch points to is not changed.
-u <upstream> , --set-upstream-to=<upstream>
Set up <branchname>'s tracking information so <upstream> is considered <branchname>'s upstream branch. If no <branchname> is specified, then it defaults to the current branch.
--unset-upstream
Remove the upstream information for <branchname>. If no branch is specified it defaults to the current branch.
--edit-description
Open an editor and edit the text to explain what the branch is for, to be used by various other commands (e.g. format-patch, request-pull, and merge (if enabled)). Multi-line explanations may be used.
--contains [<commit>]
Only list branches which contain the specified commit (HEAD if not specified). Implies --list.
--merged [<commit>]
Only list branches whose tips are reachable from the specified commit (HEAD if not specified). Implies --list.
--no-merged [<commit>]
Only list branches whose tips are not reachable from the specified commit (HEAD if not specified). Implies --list.
<branchname>
The name of the branch to create or delete. The new branch name must pass all checks defined by Section G.3.16, “git-check-ref-format(1)”. Some of these checks may restrict the characters allowed in a branch name.
<start-point>
The new branch head will point to this commit. It may be given as a branch name, a commit-id, or a tag. If this option is omitted, the current HEAD will be used instead.
<oldbranch>
The name of an existing branch to rename.
<newbranch>
The new name for an existing branch. The same restrictions as for <branchname> apply.
--sort=<key>
Sort based on the key given. Prefix - to sort in descending order of the value. You may use the --sort=<key> option multiple times, in which case the last key becomes the primary key. The keys supported are the same as those in git for-each-ref. Sort order defaults to sorting based on the full refname (including refs/... prefix). This lists detached HEAD (if present) first, then local branches and finally remote-tracking branches.
--points-at <object>
Only list branches of the given object.

Examples

Start development from a known tag
$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
$ cd my2.6
$ git branch my2.6.14 v2.6.14   1
$ git checkout my2.6.14

1

This step and the next one could be combined into a single step with "checkout -b my2.6.14 v2.6.14".

Delete an unneeded branch
$ git clone git://git.kernel.org/.../git.git my.git
$ cd my.git
$ git branch -d -r origin/todo origin/html origin/man   1
$ git branch -D test                                    2

1

Delete the remote-tracking branches "todo", "html" and "man". The next fetch or pull will create them again unless you configure them not to. See Section G.3.46, “git-fetch(1)”.

2

Delete the "test" branch even if the "master" branch (or whichever branch is currently checked out) does not have all commits from the test branch.

Notes

If you are creating a branch that you want to checkout immediately, it is easier to use the git checkout command with its -b option to create a branch and check it out with a single command.

The options --contains, --merged and --no-merged serve three related but different purposes:

  • --contains <commit> is used to find all branches which will need special attention if <commit> were to be rebased or amended, since those branches contain the specified <commit>.
  • --merged is used to find all branches which can be safely deleted, since those branches are fully contained by HEAD.
  • --no-merged is used to find branches which are candidates for merging into HEAD, since those branches are not fully contained by HEAD.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.11. git-bundle(1)

NAME

git-bundle - Move objects and refs by archive

SYNOPSIS

git bundle create <file> <git-rev-list-args>
git bundle verify <file>
git bundle list-heads <file> [<refname>…]
git bundle unbundle <file> [<refname>…]

DESCRIPTION

Some workflows require that one or more branches of development on one machine be replicated on another machine, but the two machines cannot be directly connected, and therefore the interactive Git protocols (git, ssh, http) cannot be used. This command provides support for git fetch and git pull to operate by packaging objects and references in an archive at the originating machine, then importing those into another repository using git fetch and git pull after moving the archive by some means (e.g., by sneakernet). As no direct connection between the repositories exists, the user must specify a basis for the bundle that is held by the destination repository: the bundle assumes that all objects in the basis are already in the destination repository.

OPTIONS

create <file>
Used to create a bundle named file. This requires the git-rev-list-args arguments to define the bundle contents.
verify <file>
Used to check that a bundle file is valid and will apply cleanly to the current repository. This includes checks on the bundle format itself as well as checking that the prerequisite commits exist and are fully linked in the current repository. git bundle prints a list of missing commits, if any, and exits with a non-zero status.
list-heads <file>
Lists the references defined in the bundle. If followed by a list of references, only references matching those given are printed out.
unbundle <file>
Passes the objects in the bundle to git index-pack for storage in the repository, then prints the names of all defined references. If a list of references is given, only references matching those in the list are printed. This command is really plumbing, intended to be called only by git fetch.
<git-rev-list-args>
A list of arguments, acceptable to git rev-parse and git rev-list (and containing a named ref, see SPECIFYING REFERENCES below), that specifies the specific objects and references to transport. For example, master~10..master causes the current master reference to be packaged along with all objects added since its 10th ancestor commit. There is no explicit limit to the number of references and objects that may be packaged.
[<refname>…]
A list of references used to limit the references reported as available. This is principally of use to git fetch, which expects to receive only those references asked for and not necessarily everything in the pack (in this case, git bundle acts like git fetch-pack).

SPECIFYING REFERENCES

git bundle will only package references that are shown by git show-ref: this includes heads, tags, and remote heads. References such as master~1 cannot be packaged, but are perfectly suitable for defining the basis. More than one reference may be packaged, and more than one basis can be specified. The objects packaged are those not contained in the union of the given bases. Each basis can be specified explicitly (e.g. ^master~10), or implicitly (e.g. master~10..master, --since=10.days.ago master).

It is very important that the basis used be held by the destination. It is okay to err on the side of caution, causing the bundle file to contain objects already in the destination, as these are ignored when unpacking at the destination.

EXAMPLE

Assume you want to transfer the history from a repository R1 on machine A to another repository R2 on machine B. For whatever reason, direct connection between A and B is not allowed, but we can move data from A to B via some mechanism (CD, email, etc.). We want to update R2 with development made on the branch master in R1.

To bootstrap the process, you can first create a bundle that does not have any basis. You can use a tag to remember up to what commit you last processed, in order to make it easy to later update the other repository with an incremental bundle:

machineA$ cd R1
machineA$ git bundle create file.bundle master
machineA$ git tag -f lastR2bundle master

Then you transfer file.bundle to the target machine B. Because this bundle does not require any existing object to be extracted, you can create a new repository on machine B by cloning from it:

machineB$ git clone -b master /home/me/tmp/file.bundle R2

This will define a remote called "origin" in the resulting repository that lets you fetch and pull from the bundle. The $GIT_DIR/config file in R2 will have an entry like this:

[remote "origin"]
    url = /home/me/tmp/file.bundle
    fetch = refs/heads/*:refs/remotes/origin/*

To update the resulting mine.git repository, you can fetch or pull after replacing the bundle stored at /home/me/tmp/file.bundle with incremental updates.

After working some more in the original repository, you can create an incremental bundle to update the other repository:

machineA$ cd R1
machineA$ git bundle create file.bundle lastR2bundle..master
machineA$ git tag -f lastR2bundle master

You then transfer the bundle to the other machine to replace /home/me/tmp/file.bundle, and pull from it.

machineB$ cd R2
machineB$ git pull

If you know up to what commit the intended recipient repository should have the necessary objects, you can use that knowledge to specify the basis, giving a cut-off point to limit the revisions and objects that go in the resulting bundle. The previous example used the lastR2bundle tag for this purpose, but you can use any other options that you would give to the Section G.3.68, “git-log(1)” command. Here are more examples:

You can use a tag that is present in both:

$ git bundle create mybundle v1.0.0..master

You can use a basis based on time:

$ git bundle create mybundle --since=10.days master

You can use the number of commits:

$ git bundle create mybundle -10 master

You can run git-bundle verify to see if you can extract from a bundle that was created with a basis:

$ git bundle verify mybundle

This will list what commits you must have in order to extract from the bundle and will error out if you do not have them.

A bundle from a recipient repository's point of view is just like a regular repository which it fetches or pulls from. You can, for example, map references when fetching:

$ git fetch mybundle master:localRef

You can also see what references it offers:

$ git ls-remote mybundle

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.12. git-cat-file(1)

NAME

git-cat-file - Provide content or type and size information for repository objects

SYNOPSIS

git cat-file (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv ) <object>
git cat-file (--batch | --batch-check) [--follow-symlinks]

DESCRIPTION

In its first form, the command provides the content or the type of an object in the repository. The type is required unless -t or -p is used to find the object type, or -s is used to find the object size, or --textconv is used (which implies type "blob").

In the second form, a list of objects (separated by linefeeds) is provided on stdin, and the SHA-1, type, and size of each object is printed on stdout.

OPTIONS

<object>
The name of the object to show. For a more complete list of ways to spell object names, see the "SPECIFYING REVISIONS" section in Section G.4.12, “gitrevisions(7)”.
-t
Instead of the content, show the object type identified by <object>.
-s
Instead of the content, show the object size identified by <object>.
-e
Suppress all output; instead exit with zero status if <object> exists and is a valid object.
-p
Pretty-print the contents of <object> based on its type.
<type>
Typically this matches the real type of <object> but asking for a type that can trivially be dereferenced from the given <object> is also permitted. An example is to ask for a "tree" with <object> being a commit object that contains it, or to ask for a "blob" with <object> being a tag object that points at it.
--textconv
Show the content as transformed by a textconv filter. In this case, <object> has be of the form <tree-ish>:<path>, or :<path> in order to apply the filter to the content recorded in the index at <path>.
--batch , --batch=<format>
Print object information and contents for each object provided on stdin. May not be combined with any other options or arguments. See the section BATCH OUTPUT below for details.
--batch-check , --batch-check=<format>
Print object information for each object provided on stdin. May not be combined with any other options or arguments. See the section BATCH OUTPUT below for details.
--batch-all-objects
Instead of reading a list of objects on stdin, perform the requested batch operation on all objects in the repository and any alternate object stores (not just reachable objects). Requires --batch or --batch-check be specified. Note that the objects are visited in order sorted by their hashes.
--buffer
Normally batch output is flushed after each object is output, so that a process can interactively read and write from cat-file. With this option, the output uses normal stdio buffering; this is much more efficient when invoking --batch-check on a large number of objects.
--allow-unknown-type
Allow -s or -t to query broken/corrupt objects of unknown type.
--follow-symlinks

With --batch or --batch-check, follow symlinks inside the repository when requesting objects with extended SHA-1 expressions of the form tree-ish:path-in-tree. Instead of providing output about the link itself, provide output about the linked-to object. If a symlink points outside the tree-ish (e.g. a link to /foo or a root-level link to ../foo), the portion of the link which is outside the tree will be printed.

This option does not (currently) work correctly when an object in the index is specified (e.g. :link instead of HEAD:link) rather than one in the tree.

This option cannot (currently) be used unless --batch or --batch-check is used.

For example, consider a git repository containing:

f: a file containing "hello\n"
link: a symlink to f
dir/link: a symlink to ../f
plink: a symlink to ../f
alink: a symlink to /etc/passwd

For a regular file f, echo HEAD:f | git cat-file --batch would print

ce013625030ba8dba906f756967f9e9ca394464a blob 6

And echo HEAD:link | git cat-file --batch --follow-symlinks would print the same thing, as would HEAD:dir/link, as they both point at HEAD:f.

Without --follow-symlinks, these would print data about the symlink itself. In the case of HEAD:link, you would see

4d1ae35ba2c8ec712fa2a379db44ad639ca277bd blob 1

Both plink and alink point outside the tree, so they would respectively print:

symlink 4
../f
symlink 11
/etc/passwd

OUTPUT

If -t is specified, one of the <type>.

If -s is specified, the size of the <object> in bytes.

If -e is specified, no output.

If -p is specified, the contents of <object> are pretty-printed.

If <type> is specified, the raw (though uncompressed) contents of the <object> will be returned.

BATCH OUTPUT

If --batch or --batch-check is given, cat-file will read objects from stdin, one per line, and print information about them. By default, the whole line is considered as an object, as if it were fed to Section G.3.113, “git-rev-parse(1)”.

You can specify the information shown for each object by using a custom <format>. The <format> is copied literally to stdout for each object, with placeholders of the form %(atom) expanded, followed by a newline. The available atoms are:

objectname
The 40-hex object name of the object.
objecttype
The type of of the object (the same as cat-file -t reports).
objectsize
The size, in bytes, of the object (the same as cat-file -s reports).
objectsize:disk
The size, in bytes, that the object takes up on disk. See the note about on-disk sizes in the CAVEATS section below.
deltabase
If the object is stored as a delta on-disk, this expands to the 40-hex sha1 of the delta base object. Otherwise, expands to the null sha1 (40 zeroes). See CAVEATS below.
rest
If this atom is used in the output string, input lines are split at the first whitespace boundary. All characters before that whitespace are considered to be the object name; characters after that first run of whitespace (i.e., the "rest" of the line) are output in place of the %(rest) atom.

If no format is specified, the default format is %(objectname) %(objecttype) %(objectsize).

If --batch is specified, the object information is followed by the object contents (consisting of %(objectsize) bytes), followed by a newline.

For example, --batch without a custom format would produce:

<sha1> SP <type> SP <size> LF
<contents> LF

Whereas --batch-check='%(objectname) %(objecttype)' would produce:

<sha1> SP <type> LF

If a name is specified on stdin that cannot be resolved to an object in the repository, then cat-file will ignore any custom format and print:

<object> SP missing LF

If --follow-symlinks is used, and a symlink in the repository points outside the repository, then cat-file will ignore any custom format and print:

symlink SP <size> LF
<symlink> LF

The symlink will either be absolute (beginning with a /), or relative to the tree root. For instance, if dir/link points to ../../foo, then <symlink> will be ../foo. <size> is the size of the symlink in bytes.

If --follow-symlinks is used, the following error messages will be displayed:

<object> SP missing LF

is printed when the initial symlink requested does not exist.

dangling SP <size> LF
<object> LF

is printed when the initial symlink exists, but something that it (transitive-of) points to does not.

loop SP <size> LF
<object> LF

is printed for symlink loops (or any symlinks that require more than 40 link resolutions to resolve).

notdir SP <size> LF
<object> LF

is printed when, during symlink resolution, a file is used as a directory name.

CAVEATS

Note that the sizes of objects on disk are reported accurately, but care should be taken in drawing conclusions about which refs or objects are responsible for disk usage. The size of a packed non-delta object may be much larger than the size of objects which delta against it, but the choice of which object is the base and which is the delta is arbitrary and is subject to change during a repack.

Note also that multiple copies of an object may be present in the object database; in this case, it is undefined which copy's size or delta base will be reported.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.13. git-check-attr(1)

NAME

git-check-attr - Display gitattributes information

SYNOPSIS

git check-attr [-a | --all | attr…] [--] pathname…
git check-attr --stdin [-z] [-a | --all | attr…]

DESCRIPTION

For every pathname, this command will list if each attribute is unspecified, set, or unset as a gitattribute on that pathname.

OPTIONS

-a, --all
List all attributes that are associated with the specified paths. If this option is used, then unspecified attributes will not be included in the output.
--cached
Consider .gitattributes in the index only, ignoring the working tree.
--stdin
Read pathnames from the standard input, one per line, instead of from the command-line.
-z
The output format is modified to be machine-parseable. If --stdin is also given, input paths are separated with a NUL character instead of a linefeed character.
--
Interpret all preceding arguments as attributes and all following arguments as path names.

If none of --stdin, --all, or -- is used, the first argument will be treated as an attribute and the rest of the arguments as pathnames.

OUTPUT

The output is of the form: <path> COLON SP <attribute> COLON SP <info> LF

unless -z is in effect, in which case NUL is used as delimiter: <path> NUL <attribute> NUL <info> NUL

<path> is the path of a file being queried, <attribute> is an attribute being queried and <info> can be either:

unspecified
when the attribute is not defined for the path.
unset
when the attribute is defined as false.
set
when the attribute is defined as true.
<value>
when a value has been assigned to the attribute.

Buffering happens as documented under the GIT_FLUSH option in Section G.3.1, “git(1)”. The caller is responsible for avoiding deadlocks caused by overfilling an input buffer or reading from an empty output buffer.

EXAMPLES

In the examples, the following .gitattributes file is used:

*.java diff=java -crlf myAttr
NoMyAttr.java !myAttr
README caveat=unspecified
  • Listing a single attribute:
$ git check-attr diff org/example/MyClass.java
org/example/MyClass.java: diff: java
  • Listing multiple attributes for a file:
$ git check-attr crlf diff myAttr -- org/example/MyClass.java
org/example/MyClass.java: crlf: unset
org/example/MyClass.java: diff: java
org/example/MyClass.java: myAttr: set
  • Listing all attributes for a file:
$ git check-attr --all -- org/example/MyClass.java
org/example/MyClass.java: diff: java
org/example/MyClass.java: myAttr: set
  • Listing an attribute for multiple files:
$ git check-attr myAttr -- org/example/MyClass.java org/example/NoMyAttr.java
org/example/MyClass.java: myAttr: set
org/example/NoMyAttr.java: myAttr: unspecified
  • Not all values are equally unambiguous:
$ git check-attr caveat README
README: caveat: unspecified

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.14. git-check-ignore(1)

NAME

git-check-ignore - Debug gitignore / exclude files

SYNOPSIS

git check-ignore [options] pathname…
git check-ignore [options] --stdin

DESCRIPTION

For each pathname given via the command-line or from a file via --stdin, check whether the file is excluded by .gitignore (or other input files to the exclude mechanism) and output the path if it is excluded.

By default, tracked files are not shown at all since they are not subject to exclude rules; but see --no-index.

OPTIONS

-q, --quiet
Don't output anything, just set exit status. This is only valid with a single pathname.
-v, --verbose
Also output details about the matching pattern (if any) for each given pathname. For precedence rules within and between exclude sources, see Section G.4.5, “gitignore(5)”.
--stdin
Read pathnames from the standard input, one per line, instead of from the command-line.
-z
The output format is modified to be machine-parseable (see below). If --stdin is also given, input paths are separated with a NUL character instead of a linefeed character.
-n, --non-matching
Show given paths which don't match any pattern. This only makes sense when --verbose is enabled, otherwise it would not be possible to distinguish between paths which match a pattern and those which don't.
--no-index
Don't look in the index when undertaking the checks. This can be used to debug why a path became tracked by e.g. git add . and was not ignored by the rules as expected by the user or when developing patterns including negation to match a path previously added with git add -f.

OUTPUT

By default, any of the given pathnames which match an ignore pattern will be output, one per line. If no pattern matches a given path, nothing will be output for that path; this means that path will not be ignored.

If --verbose is specified, the output is a series of lines of the form:

<source> <COLON> <linenum> <COLON> <pattern> <HT> <pathname>

<pathname> is the path of a file being queried, <pattern> is the matching pattern, <source> is the pattern's source file, and <linenum> is the line number of the pattern within that source. If the pattern contained a ! prefix or / suffix, it will be preserved in the output. <source> will be an absolute path when referring to the file configured by core.excludesFile, or relative to the repository root when referring to .git/info/exclude or a per-directory exclude file.

If -z is specified, the pathnames in the output are delimited by the null character; if --verbose is also specified then null characters are also used instead of colons and hard tabs:

<source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL>

If -n or --non-matching are specified, non-matching pathnames will also be output, in which case all fields in each output record except for <pathname> will be empty. This can be useful when running non-interactively, so that files can be incrementally streamed to STDIN of a long-running check-ignore process, and for each of these files, STDOUT will indicate whether that file matched a pattern or not. (Without this option, it would be impossible to tell whether the absence of output for a given file meant that it didn't match any pattern, or that the output hadn't been generated yet.)

Buffering happens as documented under the GIT_FLUSH option in Section G.3.1, “git(1)”. The caller is responsible for avoiding deadlocks caused by overfilling an input buffer or reading from an empty output buffer.

EXIT STATUS

0
One or more of the provided paths is ignored.
1
None of the provided paths are ignored.
128
A fatal error was encountered.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.15. git-check-mailmap(1)

NAME

git-check-mailmap - Show canonical names and email addresses of contacts

SYNOPSIS

git check-mailmap [options] <contact>…

DESCRIPTION

For each Name <[email protected]> or <[email protected]> from the command-line or standard input (when using --stdin), look up the person's canonical name and email address (see "Mapping Authors" below). If found, print them; otherwise print the input as-is.

OPTIONS

--stdin
Read contacts, one per line, from the standard input after exhausting contacts provided on the command-line.

OUTPUT

For each contact, a single line is output, terminated by a newline. If the name is provided or known to the mailmap, Name <[email protected]> is printed; otherwise only <[email protected]> is printed.

MAPPING AUTHORS

If the file .mailmap exists at the toplevel of the repository, or at the location pointed to by the mailmap.file or mailmap.blob configuration options, it is used to map author and committer names and email addresses to canonical real names and email addresses.

In the simple form, each line in the file consists of the canonical real name of an author, whitespace, and an email address used in the commit (enclosed by < and >) to map to the name. For example:

Proper Name <[email protected]>

The more complex forms are:

<[email protected]> <[email protected]>

which allows mailmap to replace only the email part of a commit, and:

Proper Name <[email protected]> <[email protected]>

which allows mailmap to replace both the name and the email of a commit matching the specified commit email address, and:

Proper Name <[email protected]> Commit Name <[email protected]>

which allows mailmap to replace both the name and the email of a commit matching both the specified commit name and email address.

Example 1: Your history contains commits by two authors, Jane and Joe, whose names appear in the repository under several forms:

Joe Developer <[email protected]>
Joe R. Developer <[email protected]>
Jane Doe <[email protected]>
Jane Doe <[email protected](none)>
Jane D. <[email protected](none)>

Now suppose that Joe wants his middle name initial used, and Jane prefers her family name fully spelled out. A proper .mailmap file would look like:

Jane Doe         <[email protected](none)>
Joe R. Developer <[email protected]>

Note how there is no need for an entry for <[email protected](none)>, because the real name of that author is already correct.

Example 2: Your repository contains commits from the following authors:

nick1 <[email protected]>
nick2 <[email protected]>
nick2 <[email protected]>
santa <[email protected]>
claus <[email protected]>
CTO <[email protected]>

Then you might want a .mailmap file that looks like:

<[email protected]>                       <[email protected]>
Some Dude <[email protected]>         nick1 <[email protected]>
Other Author <[email protected]>   nick2 <[email protected]>
Other Author <[email protected]>         <[email protected]>
Santa Claus <[email protected]> <[email protected]>

Use hash # for comments that are either on their own line, or after the email address.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.16. git-check-ref-format(1)

NAME

git-check-ref-format - Ensures that a reference name is well formed

SYNOPSIS

git check-ref-format [--normalize]
       [--[no-]allow-onelevel] [--refspec-pattern]
       <refname>
git check-ref-format --branch <branchname-shorthand>

DESCRIPTION

Checks if a given refname is acceptable, and exits with a non-zero status if it is not.

A reference is used in Git to specify branches and tags. A branch head is stored in the refs/heads hierarchy, while a tag is stored in the refs/tags hierarchy of the ref namespace (typically in $GIT_DIR/refs/heads and $GIT_DIR/refs/tags directories or, as entries in file $GIT_DIR/packed-refs if refs are packed by git gc).

Git imposes the following rules on how references are named:

  1. They can include slash / for hierarchical (directory) grouping, but no slash-separated component can begin with a dot . or end with the sequence .lock.
  2. They must contain at least one /. This enforces the presence of a category like heads/, tags/ etc. but the actual names are not restricted. If the --allow-onelevel option is used, this rule is waived.
  3. They cannot have two consecutive dots .. anywhere.
  4. They cannot have ASCII control characters (i.e. bytes whose values are lower than \040, or \177 DEL), space, tilde ~, caret ^, or colon : anywhere.
  5. They cannot have question-mark ?, asterisk *, or open bracket [ anywhere. See the --refspec-pattern option below for an exception to this rule.
  6. They cannot begin or end with a slash / or contain multiple consecutive slashes (see the --normalize option below for an exception to this rule)
  7. They cannot end with a dot ..
  8. They cannot contain a sequence @{.
  9. They cannot be the single character @.
  10. They cannot contain a \.

These rules make it easy for shell script based tools to parse reference names, pathname expansion by the shell when a reference name is used unquoted (by mistake), and also avoid ambiguities in certain reference name expressions (see Section G.4.12, “gitrevisions(7)”):

  1. A double-dot .. is often used as in ref1..ref2, and in some contexts this notation means ^ref1 ref2 (i.e. not in ref1 and in ref2).
  2. A tilde ~ and caret ^ are used to introduce the postfix nth parent and peel onion operation.
  3. A colon : is used as in srcref:dstref to mean "use srcref's value and store it in dstref" in fetch and push operations. It may also be used to select a specific object such as with git cat-file: "git cat-file blob v1.3.3:refs.c".
  4. at-open-brace @{ is used as a notation to access a reflog entry.

With the --branch option, it expands the previous branch syntax @{-n}. For example, @{-1} is a way to refer the last branch you were on. This option should be used by porcelains to accept this syntax anywhere a branch name is expected, so they can act as if you typed the branch name.

OPTIONS

--[no-]allow-onelevel
Controls whether one-level refnames are accepted (i.e., refnames that do not contain multiple /-separated components). The default is --no-allow-onelevel.
--refspec-pattern
Interpret <refname> as a reference name pattern for a refspec (as used with remote repositories). If this option is enabled, <refname> is allowed to contain a single * in the refspec (e.g., foo/bar*/baz or foo/bar*baz/ but not foo/bar*/baz*).
--normalize
Normalize refname by removing any leading slash (/) characters and collapsing runs of adjacent slashes between name components into a single slash. Iff the normalized refname is valid then print it to standard output and exit with a status of 0. (--print is a deprecated way to spell --normalize.)

EXAMPLES

  • Print the name of the previous branch:

    $ git check-ref-format --branch @{-1}
  • Determine the reference name to use for a new branch:

    $ ref=$(git check-ref-format --normalize "refs/heads/$newbranch") ||
    die "we do not like '$newbranch' as a branch name."

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.17. git-checkout-index(1)

NAME

git-checkout-index - Copy files from the index to the working tree

SYNOPSIS

git checkout-index [-u] [-q] [-a] [-f] [-n] [--prefix=<string>]
                   [--stage=<number>|all]
                   [--temp]
                   [-z] [--stdin]
                   [--] [<file>…]

DESCRIPTION

Will copy all files listed from the index to the working directory (not overwriting existing files).

OPTIONS

-u , --index
update stat information for the checked out entries in the index file.
-q , --quiet
be quiet if files exist or are not in the index
-f , --force
forces overwrite of existing files
-a , --all
checks out all files in the index. Cannot be used together with explicit filenames.
-n , --no-create
Don't checkout new files, only refresh files already checked out.
--prefix=<string>
When creating files, prepend <string> (usually a directory including a trailing /)
--stage=<number>|all
Instead of checking out unmerged entries, copy out the files from named stage. <number> must be between 1 and 3. Note: --stage=all automatically implies --temp.
--temp
Instead of copying the files to the working directory write the content to temporary files. The temporary name associations will be written to stdout.
--stdin
Instead of taking list of paths from the command line, read list of paths from the standard input. Paths are separated by LF (i.e. one path per line) by default.
-z
Only meaningful with --stdin; paths are separated with NUL character instead of LF.
--
Do not interpret any more arguments as options.

The order of the flags used to matter, but not anymore.

Just doing git checkout-index does nothing. You probably meant git checkout-index -a. And if you want to force it, you want git checkout-index -f -a.

Intuitiveness is not the goal here. Repeatability is. The reason for the "no arguments means no work" behavior is that from scripts you are supposed to be able to do:

$ find . -name '*.h' -print0 | xargs -0 git checkout-index -f --

which will force all existing *.h files to be replaced with their cached copies. If an empty command line implied "all", then this would force-refresh everything in the index, which was not the point. But since git checkout-index accepts --stdin it would be faster to use:

$ find . -name '*.h' -print0 | git checkout-index -f -z --stdin

The -- is just a good idea when you know the rest will be filenames; it will prevent problems with a filename of, for example, -a. Using -- is probably a good policy in scripts.

Using --temp or --stage=all

When --temp is used (or implied by --stage=all) git checkout-index will create a temporary file for each index entry being checked out. The index will not be updated with stat information. These options can be useful if the caller needs all stages of all unmerged entries so that the unmerged files can be processed by an external merge tool.

A listing will be written to stdout providing the association of temporary file names to tracked path names. The listing format has two variations:

  1. tempname TAB path RS

    The first format is what gets used when --stage is omitted or is not --stage=all. The field tempname is the temporary file name holding the file content and path is the tracked path name in the index. Only the requested entries are output.

  2. stage1temp SP stage2temp SP stage3tmp TAB path RS

    The second format is what gets used when --stage=all. The three stage temporary fields (stage1temp, stage2temp, stage3temp) list the name of the temporary file if there is a stage entry in the index or . if there is no stage entry. Paths which only have a stage 0 entry will always be omitted from the output.

In both formats RS (the record separator) is newline by default but will be the null byte if -z was passed on the command line. The temporary file names are always safe strings; they will never contain directory separators or whitespace characters. The path field is always relative to the current directory and the temporary file names are always relative to the top level directory.

If the object being copied out to a temporary file is a symbolic link the content of the link will be written to a normal file. It is up to the end-user or the Porcelain to make use of this information.

EXAMPLES

To update and refresh only the files already checked out
$ git checkout-index -n -f -a && git update-index --ignore-missing --refresh
Using git checkout-index to "export an entire tree"

The prefix ability basically makes it trivial to use git checkout-index as an "export as tree" function. Just read the desired tree into the index, and do:

$ git checkout-index --prefix=git-export-dir/ -a

git checkout-index will "export" the index into the specified directory.

The final "/" is important. The exported name is literally just prefixed with the specified string. Contrast this with the following example.

Export files with a prefix
$ git checkout-index --prefix=.merged- Makefile

This will check out the currently cached copy of Makefile into the file .merged-Makefile.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.18. git-checkout(1)

NAME

git-checkout - Switch branches or restore working tree files

SYNOPSIS

git checkout [-q] [-f] [-m] [<branch>]
git checkout [-q] [-f] [-m] --detach [<branch>]
git checkout [-q] [-f] [-m] [--detach] <commit>
git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>…
git checkout [-p|--patch] [<tree-ish>] [--] [<paths>…]

DESCRIPTION

Updates files in the working tree to match the version in the index or the specified tree. If no paths are given, git checkout will also update HEAD to set the specified branch as the current branch.

git checkout <branch>

To prepare for working on <branch>, switch to it by updating the index and the files in the working tree, and by pointing HEAD at the branch. Local modifications to the files in the working tree are kept, so that they can be committed to the <branch>.

If <branch> is not found but there does exist a tracking branch in exactly one remote (call it <remote>) with a matching name, treat as equivalent to

$ git checkout -b <branch> --track <remote>/<branch>

You could omit <branch>, in which case the command degenerates to "check out the current branch", which is a glorified no-op with a rather expensive side-effects to show only the tracking information, if exists, for the current branch.

git checkout -b|-B <new_branch> [<start point>]

Specifying -b causes a new branch to be created as if Section G.3.10, “git-branch(1)” were called and then checked out. In this case you can use the --track or --no-track options, which will be passed to git branch. As a convenience, --track without -b implies branch creation; see the description of --track below.

If -B is given, <new_branch> is created if it doesn't exist; otherwise, it is reset. This is the transactional equivalent of

$ git branch -f <branch> [<start point>]
$ git checkout <branch>

that is to say, the branch is not reset/created unless "git checkout" is successful.

git checkout --detach [<branch>] , git checkout [--detach] <commit>

Prepare to work on top of <commit>, by detaching HEAD at it (see "DETACHED HEAD" section), and updating the index and the files in the working tree. Local modifications to the files in the working tree are kept, so that the resulting working tree will be the state recorded in the commit plus the local modifications.

When the <commit> argument is a branch name, the --detach option can be used to detach HEAD at the tip of the branch (git checkout <branch> would check out that branch without detaching HEAD).

Omitting <branch> detaches HEAD at the tip of the current branch.

git checkout [-p|--patch] [<tree-ish>] [--] <pathspec>…

When <paths> or --patch are given, git checkout does not switch branches. It updates the named paths in the working tree from the index file or from a named <tree-ish> (most often a commit). In this case, the -b and --track options are meaningless and giving either of them results in an error. The <tree-ish> argument can be used to specify a specific tree-ish (i.e. commit, tag or tree) to update the index for the given paths before updating the working tree.

git checkout with <paths> or --patch is used to restore modified or deleted paths to their original contents from the index or replace paths with the contents from a named <tree-ish> (most often a commit-ish).

The index may contain unmerged entries because of a previous failed merge. By default, if you try to check out such an entry from the index, the checkout operation will fail and nothing will be checked out. Using -f will ignore these unmerged entries. The contents from a specific side of the merge can be checked out of the index by using --ours or --theirs. With -m, changes made to the working tree file can be discarded to re-create the original conflicted merge result.

OPTIONS

-q , --quiet
Quiet, suppress feedback messages.
--[no-]progress
Progress status is reported on the standard error stream by default when it is attached to a terminal, unless --quiet is specified. This flag enables progress reporting even if not attached to a terminal, regardless of --quiet.
-f , --force

When switching branches, proceed even if the index or the working tree differs from HEAD. This is used to throw away local changes.

When checking out paths from the index, do not fail upon unmerged entries; instead, unmerged entries are ignored.

--ours , --theirs

When checking out paths from the index, check out stage #2 (ours) or #3 (theirs) for unmerged paths.

Note that during git rebase and git pull --rebase, ours and theirs may appear swapped; --ours gives the version from the branch the changes are rebased onto, while --theirs gives the version from the branch that holds your work that is being rebased.

This is because rebase is used in a workflow that treats the history at the remote as the shared canonical one, and treats the work done on the branch you are rebasing as the third-party work to be integrated, and you are temporarily assuming the role of the keeper of the canonical history during the rebase. As the keeper of the canonical history, you need to view the history from the remote as ours (i.e. "our shared canonical history"), while what you did on your side branch as theirs (i.e. "one contributor's work on top of it").

-b <new_branch>
Create a new branch named <new_branch> and start it at <start_point>; see Section G.3.10, “git-branch(1)” for details.
-B <new_branch>
Creates the branch <new_branch> and start it at <start_point>; if it already exists, then reset it to <start_point>. This is equivalent to running "git branch" with "-f"; see Section G.3.10, “git-branch(1)” for details.
-t , --track

When creating a new branch, set up "upstream" configuration. See "--track" in Section G.3.10, “git-branch(1)” for details.

If no -b option is given, the name of the new branch will be derived from the remote-tracking branch, by looking at the local part of the refspec configured for the corresponding remote, and then stripping the initial part up to the "*". This would tell us to use "hack" as the local branch when branching off of "origin/hack" (or "remotes/origin/hack", or even "refs/remotes/origin/hack"). If the given name has no slash, or the above guessing results in an empty name, the guessing is aborted. You can explicitly give a name with -b in such a case.

--no-track
Do not set up "upstream" configuration, even if the branch.autoSetupMerge configuration variable is true.
-l
Create the new branch's reflog; see Section G.3.10, “git-branch(1)” for details.
--detach
Rather than checking out a branch to work on it, check out a commit for inspection and discardable experiments. This is the default behavior of "git checkout <commit>" when <commit> is not a branch name. See the "DETACHED HEAD" section below for details.
--orphan <new_branch>

Create a new orphan branch, named <new_branch>, started from <start_point> and switch to it. The first commit made on this new branch will have no parents and it will be the root of a new history totally disconnected from all the other branches and commits.

The index and the working tree are adjusted as if you had previously run "git checkout <start_point>". This allows you to start a new history that records a set of paths similar to <start_point> by easily running "git commit -a" to make the root commit.

This can be useful when you want to publish the tree from a commit without exposing its full history. You might want to do this to publish an open source branch of a project whose current tree is "clean", but whose full history contains proprietary or otherwise encumbered bits of code.

If you want to start a disconnected history that records a set of paths that is totally different from the one of <start_point>, then you should clear the index and the working tree right after creating the orphan branch by running "git rm -rf ." from the top level of the working tree. Afterwards you will be ready to prepare your new files, repopulating the working tree, by copying them from elsewhere, extracting a tarball, etc.

--ignore-skip-worktree-bits
In sparse checkout mode, git checkout -- <paths> would update only entries matched by <paths> and sparse patterns in $GIT_DIR/info/sparse-checkout. This option ignores the sparse patterns and adds back any files in <paths>.
-m , --merge

When switching branches, if you have local modifications to one or more files that are different between the current branch and the branch to which you are switching, the command refuses to switch branches in order to preserve your modifications in context. However, with this option, a three-way merge between the current branch, your working tree contents, and the new branch is done, and you will be on the new branch.

When a merge conflict happens, the index entries for conflicting paths are left unmerged, and you need to resolve the conflicts and mark the resolved paths with git add (or git rm if the merge should result in deletion of the path).

When checking out paths from the index, this option lets you recreate the conflicted merge in the specified paths.

--conflict=<style>
The same as --merge option above, but changes the way the conflicting hunks are presented, overriding the merge.conflictStyle configuration variable. Possible values are "merge" (default) and "diff3" (in addition to what is shown by "merge" style, shows the original contents).
-p , --patch

Interactively select hunks in the difference between the <tree-ish> (or the index, if unspecified) and the working tree. The chosen hunks are then applied in reverse to the working tree (and if a <tree-ish> was specified, the index).

This means that you can use git checkout -p to selectively discard edits from your current working tree. See the Interactive Mode section of Section G.3.2, “git-add(1)” to learn how to operate the --patch mode.

--ignore-other-worktrees
git checkout refuses when the wanted ref is already checked out by another worktree. This option makes it check the ref out anyway. In other words, the ref can be held by more than one worktree.
<branch>

Branch to checkout; if it refers to a branch (i.e., a name that, when prepended with "refs/heads/", is a valid ref), then that branch is checked out. Otherwise, if it refers to a valid commit, your HEAD becomes "detached" and you are no longer on any branch (see below for details).

As a special case, the "@{-N}" syntax for the N-th last branch/commit checks out branches (instead of detaching). You may also specify - which is synonymous with "@{-1}".

As a further special case, you may use "A...B" as a shortcut for the merge base of A and B if there is exactly one merge base. You can leave out at most one of A and B, in which case it defaults to HEAD.

<new_branch>
Name for the new branch.
<start_point>
The name of a commit at which to start the new branch; see Section G.3.10, “git-branch(1)” for details. Defaults to HEAD.
<tree-ish>
Tree to checkout from (when paths are given). If not specified, the index will be used.

DETACHED HEAD

HEAD normally refers to a named branch (e.g. master). Meanwhile, each branch refers to a specific commit. Let's look at a repo with three commits, one of them tagged, and with branch master checked out:

           HEAD (refers to branch 'master')
            |
            v
a---b---c  branch 'master' (refers to commit 'c')
    ^
    |
  tag 'v2.0' (refers to commit 'b')

When a commit is created in this state, the branch is updated to refer to the new commit. Specifically, git commit creates a new commit d, whose parent is commit c, and then updates branch master to refer to new commit d. HEAD still refers to branch master and so indirectly now refers to commit d:

$ edit; git add; git commit

               HEAD (refers to branch 'master')
                |
                v
a---b---c---d  branch 'master' (refers to commit 'd')
    ^
    |
  tag 'v2.0' (refers to commit 'b')

It is sometimes useful to be able to checkout a commit that is not at the tip of any named branch, or even to create a new commit that is not referenced by a named branch. Let's look at what happens when we checkout commit b (here we show two ways this may be done):

$ git checkout v2.0  # or
$ git checkout master^^

   HEAD (refers to commit 'b')
    |
    v
a---b---c---d  branch 'master' (refers to commit 'd')
    ^
    |
  tag 'v2.0' (refers to commit 'b')

Notice that regardless of which checkout command we use, HEAD now refers directly to commit b. This is known as being in detached HEAD state. It means simply that HEAD refers to a specific commit, as opposed to referring to a named branch. Let's see what happens when we create a commit:

$ edit; git add; git commit

     HEAD (refers to commit 'e')
      |
      v
      e
     /
a---b---c---d  branch 'master' (refers to commit 'd')
    ^
    |
  tag 'v2.0' (refers to commit 'b')

There is now a new commit e, but it is referenced only by HEAD. We can of course add yet another commit in this state:

$ edit; git add; git commit

         HEAD (refers to commit 'f')
          |
          v
      e---f
     /
a---b---c---d  branch 'master' (refers to commit 'd')
    ^
    |
  tag 'v2.0' (refers to commit 'b')

In fact, we can perform all the normal Git operations. But, let's look at what happens when we then checkout master:

$ git checkout master

               HEAD (refers to branch 'master')
      e---f     |
     /          v
a---b---c---d  branch 'master' (refers to commit 'd')
    ^
    |
  tag 'v2.0' (refers to commit 'b')

It is important to realize that at this point nothing refers to commit f. Eventually commit f (and by extension commit e) will be deleted by the routine Git garbage collection process, unless we create a reference before that happens. If we have not yet moved away from commit f, any of these will create a reference to it:

$ git checkout -b foo   1
$ git branch foo        2
$ git tag foo           3

1

creates a new branch foo, which refers to commit f, and then updates HEAD to refer to branch foo. In other words, we'll no longer be in detached HEAD state after this command.

2

similarly creates a new branch foo, which refers to commit f, but leaves HEAD detached.

3

creates a new tag foo, which refers to commit f, leaving HEAD detached.

If we have moved away from commit f, then we must first recover its object name (typically by using git reflog), and then we can create a reference to it. For example, to see the last two commits to which HEAD referred, we can use either of these commands:

$ git reflog -2 HEAD # or
$ git log -g -2 HEAD

EXAMPLES

  1. The following sequence checks out the master branch, reverts the Makefile to two revisions back, deletes hello.c by mistake, and gets it back from the index.

    $ git checkout master             1
    $ git checkout master~2 Makefile  2
    $ rm -f hello.c
    $ git checkout hello.c            3

    1

    switch branch

    2

    take a file out of another commit

    3

    restore hello.c from the index

    If you want to check out all C source files out of the index, you can say

    $ git checkout -- '*.c'

    Note the quotes around *.c. The file hello.c will also be checked out, even though it is no longer in the working tree, because the file globbing is used to match entries in the index (not in the working tree by the shell).

    If you have an unfortunate branch that is named hello.c, this step would be confused as an instruction to switch to that branch. You should instead write:

    $ git checkout -- hello.c
  2. After working in the wrong branch, switching to the correct branch would be done using:

    $ git checkout mytopic

    However, your "wrong" branch and correct "mytopic" branch may differ in files that you have modified locally, in which case the above checkout would fail like this:

    $ git checkout mytopic
    error: You have local changes to 'frotz'; not switching branches.

    You can give the -m flag to the command, which would try a three-way merge:

    $ git checkout -m mytopic
    Auto-merging frotz

    After this three-way merge, the local modifications are not registered in your index file, so git diff would show you what changes you made since the tip of the new branch.

  3. When a merge conflict happens during switching branches with the -m option, you would see something like this:

    $ git checkout -m mytopic
    Auto-merging frotz
    ERROR: Merge conflict in frotz
    fatal: merge program failed

    At this point, git diff shows the changes cleanly merged as in the previous example, as well as the changes in the conflicted files. Edit and resolve the conflict and mark it resolved with git add as usual:

    $ edit frotz
    $ git add frotz

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.19. git-cherry-pick(1)

NAME

git-cherry-pick - Apply the changes introduced by some existing commits

SYNOPSIS

git cherry-pick [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]
                  [-S[<keyid>]] <commit>…
git cherry-pick --continue
git cherry-pick --quit
git cherry-pick --abort

DESCRIPTION

Given one or more existing commits, apply the change each one introduces, recording a new commit for each. This requires your working tree to be clean (no modifications from the HEAD commit).

When it is not obvious how to apply a change, the following happens:

  1. The current branch and HEAD pointer stay at the last commit successfully made.
  2. The CHERRY_PICK_HEAD ref is set to point at the commit that introduced the change that is difficult to apply.
  3. Paths in which the change applied cleanly are updated both in the index file and in your working tree.
  4. For conflicting paths, the index file records up to three versions, as described in the "TRUE MERGE" section of Section G.3.79, “git-merge(1)”. The working tree files will include a description of the conflict bracketed by the usual conflict markers <<<<<<< and >>>>>>>.
  5. No other modifications are made.

See Section G.3.79, “git-merge(1)” for some hints on resolving such conflicts.

OPTIONS

<commit>…
Commits to cherry-pick. For a more complete list of ways to spell commits, see Section G.4.12, “gitrevisions(7)”. Sets of commits can be passed but no traversal is done by default, as if the --no-walk option was specified, see Section G.3.112, “git-rev-list(1)”. Note that specifying a range will feed all <commit>… arguments to a single revision walk (see a later example that uses maint master..next).
-e , --edit
With this option, git cherry-pick will let you edit the commit message prior to committing.
-x
When recording the commit, append a line that says "(cherry picked from commit …)" to the original commit message in order to indicate which commit this change was cherry-picked from. This is done only for cherry picks without conflicts. Do not use this option if you are cherry-picking from your private branch because the information is useless to the recipient. If on the other hand you are cherry-picking between two publicly visible branches (e.g. backporting a fix to a maintenance branch for an older release from a development branch), adding this information can be useful.
-r
It used to be that the command defaulted to do -x described above, and -r was to disable it. Now the default is not to do -x so this option is a no-op.
-m parent-number , --mainline parent-number
Usually you cannot cherry-pick a merge because you do not know which side of the merge should be considered the mainline. This option specifies the parent number (starting from 1) of the mainline and allows cherry-pick to replay the change relative to the specified parent.
-n , --no-commit

Usually the command automatically creates a sequence of commits. This flag applies the changes necessary to cherry-pick each named commit to your working tree and the index, without making any commit. In addition, when this option is used, your index does not have to match the HEAD commit. The cherry-pick is done against the beginning state of your index.

This is useful when cherry-picking more than one commits' effect to your index in a row.

-s , --signoff
Add Signed-off-by line at the end of the commit message. See the signoff option in Section G.3.26, “git-commit(1)” for more information.
-S[<keyid>] , --gpg-sign[=<keyid>]
GPG-sign commits. The keyid argument is optional and defaults to the committer identity; if specified, it must be stuck to the option without a space.
--ff
If the current HEAD is the same as the parent of the cherry-pick'ed commit, then a fast forward to this commit will be performed.
--allow-empty
By default, cherry-picking an empty commit will fail, indicating that an explicit invocation of git commit --allow-empty is required. This option overrides that behavior, allowing empty commits to be preserved automatically in a cherry-pick. Note that when "--ff" is in effect, empty commits that meet the "fast-forward" requirement will be kept even without this option. Note also, that use of this option only keeps commits that were initially empty (i.e. the commit recorded the same tree as its parent). Commits which are made empty due to a previous commit are dropped. To force the inclusion of those commits use --keep-redundant-commits.
--allow-empty-message
By default, cherry-picking a commit with an empty message will fail. This option overrides that behaviour, allowing commits with empty messages to be cherry picked.
--keep-redundant-commits
If a commit being cherry picked duplicates a commit already in the current history, it will become empty. By default these redundant commits cause cherry-pick to stop so the user can examine the commit. This option overrides that behavior and creates an empty commit object. Implies --allow-empty.
--strategy=<strategy>
Use the given merge strategy. Should only be used once. See the MERGE STRATEGIES section in Section G.3.79, “git-merge(1)” for details.
-X<option> , --strategy-option=<option>
Pass the merge strategy-specific option through to the merge strategy. See Section G.3.79, “git-merge(1)” for details.

SEQUENCER SUBCOMMANDS

--continue
Continue the operation in progress using the information in .git/sequencer. Can be used to continue after resolving conflicts in a failed cherry-pick or revert.
--quit
Forget about the current operation in progress. Can be used to clear the sequencer state after a failed cherry-pick or revert.
--abort
Cancel the operation and return to the pre-sequence state.

EXAMPLES

git cherry-pick master
Apply the change introduced by the commit at the tip of the master branch and create a new commit with this change.
git cherry-pick ..master , git cherry-pick ^HEAD master
Apply the changes introduced by all commits that are ancestors of master but not of HEAD to produce new commits.
git cherry-pick maint next ^master , git cherry-pick maint master..next
Apply the changes introduced by all commits that are ancestors of maint or next, but not master or any of its ancestors. Note that the latter does not mean maint and everything between master and next; specifically, maint will not be used if it is included in master.
git cherry-pick master~4 master~2
Apply the changes introduced by the fifth and third last commits pointed to by master and create 2 new commits with these changes.
git cherry-pick -n master~1 next
Apply to the working tree and the index the changes introduced by the second last commit pointed to by master and by the last commit pointed to by next, but do not create any commit with these changes.
git cherry-pick --ff ..next
If history is linear and HEAD is an ancestor of next, update the working tree and advance the HEAD pointer to match next. Otherwise, apply the changes introduced by those commits that are in next but not HEAD to the current branch, creating a new commit for each new change.
git rev-list --reverse master -- README | git cherry-pick -n --stdin
Apply the changes introduced by all commits on the master branch that touched README to the working tree and index, so the result can be inspected and made into a single new commit if suitable.

The following sequence attempts to backport a patch, bails out because the code the patch applies to has changed too much, and then tries again, this time exercising more care about matching up context lines.

$ git cherry-pick topic^             1
$ git diff                           2
$ git reset --merge ORIG_HEAD        3
$ git cherry-pick -Xpatience topic^  4

1

apply the change that would be shown by git show topic^. In this example, the patch does not apply cleanly, so information about the conflict is written to the index and working tree and no new commit results.

2

summarize changes to be reconciled

3

cancel the cherry-pick. In other words, return to the pre-cherry-pick state, preserving any local modifications you had in the working tree.

4

try to apply the change introduced by topic^ again, spending extra time to avoid mistakes based on incorrectly matching context lines.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.20. git-cherry(1)

NAME

git-cherry - Find commits yet to be applied to upstream

SYNOPSIS

git cherry [-v] [<upstream> [<head> [<limit>]]]

DESCRIPTION

Determine whether there are commits in <head>..<upstream> that are equivalent to those in the range <limit>..<head>.

The equivalence test is based on the diff, after removing whitespace and line numbers. git-cherry therefore detects when commits have been "copied" by means of Section G.3.19, “git-cherry-pick(1)”, Section G.3.3, “git-am(1)” or Section G.3.99, “git-rebase(1)”.

Outputs the SHA1 of every commit in <limit>..<head>, prefixed with - for commits that have an equivalent in <upstream>, and + for commits that do not.

OPTIONS

-v
Show the commit subjects next to the SHA1s.
<upstream>
Upstream branch to search for equivalent commits. Defaults to the upstream branch of HEAD.
<head>
Working branch; defaults to HEAD.
<limit>
Do not report commits up to (and including) limit.

EXAMPLES

1. Patch workflows

git-cherry is frequently used in patch-based workflows (see Section G.4.15, “gitworkflows(7)”) to determine if a series of patches has been applied by the upstream maintainer. In such a workflow you might create and send a topic branch like this:

$ git checkout -b topic origin/master
# work and create some commits
$ git format-patch origin/master
$ git send-email ... 00*

Later, you can see whether your changes have been applied by saying (still on topic):

$ git fetch  # update your notion of origin/master
$ git cherry -v

2. Concrete example

In a situation where topic consisted of three commits, and the maintainer applied two of them, the situation might look like:

$ git log --graph --oneline --decorate --boundary origin/master...topic
* 7654321 (origin/master) upstream tip commit
[... snip some other commits ...]
* cccc111 cherry-pick of C
* aaaa111 cherry-pick of A
[... snip a lot more that has happened ...]
| * cccc000 (topic) commit C
| * bbbb000 commit B
| * aaaa000 commit A
|/
o 1234567 branch point

In such cases, git-cherry shows a concise summary of what has yet to be applied:

$ git cherry origin/master topic
- cccc000... commit C
+ bbbb000... commit B
- aaaa000... commit A

Here, we see that the commits A and C (marked with -) can be dropped from your topic branch when you rebase it on top of origin/master, while the commit B (marked with +) still needs to be kept so that it will be sent to be applied to origin/master.

3. Using a limit

The optional <limit> is useful in cases where your topic is based on other work that is not in upstream. Expanding on the previous example, this might look like:

$ git log --graph --oneline --decorate --boundary origin/master...topic
* 7654321 (origin/master) upstream tip commit
[... snip some other commits ...]
* cccc111 cherry-pick of C
* aaaa111 cherry-pick of A
[... snip a lot more that has happened ...]
| * cccc000 (topic) commit C
| * bbbb000 commit B
| * aaaa000 commit A
| * 0000fff (base) unpublished stuff F
[... snip ...]
| * 0000aaa unpublished stuff A
|/
o 1234567 merge-base between upstream and topic

By specifying base as the limit, you can avoid listing commits between base and topic:

$ git cherry origin/master topic base
- cccc000... commit C
+ bbbb000... commit B
- aaaa000... commit A

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.21. git-citool(1)

NAME

git-citool - Graphical alternative to git-commit

SYNOPSIS

git citool

DESCRIPTION

A Tcl/Tk based graphical interface to review modified files, stage them into the index, enter a commit message and record the new commit onto the current branch. This interface is an alternative to the less interactive git commit program.

git citool is actually a standard alias for git gui citool. See Section G.3.56, “git-gui(1)” for more details.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.22. git-clean(1)

NAME

git-clean - Remove untracked files from the working tree

SYNOPSIS

git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>…

DESCRIPTION

Cleans the working tree by recursively removing files that are not under version control, starting from the current directory.

Normally, only files unknown to Git are removed, but if the -x option is specified, ignored files are also removed. This can, for example, be useful to remove all build products.

If any optional <path>... arguments are given, only those paths are affected.

OPTIONS

-d
Remove untracked directories in addition to untracked files. If an untracked directory is managed by a different Git repository, it is not removed by default. Use -f option twice if you really want to remove such a directory.
-f , --force
If the Git configuration variable clean.requireForce is not set to false, git clean will refuse to delete files or directories unless given -f, -n or -i. Git will refuse to delete directories with .git sub directory or file unless a second -f is given.
-i , --interactive
Show what would be done and clean files interactively. See Interactive mode for details.
-n , --dry-run
Don't actually remove anything, just show what would be done.
-q , --quiet
Be quiet, only report errors, but not the files that are successfully removed.
-e <pattern> , --exclude=<pattern>
In addition to those found in .gitignore (per directory) and $GIT_DIR/info/exclude, also consider these patterns to be in the set of the ignore rules in effect.
-x
Don't use the standard ignore rules read from .gitignore (per directory) and $GIT_DIR/info/exclude, but do still use the ignore rules given with -e options. This allows removing all untracked files, including build products. This can be used (possibly in conjunction with git reset) to create a pristine working directory to test a clean build.
-X
Remove only files ignored by Git. This may be useful to rebuild everything from scratch, but keep manually created files.

Interactive mode

When the command enters the interactive mode, it shows the files and directories to be cleaned, and goes into its interactive command loop.

The command loop shows the list of subcommands available, and gives a prompt "What now> ". In general, when the prompt ends with a single >, you can pick only one of the choices given and type return, like this:

    *** Commands ***
        1: clean                2: filter by pattern    3: select by numbers
        4: ask each             5: quit                 6: help
    What now> 1

You also could say c or clean above as long as the choice is unique.

The main command loop has 6 subcommands.

clean
Start cleaning files and directories, and then quit.
filter by pattern
This shows the files and directories to be deleted and issues an "Input ignore patterns>>" prompt. You can input space-separated patterns to exclude files and directories from deletion. E.g. "*.c *.h" will excludes files end with ".c" and ".h" from deletion. When you are satisfied with the filtered result, press ENTER (empty) back to the main menu.
select by numbers
This shows the files and directories to be deleted and issues an "Select items to delete>>" prompt. When the prompt ends with double >> like this, you can make more than one selection, concatenated with whitespace or comma. Also you can say ranges. E.g. "2-5 7,9" to choose 2,3,4,5,7,9 from the list. If the second number in a range is omitted, all remaining items are selected. E.g. "7-" to choose 7,8,9 from the list. You can say * to choose everything. Also when you are satisfied with the filtered result, press ENTER (empty) back to the main menu.
ask each
This will start to clean, and you must confirm one by one in order to delete items. Please note that this action is not as efficient as the above two actions.
quit
This lets you quit without do cleaning.
help
Show brief usage of interactive git-clean.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.23. git-clone(1)

NAME

git-clone - Clone a repository into a new directory

SYNOPSIS

git clone [--template=<template_directory>]
          [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
          [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
          [--dissociate] [--separate-git-dir <git dir>]
          [--depth <depth>] [--[no-]single-branch]
          [--recursive | --recurse-submodules] [--jobs <n>] [--] <repository>
          [<directory>]

DESCRIPTION

Clones a repository into a newly created directory, creates remote-tracking branches for each branch in the cloned repository (visible using git branch -r), and creates and checks out an initial branch that is forked from the cloned repository's currently active branch.

After the clone, a plain git fetch without arguments will update all the remote-tracking branches, and a git pull without arguments will in addition merge the remote master branch into the current master branch, if any (this is untrue when "--single-branch" is given; see below).

This default configuration is achieved by creating references to the remote branch heads under refs/remotes/origin and by initializing remote.origin.url and remote.origin.fetch configuration variables.

OPTIONS

--local , -l

When the repository to clone from is on a local machine, this flag bypasses the normal "Git aware" transport mechanism and clones the repository by making a copy of HEAD and everything under objects and refs directories. The files under .git/objects/ directory are hardlinked to save space when possible.

If the repository is specified as a local path (e.g., /path/to/repo), this is the default, and --local is essentially a no-op. If the repository is specified as a URL, then this flag is ignored (and we never use the local optimizations). Specifying --no-local will override the default when /path/to/repo is given, using the regular Git transport instead.

--no-hardlinks
Force the cloning process from a repository on a local filesystem to copy the files under the .git/objects directory instead of using hardlinks. This may be desirable if you are trying to make a back-up of your repository.
--shared , -s

When the repository to clone is on the local machine, instead of using hard links, automatically setup .git/objects/info/alternates to share the objects with the source repository. The resulting repository starts out without any object of its own.

NOTE: this is a possibly dangerous operation; do not use it unless you understand what it does. If you clone your repository using this option and then delete branches (or use any other Git command that makes any existing commit unreferenced) in the source repository, some objects may become unreferenced (or dangling). These objects may be removed by normal Git operations (such as git commit) which automatically call git gc --auto. (See Section G.3.53, “git-gc(1)”.) If these objects are removed and were referenced by the cloned repository, then the cloned repository will become corrupt.

Note that running git repack without the -l option in a repository cloned with -s will copy objects from the source repository into a pack in the cloned repository, removing the disk space savings of clone -s. It is safe, however, to run git gc, which uses the -l option by default.

If you want to break the dependency of a repository cloned with -s on its source repository, you can simply run git repack -a to copy all objects from the source repository into a pack in the cloned repository.

--reference <repository>

If the reference repository is on the local machine, automatically setup .git/objects/info/alternates to obtain objects from the reference repository. Using an already existing repository as an alternate will require fewer objects to be copied from the repository being cloned, reducing network and local storage costs.

NOTE: see the NOTE for the --shared option, and also the --dissociate option.

--dissociate
Borrow the objects from reference repositories specified with the --reference options only to reduce network transfer, and stop borrowing from them after a clone is made by making necessary local copies of borrowed objects. This option can also be used when cloning locally from a repository that already borrows objects from another repository--the new repository will borrow objects from the same repository, and this option can be used to stop the borrowing.
--quiet , -q
Operate quietly. Progress is not reported to the standard error stream.
--verbose , -v
Run verbosely. Does not affect the reporting of progress status to the standard error stream.
--progress
Progress status is reported on the standard error stream by default when it is attached to a terminal, unless -q is specified. This flag forces progress status even if the standard error stream is not directed to a terminal.
--no-checkout , -n
No checkout of HEAD is performed after the clone is complete.
--bare
Make a bare Git repository. That is, instead of creating <directory> and placing the administrative files in <directory>/.git, make the <directory> itself the $GIT_DIR. This obviously implies the -n because there is nowhere to check out the working tree. Also the branch heads at the remote are copied directly to corresponding local branch heads, without mapping them to refs/remotes/origin/. When this option is used, neither remote-tracking branches nor the related configuration variables are created.
--mirror
Set up a mirror of the source repository. This implies --bare. Compared to --bare, --mirror not only maps local branches of the source to local branches of the target, it maps all refs (including remote-tracking branches, notes etc.) and sets up a refspec configuration such that all these refs are overwritten by a git remote update in the target repository.
--origin <name> , -o <name>
Instead of using the remote name origin to keep track of the upstream repository, use <name>.
--branch <name> , -b <name>
Instead of pointing the newly created HEAD to the branch pointed to by the cloned repository's HEAD, point to <name> branch instead. In a non-bare repository, this is the branch that will be checked out. --branch can also take tags and detaches the HEAD at that commit in the resulting repository.
--upload-pack <upload-pack> , -u <upload-pack>
When given, and the repository to clone from is accessed via ssh, this specifies a non-default path for the command run on the other end.
--template=<template_directory>
Specify the directory from which templates will be used; (See the "TEMPLATE DIRECTORY" section of Section G.3.65, “git-init(1)”.)
--config <key>=<value> , -c <key>=<value>
Set a configuration variable in the newly-created repository; this takes effect immediately after the repository is initialized, but before the remote history is fetched or any files checked out. The key is in the same format as expected by Section G.3.27, “git-config(1)” (e.g., core.eol=true). If multiple values are given for the same key, each value will be written to the config file. This makes it safe, for example, to add additional fetch refspecs to the origin remote.
--depth <depth>
Create a shallow clone with a history truncated to the specified number of commits. Implies --single-branch unless --no-single-branch is given to fetch the histories near the tips of all branches.
--[no-]single-branch
Clone only the history leading to the tip of a single branch, either specified by the --branch option or the primary branch remote's HEAD points at. Further fetches into the resulting repository will only update the remote-tracking branch for the branch this option was used for the initial cloning. If the HEAD at the remote did not point at any branch when --single-branch clone was made, no remote-tracking branch is created.
--recursive , --recurse-submodules
After the clone is created, initialize all submodules within, using their default settings. This is equivalent to running git submodule update --init --recursive immediately after the clone is finished. This option is ignored if the cloned repository does not have a worktree/checkout (i.e. if any of --no-checkout/-n, --bare, or --mirror is given)
--separate-git-dir=<git dir>
Instead of placing the cloned repository where it is supposed to be, place the cloned repository at the specified directory, then make a filesystem-agnostic Git symbolic link to there. The result is Git repository can be separated from working tree.
-j <n> , --jobs <n>
The number of submodules fetched at the same time. Defaults to the submodule.fetchJobs option.
<repository>
The (possibly remote) repository to clone from. See the URLS section below for more information on specifying repositories.
<directory>
The name of a new directory to clone into. The "humanish" part of the source repository is used if no directory is explicitly given (repo for /path/to/repo.git and foo for host.xz:foo/.git). Cloning into an existing directory is only allowed if the directory is empty.

GIT URLS

In general, URLs contain information about the transport protocol, the address of the remote server, and the path to the repository. Depending on the transport protocol, some of this information may be absent.

Git supports ssh, git, http, and https protocols (in addition, ftp, and ftps can be used for fetching, but this is inefficient and deprecated; do not use it).

The native transport (i.e. git:// URL) does no authentication and should be used with caution on unsecured networks.

The following syntaxes may be used with them:

  • ssh://[[email protected]]host.xz[:port]/path/to/repo.git/
  • git://host.xz[:port]/path/to/repo.git/
  • http[s]://host.xz[:port]/path/to/repo.git/
  • ftp[s]://host.xz[:port]/path/to/repo.git/

An alternative scp-like syntax may also be used with the ssh protocol:

This syntax is only recognized if there are no slashes before the first colon. This helps differentiate a local path that contains a colon. For example the local path foo:bar could be specified as an absolute path or ./foo:bar to avoid being misinterpreted as an ssh url.

The ssh and git protocols additionally support ~username expansion:

For local repositories, also supported by Git natively, the following syntaxes may be used:

  • /path/to/repo.git/
  • file:///path/to/repo.git/

These two syntaxes are mostly equivalent, except the former implies --local option.

When Git doesn't know how to handle a certain transport protocol, it attempts to use the remote-<transport> remote helper, if one exists. To explicitly request a remote helper, the following syntax may be used:

  • <transport>::<address>

where <address> may be a path, a server and path, or an arbitrary URL-like string recognized by the specific remote helper being invoked. See Section G.4.10, “gitremote-helpers(1)” for details.

If there are a large number of similarly-named remote repositories and you want to use a different format for them (such that the URLs you use will be rewritten into URLs that work), you can create a configuration section of the form:

        [url "<actual url base>"]
                insteadOf = <other url base>

For example, with this:

        [url "git://git.host.xz/"]
                insteadOf = host.xz:/path/to/
                insteadOf = work:

a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".

If you want to rewrite URLs for push only, you can create a configuration section of the form:

        [url "<actual url base>"]
                pushInsteadOf = <other url base>

For example, with this:

        [url "ssh://example.org/"]
                pushInsteadOf = git://example.org/

a URL like "git://example.org/path/to/repo.git" will be rewritten to "ssh://example.org/path/to/repo.git" for pushes, but pulls will still use the original URL.

Examples

  • Clone from upstream:

    $ git clone git://git.kernel.org/pub/scm/.../linux.git my-linux
    $ cd my-linux
    $ make
  • Make a local clone that borrows from the current directory, without checking things out:

    $ git clone -l -s -n . ../copy
    $ cd ../copy
    $ git show-branch
  • Clone from upstream while borrowing from an existing local directory:

    $ git clone --reference /git/linux.git \
            git://git.kernel.org/pub/scm/.../linux.git \
            my-linux
    $ cd my-linux
  • Create a bare repository to publish your changes to the public:

    $ git clone --bare -l /home/proj/.git /pub/scm/proj.git

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.24. git-column(1)

NAME

git-column - Display data in columns

SYNOPSIS

git column [--command=<name>] [--[raw-]mode=<mode>] [--width=<width>]
             [--indent=<string>] [--nl=<string>] [--padding=<n>]

DESCRIPTION

This command formats its input into multiple columns.

OPTIONS

--command=<name>
Look up layout mode using configuration variable column.<name> and column.ui.
--mode=<mode>
Specify layout mode. See configuration variable column.ui for option syntax.
--raw-mode=<n>
Same as --mode but take mode encoded as a number. This is mainly used by other commands that have already parsed layout mode.
--width=<width>
Specify the terminal width. By default git column will detect the terminal width, or fall back to 80 if it is unable to do so.
--indent=<string>
String to be printed at the beginning of each line.
--nl=<N>
String to be printed at the end of each line, including newline character.
--padding=<N>
The number of spaces between columns. One space by default.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.25. git-commit-tree(1)

NAME

git-commit-tree - Create a new commit object

SYNOPSIS

git commit-tree <tree> [(-p <parent>)…]
git commit-tree [(-p <parent>)…] [-S[<keyid>]] [(-m <message>)…]
                  [(-F <file>)…] <tree>

DESCRIPTION

This is usually not what an end user wants to run directly. See Section G.3.26, “git-commit(1)” instead.

Creates a new commit object based on the provided tree object and emits the new commit object id on stdout. The log message is read from the standard input, unless -m or -F options are given.

A commit object may have any number of parents. With exactly one parent, it is an ordinary commit. Having more than one parent makes the commit a merge between several lines of history. Initial (root) commits have no parents.

While a tree represents a particular directory state of a working directory, a commit represents that state in "time", and explains how to get there.

Normally a commit would identify a new "HEAD" state, and while Git doesn't care where you save the note about that state, in practice we tend to just write the result to the file that is pointed at by .git/HEAD, so that we can always see what the last committed state was.

OPTIONS

<tree>
An existing tree object
-p <parent>
Each -p indicates the id of a parent commit object.
-m <message>
A paragraph in the commit log message. This can be given more than once and each <message> becomes its own paragraph.
-F <file>
Read the commit log message from the given file. Use - to read from the standard input.
-S[<keyid>] , --gpg-sign[=<keyid>]
GPG-sign commits. The keyid argument is optional and defaults to the committer identity; if specified, it must be stuck to the option without a space.
--no-gpg-sign
Countermand commit.gpgSign configuration variable that is set to force each and every commit to be signed.

Commit Information

A commit encapsulates:

  • all parent object ids
  • author name, email and date
  • committer name and email and the commit time.

While parent object ids are provided on the command line, 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)

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

A commit comment is read from stdin. If a changelog entry is not provided via "<" redirection, git commit-tree will just wait for one to be entered and terminated with ^D.

DATE FORMATS

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

Git internal format
It is <unix timestamp> <time zone offset>, where <unix timestamp> is the number of seconds since the UNIX epoch. <time zone offset> is a positive or negative offset from UTC. For example CET (which is 2 hours ahead UTC) is +0200.
RFC 2822
The standard email format as described by RFC 2822, for example Thu, 07 Apr 2005 22:13:13 +0200.
ISO 8601

Time and date specified by the ISO 8601 standard, for example 2005-04-07T22:13:13. The parser accepts a space instead of the T character as well.

[Note] Note

In addition, the date part is accepted in the following formats: YYYY.MM.DD, MM/DD/YYYY and DD.MM.YYYY.

Discussion

Git is to some extent character encoding agnostic.

  • The contents of the blob objects are uninterpreted sequences of bytes. There is no encoding translation at the core level.
  • Path names are encoded in UTF-8 normalization form C. This applies to tree objects, the index file, ref names, as well as path names in command line arguments, environment variables and config files (.git/config (see Section G.3.27, “git-config(1)”), Section G.4.5, “gitignore(5)”, Section G.4.2, “gitattributes(5)” and Section G.4.8, “gitmodules(5)”).

    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.

  • Commit log messages are typically encoded in UTF-8, but other extended ASCII encodings are also supported. This includes ISO-8859-x, CP125x and many others, but not UTF-16/32, EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, EUC-x, CP9xx etc.).

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.

  1. git commit and git commit-tree issues a warning if the commit log message given to it does not look like a valid UTF-8 string, unless you explicitly say your project uses a legacy encoding. The way to say this is to have i18n.commitencoding in .git/config file, like this:

    [i18n]
            commitencoding = ISO-8859-1

    Commit objects created with the above setting record the value of i18n.commitencoding in its 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.

  2. git log, git show, git blame and friends look at the encoding header of a commit object, and try to re-code the log message into UTF-8 unless otherwise specified. You can specify the desired output encoding with i18n.logoutputencoding in .git/config file, like this:

    [i18n]
            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.

FILES

/etc/mailname

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.26. git-commit(1)

NAME

git-commit - Record changes to the repository

SYNOPSIS

git commit [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend]
           [--dry-run] [(-c | -C | --fixup | --squash) <commit>]
           [-F <file> | -m <msg>] [--reset-author] [--allow-empty]
           [--allow-empty-message] [--no-verify] [-e] [--author=<author>]
           [--date=<date>] [--cleanup=<mode>] [--[no-]status]
           [-i | -o] [-S[<keyid>]] [--] [<file>…]

DESCRIPTION

Stores the current contents of the index in a new commit along with a log message from the user describing the changes.

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

  1. by using git add to incrementally "add" changes to the index before using the commit command (Note: even modified files must be "added");
  2. by using git rm 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 (which must already be known to Git);
  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 or --patch switches with the commit command to decide one by one which files or hunks should be part of the commit, before finalizing the operation. See the Interactive Mode section of Section G.3.2, “git-add(1)” to learn how to operate these modes.

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
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.
-p , --patch
Use the interactive patch selection interface to chose which changes to commit. See Section G.3.2, “git-add(1)” for details.
-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.
--fixup=<commit>
Construct a commit message for use with rebase --autosquash. The commit message will be the subject line from the specified commit with a prefix of "fixup! ". See Section G.3.99, “git-rebase(1)” for details.
--squash=<commit>
Construct a commit message for use with rebase --autosquash. The commit message subject line is taken from the specified commit with a prefix of "squash! ". Can be used with additional commit message options (-m/-c/-C/-F). See Section G.3.99, “git-rebase(1)” for details.
--reset-author
When used with -C/-c/--amend options, or when committing after a a conflicting cherry-pick, declare that the authorship of the resulting commit now belongs to the committer. This also renews the author timestamp.
--short
When doing a dry-run, give the output in the short-format. See Section G.3.129, “git-status(1)” for details. Implies --dry-run.
--branch
Show the branch and tracking info even in short-format.
--porcelain
When doing a dry-run, give the output in a porcelain-ready format. See Section G.3.129, “git-status(1)” for details. Implies --dry-run.
--long
When doing a dry-run, give the output in a the long-format. Implies --dry-run.
-z , --null
When showing short or porcelain status output, terminate entries in the status output with NUL, instead of LF. If no format is given, implies the --porcelain output format.
-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 commit author. Specify an explicit author using the standard A U Thor <[email protected]> format. Otherwise <author> is assumed to be a pattern and is used to search for an existing commit by that author (i.e. rev-list --all -i --author=<author>); the commit author is then copied from the first such commit found.
--date=<date>
Override the author date used in the commit.
-m <msg> , --message=<msg>
Use the given <msg> as the commit message. If multiple -m options are given, their values are concatenated as separate paragraphs.
-t <file> , --template=<file>
When editing the commit message, start the editor with the contents in the given file. The commit.template configuration variable is often used to give this option implicitly to the command. This mechanism can be used by projects that want to guide participants with some hints on what to write in the message in what order. If the user exits the editor without editing the message, the commit is aborted. This has no effect when a message is given by other means, e.g. with the -m or -F options.
-s , --signoff
Add Signed-off-by line by the committer at the end of the commit log message. The meaning of a signoff depends on the project, but it typically certifies that committer has the rights to submit this work under the same license and agrees to a Developer Certificate of Origin (see http://developercertificate.org/ for more information).
-n , --no-verify
This option bypasses the pre-commit and commit-msg hooks. See also Section G.4.6, “githooks(5)”.
--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.
--allow-empty-message
Like --allow-empty this command is primarily for use by foreign SCM interface scripts. It allows you to create a commit with an empty commit message without using plumbing commands like Section G.3.25, “git-commit-tree(1)”.
--cleanup=<mode>

This option determines how the supplied commit message should be cleaned up before committing. The <mode> can be strip, whitespace, verbatim, scissors or default.

strip
Strip leading and trailing empty lines, trailing whitespace, commentary and collapse consecutive empty lines.
whitespace
Same as strip except #commentary is not removed.
verbatim
Do not change the message at all.
scissors
Same as whitespace, except that everything from (and including) the line "# ------------------------ >8 ------------------------" is truncated if the message is to be edited. "#" can be customized with core.commentChar.
default
Same as strip if the message is to be edited. Otherwise whitespace.

The default can be changed by the commit.cleanup configuration variable (see Section G.3.27, “git-config(1)”).

-e , --edit
The message taken from file with -F, command line with -m, and from commit object with -C are usually used as the commit log message unmodified. This option lets you further edit the message taken from these sources.
--no-edit
Use the selected commit message without launching an editor. For example, git commit --amend --no-edit amends a commit without changing its commit message.
--amend

Replace the tip of the current branch by creating a new commit. The recorded tree is prepared as usual (including the effect of the -i and -o options and explicit pathspec), and the message from the original commit is used as the starting point, instead of an empty message, when no other message is specified from the command line via options such as -m, -F, -c, etc. The new commit has the same parents and author as the current one (the --reset-author option can countermand this).

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.

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 Section G.3.99, “git-rebase(1)”.)

--no-post-rewrite
Bypass the post-rewrite hook.
-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 by taking the updated working tree contents of the paths specified on the command line, disregarding any contents that have been staged for other paths. 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 to be specified, which can be used to amend the last commit without committing changes that have already been staged.
-u[<mode>] , --untracked-files[=<mode>]

Show untracked files.

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:

  • no - Show no untracked files
  • normal - Shows untracked files and directories
  • all - Also shows individual files in untracked directories.

    The default can be changed using the status.showUntrackedFiles configuration variable documented in Section G.3.27, “git-config(1)”.

-v , --verbose

Show unified diff between the HEAD commit and what would be committed at the bottom of the commit message template to help the user describe the commit by reminding what changes the commit has. Note that this diff output doesn't have its lines prefixed with #. This diff will not be a part of the commit message.

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
Suppress commit summary message.
--dry-run
Do not create a commit, but show a list of paths that are to be committed, paths with local changes that will be left uncommitted and paths that are untracked.
--status
Include the output of Section G.3.129, “git-status(1)” in the commit message template when using an editor to prepare the commit message. Defaults to on, but can be used to override configuration variable commit.status.
--no-status
Do not include the output of Section G.3.129, “git-status(1)” in the commit message template when using an editor to prepare the default commit message.
-S[<keyid>] , --gpg-sign[=<keyid>]
GPG-sign commits. The keyid argument is optional and defaults to the committer identity; if specified, it must be stuck to the option without a space.
--no-gpg-sign
Countermand commit.gpgSign configuration variable that is set to force each and every commit to be signed.
--
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.

DATE FORMATS

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

Git internal format
It is <unix timestamp> <time zone offset>, where <unix timestamp> is the number of seconds since the UNIX epoch. <time zone offset> is a positive or negative offset from UTC. For example CET (which is 2 hours ahead UTC) is +0200.
RFC 2822
The standard email format as described by RFC 2822, for example Thu, 07 Apr 2005 22:13:13 +0200.
ISO 8601

Time and date specified by the ISO 8601 standard, for example 2005-04-07T22:13:13. The parser accepts a space instead of the T character as well.

[Note] Note

In addition, the date part is accepted in the following formats: YYYY.MM.DD, MM/DD/YYYY and DD.MM.YYYY.

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

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. 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, Section G.3.50, “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.

  • The contents of the blob objects are uninterpreted sequences of bytes. There is no encoding translation at the core level.
  • Path names are encoded in UTF-8 normalization form C. This applies to tree objects, the index file, ref names, as well as path names in command line arguments, environment variables and config files (.git/config (see Section G.3.27, “git-config(1)”), Section G.4.5, “gitignore(5)”, Section G.4.2, “gitattributes(5)” and Section G.4.8, “gitmodules(5)”).

    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.

  • Commit log messages are typically encoded in UTF-8, but other extended ASCII encodings are also supported. This includes ISO-8859-x, CP125x and many others, but not UTF-16/32, EBCDIC and CJK multi-byte encodings (GBK, Shift-JIS, Big5, EUC-x, CP9xx etc.).

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.

  1. git commit and git commit-tree issues a warning if the commit log message given to it does not look like a valid UTF-8 string, unless you explicitly say your project uses a legacy encoding. The way to say this is to have i18n.commitencoding in .git/config file, like this:

    [i18n]
            commitencoding = ISO-8859-1

    Commit objects created with the above setting record the value of i18n.commitencoding in its 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.

  2. git log, git show, git blame and friends look at the encoding header of a commit object, and try to re-code the log message into UTF-8 unless otherwise specified. You can specify the desired output encoding with i18n.logoutputencoding in .git/config file, like this:

    [i18n]
            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 Section G.3.142, “git-var(1)” for details.

HOOKS

This command can run commit-msg, prepare-commit-msg, pre-commit, and post-commit hooks. See Section G.4.6, “githooks(5)” for more information.

FILES

$GIT_DIR/COMMIT_EDITMSG
This file contains the commit message of a commit in progress. If git commit exits due to an error before creating a commit, any commit message that has been provided by the user (e.g., in an editor session) will be available in this file, but will be overwritten by the next invocation of git commit.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.27. git-config(1)

NAME

git-config - Get and set repository or global options

SYNOPSIS

git config [<file-option>] [type] [--show-origin] [-z|--null] name [value [value_regex]]
git config [<file-option>] [type] --add name value
git config [<file-option>] [type] --replace-all name value [value_regex]
git config [<file-option>] [type] [--show-origin] [-z|--null] --get name [value_regex]
git config [<file-option>] [type] [--show-origin] [-z|--null] --get-all name [value_regex]
git config [<file-option>] [type] [--show-origin] [-z|--null] [--name-only] --get-regexp name_regex [value_regex]
git config [<file-option>] [type] [-z|--null] --get-urlmatch name URL
git config [<file-option>] --unset name [value_regex]
git config [<file-option>] --unset-all name [value_regex]
git config [<file-option>] --rename-section old_name new_name
git config [<file-option>] --remove-section name
git config [<file-option>] [--show-origin] [-z|--null] [--name-only] -l | --list
git config [<file-option>] --get-color name [default]
git config [<file-option>] --get-colorbool name [stdout-is-tty]
git config [<file-option>] -e | --edit

DESCRIPTION

You can query/set/replace/unset options with this command. The name is actually the section and the key separated by a dot, and the value will be escaped.

Multiple lines can be added to an option by using the --add option. If you want to update or unset an option which can occur on multiple lines, a POSIX regexp value_regex needs to be given. Only the existing values that match the regexp are updated or unset. If you want to handle the lines that do not match the regex, just prepend a single exclamation mark in front (see also the section called “EXAMPLES”).

The type specifier can be either --int or --bool, to make git config ensure that the variable(s) are of the given type and convert the value to the canonical form (simple decimal number for int, a "true" or "false" string for bool), or --path, which does some path expansion (see --path below). If no type specifier is passed, no checks or transformations are performed on the value.

When reading, the values are read from the system, global and repository local configuration files by default, and options --system, --global, --local and --file <filename> can be used to tell the command to read from only that location (see the section called “FILES”).

When writing, the new value is written to the repository local configuration file by default, and options --system, --global, --file <filename> can be used to tell the command to write to that location (you can say --local but that is the default).

This command will fail with non-zero status upon error. Some exit codes are:

  • The config file is invalid (ret=3),
  • can not write to the config file (ret=4),
  • no section or name was provided (ret=2),
  • the section or key is invalid (ret=1),
  • you try to unset an option which does not exist (ret=5),
  • you try to unset/set an option for which multiple lines match (ret=5), or
  • you try to use an invalid regexp (ret=6).

On success, the command returns the exit code 0.

OPTIONS

--replace-all
Default behavior is to replace at most one line. This replaces all lines matching the key (and optionally the value_regex).
--add
Adds a new line to the option without altering any existing values. This is the same as providing ^$ as the value_regex in --replace-all.
--get
Get the value for a given key (optionally filtered by a regex matching the value). Returns error code 1 if the key was not found and the last value if multiple key values were found.
--get-all
Like get, but returns all values for a multi-valued key.
--get-regexp
Like --get-all, but interprets the name as a regular expression and writes out the key names. Regular expression matching is currently case-sensitive and done against a canonicalized version of the key in which section and variable names are lowercased, but subsection names are not.
--get-urlmatch name URL
When given a two-part name section.key, the value for section.<url>.key whose <url> part matches the best to the given URL is returned (if no such key exists, the value for section.key is used as a fallback). When given just the section as name, do so for all the keys in the section and list them. Returns error code 1 if no value is found.
--global

For writing options: write to global ~/.gitconfig file rather than the repository .git/config, write to $XDG_CONFIG_HOME/git/config file if this file exists and the ~/.gitconfig file doesn't.

For reading options: read only from global ~/.gitconfig and from $XDG_CONFIG_HOME/git/config rather than from all available files.

See also the section called “FILES”.

--system

For writing options: write to system-wide $(prefix)/etc/gitconfig rather than the repository .git/config.

For reading options: read only from system-wide $(prefix)/etc/gitconfig rather than from all available files.

See also the section called “FILES”.

--local

For writing options: write to the repository .git/config file. This is the default behavior.

For reading options: read only from the repository .git/config rather than from all available files.

See also the section called “FILES”.

-f config-file , --file config-file
Use the given config file instead of the one specified by GIT_CONFIG.
--blob blob
Similar to --file but use the given blob instead of a file. E.g. you can use master:.gitmodules to read values from the file .gitmodules in the master branch. See "SPECIFYING REVISIONS" section in Section G.4.12, “gitrevisions(7)” for a more complete list of ways to spell blob names.
--remove-section
Remove the given section from the configuration file.
--rename-section
Rename the given section to a new name.
--unset
Remove the line matching the key from config file.
--unset-all
Remove all lines matching the key from config file.
-l , --list
List all variables set in config file, along with their values.
--bool
git config will ensure that the output is "true" or "false"
--int
git config will ensure that the output is a simple decimal number. An optional value suffix of k, m, or g in the config file will cause the value to be multiplied by 1024, 1048576, or 1073741824 prior to output.
--bool-or-int
git config will ensure that the output matches the format of either --bool or --int, as described above.
--path
git-config will expand leading ~ to the value of $HOME, and ~user to the home directory for the specified user. This option has no effect when setting the value (but you can use git config bla ~/ from the command line to let your shell do the expansion).
-z , --null
For all options that output values and/or keys, always end values with the null character (instead of a newline). Use newline instead as a delimiter between key and value. This allows for secure parsing of the output without getting confused e.g. by values that contain line breaks.
--name-only
Output only the names of config variables for --list or --get-regexp.
--show-origin
Augment the output of all queried config options with the origin type (file, standard input, blob, command line) and the actual origin (config file path, ref, or blob id if applicable).
--get-colorbool name [stdout-is-tty]
Find the color setting for name (e.g. color.diff) and output "true" or "false". stdout-is-tty should be either "true" or "false", and is taken into account when configuration says "auto". If stdout-is-tty is missing, then checks the standard output of the command itself, and exits with status 0 if color is to be used, or exits with status 1 otherwise. When the color setting for name is undefined, the command uses color.ui as fallback.
--get-color name [default]
Find the color configured for name (e.g. color.diff.new) and output it as the ANSI color escape sequence to the standard output. The optional default parameter is used instead, if there is no color configured for name.
-e , --edit
Opens an editor to modify the specified config file; either --system, --global, or repository (default).
--[no-]includes
Respect include.* directives in config files when looking up values. Defaults to off when a specific file is given (e.g., using --file, --global, etc) and on when searching all config files.

FILES

If not set explicitly with --file, there are four files where git config will search for configuration options:

$(prefix)/etc/gitconfig
System-wide configuration file.
$XDG_CONFIG_HOME/git/config
Second user-specific configuration file. If $XDG_CONFIG_HOME is not set or empty, $HOME/.config/git/config will be used. Any single-valued variable set in this file will be overwritten by whatever is in ~/.gitconfig. It is a good idea not to create this file if you sometimes use older versions of Git, as support for this file was added fairly recently.
~/.gitconfig
User-specific configuration file. Also called "global" configuration file.
$GIT_DIR/config
Repository specific configuration file.

If no further options are given, all reading options will read all of these files that are available. If the global or the system-wide configuration file are not available they will be ignored. If the repository configuration file is not available or readable, git config will exit with a non-zero error code. However, in neither case will an error message be issued.

The files are read in the order given above, with last value found taking precedence over values read earlier. When multiple values are taken then all values of a key from all files will be used.

All writing options will per default write to the repository specific configuration file. Note that this also affects options like --replace-all and --unset. git config will only ever change one file at a time.

You can override these rules either by command-line options or by environment variables. The --global and the --system options will limit the file used to the global or system-wide file respectively. The GIT_CONFIG environment variable has a similar effect, but you can specify any filename you want.

ENVIRONMENT

GIT_CONFIG
Take the configuration from the given file instead of .git/config. Using the "--global" option forces this to ~/.gitconfig. Using the "--system" option forces this to $(prefix)/etc/gitconfig.
GIT_CONFIG_NOSYSTEM
Whether to skip reading settings from the system-wide $(prefix)/etc/gitconfig file. See Section G.3.1, “git(1)” for details.

See also the section called “FILES”.

EXAMPLES

Given a .git/config like this:

#
# This is the config file, and
# a '#' or ';' character indicates
# a comment
#
; core variables
[core]
        ; Don't trust file modes
        filemode = false
; Our diff algorithm
[diff]
        external = /usr/local/bin/diff-wrapper
        renames = true
; Proxy settings
[core]
        gitproxy=proxy-command for kernel.org
        gitproxy=default-proxy ; for all the rest
; HTTP
[http]
        sslVerify
[http "https://weak.example.com"]
        sslVerify = false
        cookieFile = /tmp/cookie.txt

you can set the filemode to true with

% git config core.filemode true

The hypothetical proxy command entries actually have a postfix to discern what URL they apply to. Here is how to change the entry for kernel.org to "ssh".

% git config core.gitproxy '"ssh" for kernel.org' 'for kernel.org$'

This makes sure that only the key/value pair for kernel.org is replaced.

To delete the entry for renames, do

% git config --unset diff.renames

If you want to delete an entry for a multivar (like core.gitproxy above), you have to provide a regex matching the value of exactly one line.

To query the value for a given key, do

% git config --get core.filemode

or

% git config core.filemode

or, to query a multivar:

% git config --get core.gitproxy "for kernel.org$"

If you want to know all the values for a multivar, do:

% git config --get-all core.gitproxy

If you like to live dangerously, you can replace all core.gitproxy by a new one with

% git config --replace-all core.gitproxy ssh

However, if you really only want to replace the line for the default proxy, i.e. the one without a "for …" postfix, do something like this:

% git config core.gitproxy ssh '! for '

To actually match only values with an exclamation mark, you have to

% git config section.key value '[!]'

To add a new proxy, without altering any of the existing ones, use

% git config --add core.gitproxy '"proxy-command" for example.com'

An example to use customized color from the configuration in your script:

#!/bin/sh
WS=$(git config --get-color color.diff.whitespace "blue reverse")
RESET=$(git config --get-color "" "reset")
echo "${WS}your whitespace color or blue reverse${RESET}"

For URLs in https://weak.example.com, http.sslVerify is set to false, while it is set to true for all others:

% git config --bool --get-urlmatch http.sslverify https://good.example.com
true
% git config --bool --get-urlmatch http.sslverify https://weak.example.com
false
% git config --get-urlmatch http https://weak.example.com
http.cookieFile /tmp/cookie.txt
http.sslverify false

CONFIGURATION FILE

The Git configuration file contains a number of variables that affect the Git commands' behavior. The .git/config file in each repository is used to store the configuration for that repository, and $HOME/.gitconfig is used to store a per-user configuration as fallback values for the .git/config file. The file /etc/gitconfig can be used to store a system-wide default configuration.

The configuration variables are used by both the Git plumbing and the porcelains. The variables are divided into sections, wherein the fully qualified variable name of the variable itself is the last dot-separated segment and the section name is everything before the last dot. The variable names are case-insensitive, allow only alphanumeric characters and -, and must start with an alphabetic character. Some variables may appear multiple times; we say then that the variable is multivalued.

1. Syntax

The syntax is fairly flexible and permissive; whitespaces are mostly ignored. The # and ; characters begin comments to the end of line, blank lines are ignored.

The file consists of sections and variables. A section begins with the name of the section in square brackets and continues until the next section begins. Section names are case-insensitive. Only alphanumeric characters, - and . are allowed in section names. Each variable must belong to some section, which means that there must be a section header before the first setting of a variable.

Sections can be further divided into subsections. To begin a subsection put its name in double quotes, separated by space from the section name, in the section header, like in the example below:

        [section "subsection"]

Subsection names are case sensitive and can contain any characters except newline (doublequote " and backslash can be included by escaping them as \" and \\, respectively). Section headers cannot span multiple lines. Variables may belong directly to a section or to a given subsection. You can have [section] if you have [section "subsection"], but you don't need to.

There is also a deprecated [section.subsection] syntax. With this syntax, the subsection name is converted to lower-case and is also compared case sensitively. These subsection names follow the same restrictions as section names.

All the other lines (and the remainder of the line after the section header) are recognized as setting variables, in the form name = value (or just name, which is a short-hand to say that the variable is the boolean "true"). The variable names are case-insensitive, allow only alphanumeric characters and -, and must start with an alphabetic character.

A line that defines a value can be continued to the next line by ending it with a \; the backquote and the end-of-line are stripped. Leading whitespaces after name =, the remainder of the line after the first comment character # or ;, and trailing whitespaces of the line are discarded unless they are enclosed in double quotes. Internal whitespaces within the value are retained verbatim.

Inside double quotes, double quote " and backslash \ characters must be escaped: use \" for " and \\ for \.

The following escape sequences (beside \" and \\) are recognized: \n for newline character (NL), \t for horizontal tabulation (HT, TAB) and \b for backspace (BS). Other char escape sequences (including octal escape sequences) are invalid.

2. Includes

You can include one config file from another by setting the special include.path variable to the name of the file to be included. The included file is expanded immediately, as if its contents had been found at the location of the include directive. If the value of the include.path variable is a relative path, the path is considered to be relative to the configuration file in which the include directive was found. The value of include.path is subject to tilde expansion: ~/ is expanded to the value of $HOME, and ~user/ to the specified user's home directory. See below for examples.

3. Example

# Core variables
[core]
        ; Don't trust file modes
        filemode = false
# Our diff algorithm
[diff]
        external = /usr/local/bin/diff-wrapper
        renames = true
[branch "devel"]
        remote = origin
        merge = refs/heads/devel
# Proxy settings
[core]
        gitProxy="ssh" for "kernel.org"
        gitProxy=default-proxy ; for the rest
[include]
        path = /path/to/foo.inc ; include by absolute path
        path = foo ; expand "foo" relative to the current file
        path = ~/foo ; expand "foo" in your $HOME directory

4. Values

Values of many variables are treated as a simple string, but there are variables that take values of specific types and there are rules as to how to spell them.

boolean

When a variable is said to take a boolean value, many synonyms are accepted for true and false; these are all case-insensitive.

true
Boolean true can be spelled as yes, on, true, or 1. Also, a variable defined without = <value> is taken as true.
false

Boolean false can be spelled as no, off, false, or 0.

When converting value to the canonical form using --bool type specifier; git config will ensure that the output is "true" or "false" (spelled in lowercase).

integer
The value for many variables that specify various sizes can be suffixed with k, M,… to mean "scale the number by 1024", "by 1024x1024", etc.
color

The value for a variables that takes a color is a list of colors (at most two) and attributes (at most one), separated by spaces. The colors accepted are normal, black, red, green, yellow, blue, magenta, cyan and white; the attributes are bold, dim, ul, blink and reverse. The first color given is the foreground; the second is the background. The position of the attribute, if any, doesn't matter. Attributes may be turned off specifically by prefixing them with no (e.g., noreverse, noul, etc).

Colors (foreground and background) may also be given as numbers between 0 and 255; these use ANSI 256-color mode (but note that not all terminals may support this). If your terminal supports it, you may also specify 24-bit RGB values as hex, like #ff0ab3.

The attributes are meant to be reset at the beginning of each item in the colored output, so setting color.decorate.branch to black will paint that branch name in a plain black, even if the previous thing on the same output line (e.g. opening parenthesis before the list of branch names in log --decorate output) is set to be painted with bold or some other attribute.

5. Variables

Note that this list is non-comprehensive and not necessarily complete. For command-specific variables, you will find a more detailed description in the appropriate manual page.

Other git-related tools may and do use their own variables. When inventing new variables for use in your own tool, make sure their names do not conflict with those that are used by Git itself and other popular tools, and describe them in your documentation.

advice.*

These variables control various optional help messages designed to aid new users. All advice.* variables default to true, and you can tell Git that you do not need help by setting these to false:

pushUpdateRejected
Set this variable to false if you want to disable pushNonFFCurrent, pushNonFFMatching, pushAlreadyExists, pushFetchFirst, and pushNeedsForce simultaneously.
pushNonFFCurrent
Advice shown when Section G.3.96, “git-push(1)” fails due to a non-fast-forward update to the current branch.
pushNonFFMatching
Advice shown when you ran Section G.3.96, “git-push(1)” and pushed matching refs explicitly (i.e. you used :, or specified a refspec that isn't your current branch) and it resulted in a non-fast-forward error.
pushAlreadyExists
Shown when Section G.3.96, “git-push(1)” rejects an update that does not qualify for fast-forwarding (e.g., a tag.)
pushFetchFirst
Shown when Section G.3.96, “git-push(1)” rejects an update that tries to overwrite a remote ref that points at an object we do not have.
pushNeedsForce
Shown when Section G.3.96, “git-push(1)” rejects an update that tries to overwrite a remote ref that points at an object that is not a commit-ish, or make the remote ref point at an object that is not a commit-ish.
statusHints
Show directions on how to proceed from the current state in the output of Section G.3.129, “git-status(1)”, in the template shown when writing commit messages in Section G.3.26, “git-commit(1)”, and in the help message shown by Section G.3.18, “git-checkout(1)” when switching branch.
statusUoption
Advise to consider using the -u option to Section G.3.129, “git-status(1)” when the command takes more than 2 seconds to enumerate untracked files.
commitBeforeMerge
Advice shown when Section G.3.79, “git-merge(1)” refuses to merge to avoid overwriting local changes.
resolveConflict
Advice shown by various commands when conflicts prevent the operation from being performed.
implicitIdentity
Advice on how to set your identity configuration when your information is guessed from the system username and domain name.
detachedHead
Advice shown when you used Section G.3.18, “git-checkout(1)” to move to the detach HEAD state, to instruct how to create a local branch after the fact.
amWorkDir
Advice that shows the location of the patch file when Section G.3.3, “git-am(1)” fails to apply it.
rmHints
In case of failure in the output of Section G.3.115, “git-rm(1)”, show directions on how to proceed from the current state.
core.fileMode

Tells Git if the executable bit of files in the working tree is to be honored.

Some filesystems lose the executable bit when a file that is marked as executable is checked out, or checks out an non-executable file with executable bit on. Section G.3.23, “git-clone(1)” or Section G.3.65, “git-init(1)” probe the filesystem to see if it handles the executable bit correctly and this variable is automatically set as necessary.

A repository, however, may be on a filesystem that handles the filemode correctly, and this variable is set to true when created, but later may be made accessible from another environment that loses the filemode (e.g. exporting ext4 via CIFS mount, visiting a Cygwin created repository with Git for Windows or Eclipse). In such a case it may be necessary to set this variable to false. See Section G.3.137, “git-update-index(1)”.

The default is true (when core.filemode is not specified in the config file).

core.ignoreCase

If true, this option enables various workarounds to enable Git to work better on filesystems that are not case sensitive, like FAT. For example, if a directory listing finds "makefile" when Git expects "Makefile", Git will assume it is really the same file, and continue to remember it as "Makefile".

The default is false, except Section G.3.23, “git-clone(1)” or Section G.3.65, “git-init(1)” will probe and set core.ignoreCase true if appropriate when the repository is created.

core.precomposeUnicode
This option is only used by Mac OS implementation of Git. When core.precomposeUnicode=true, Git reverts the unicode decomposition of filenames done by Mac OS. This is useful when sharing a repository between Mac OS and Linux or Windows. (Git for Windows 1.7.10 or higher is needed, or Git under cygwin 1.7). When false, file names are handled fully transparent by Git, which is backward compatible with older versions of Git.
core.protectHFS
If set to true, do not allow checkout of paths that would be considered equivalent to .git on an HFS+ filesystem. Defaults to true on Mac OS, and false elsewhere.
core.protectNTFS
If set to true, do not allow checkout of paths that would cause problems with the NTFS filesystem, e.g. conflict with 8.3 "short" names. Defaults to true on Windows, and false elsewhere.
core.trustctime
If false, the ctime differences between the index and the working tree are ignored; useful when the inode change time is regularly modified by something outside Git (file system crawlers and some backup systems). See Section G.3.137, “git-update-index(1)”. True by default.
core.untrackedCache
Determines what to do about the untracked cache feature of the index. It will be kept, if this variable is unset or set to keep. It will automatically be added if set to true. And it will automatically be removed, if set to false. Before setting it to true, you should check that mtime is working properly on your system. See Section G.3.137, “git-update-index(1)”. keep by default.
core.checkStat
Determines which stat fields to match between the index and work tree. The user can set this to default or minimal. Default (or explicitly default), is to check all fields, including the sub-second part of mtime and ctime.
core.quotePath
The commands that output paths (e.g. ls-files, diff), when not given the -z option, will quote "unusual" characters in the pathname by enclosing the pathname in a double-quote pair and with backslashes the same way strings in C source code are quoted. If this variable is set to false, the bytes higher than 0x80 are not quoted but output as verbatim. Note that double quote, backslash and control characters are always quoted without -z regardless of the setting of this variable.
core.eol
Sets the line ending type to use in the working directory for files that have the text property set. Alternatives are lf, crlf and native, which uses the platform's native line ending. The default value is native. See Section G.4.2, “gitattributes(5)” for more information on end-of-line conversion.
core.safecrlf

If true, makes Git check if converting CRLF is reversible when end-of-line conversion is active. Git will verify if a command modifies a file in the work tree either directly or indirectly. For example, committing a file followed by checking out the same file should yield the original file in the work tree. If this is not the case for the current setting of core.autocrlf, Git will reject the file. The variable can be set to "warn", in which case Git will only warn about an irreversible conversion but continue the operation.

CRLF conversion bears a slight chance of corrupting data. When it is enabled, Git will convert CRLF to LF during commit and LF to CRLF during checkout. A file that contains a mixture of LF and CRLF before the commit cannot be recreated by Git. For text files this is the right thing to do: it corrects line endings such that we have only LF line endings in the repository. But for binary files that are accidentally classified as text the conversion can corrupt data.

If you recognize such corruption early you can easily fix it by setting the conversion type explicitly in .gitattributes. Right after committing you still have the original file in your work tree and this file is not yet corrupted. You can explicitly tell Git that this file is binary and Git will handle the file appropriately.

Unfortunately, the desired effect of cleaning up text files with mixed line endings and the undesired effect of corrupting binary files cannot be distinguished. In both cases CRLFs are removed in an irreversible way. For text files this is the right thing to do because CRLFs are line endings, while for binary files converting CRLFs corrupts data.

Note, this safety check does not mean that a checkout will generate a file identical to the original file for a different setting of core.eol and core.autocrlf, but only for the current one. For example, a text file with LF would be accepted with core.eol=lf and could later be checked out with core.eol=crlf, in which case the resulting file would contain CRLF, although the original file contained LF. However, in both work trees the line endings would be consistent, that is either all LF or all CRLF, but never mixed. A file with mixed line endings would be reported by the core.safecrlf mechanism.

core.autocrlf
Setting this variable to "true" is almost the same as setting the text attribute to "auto" on all files except that text files are not guaranteed to be normalized: files that contain CRLF in the repository will not be touched. Use this setting if you want to have CRLF line endings in your working directory even though the repository does not have normalized line endings. This variable can be set to input, in which case no output conversion is performed.
core.symlinks

If false, symbolic links are checked out as small plain files that contain the link text. Section G.3.137, “git-update-index(1)” and Section G.3.2, “git-add(1)” will not change the recorded type to regular file. Useful on filesystems like FAT that do not support symbolic links.

The default is true, except Section G.3.23, “git-clone(1)” or Section G.3.65, “git-init(1)” will probe and set core.symlinks false if appropriate when the repository is created.

core.gitProxy

A "proxy command" to execute (as command host port) instead of establishing direct connection to the remote server when using the Git protocol for fetching. If the variable value is in the "COMMAND for DOMAIN" format, the command is applied only on hostnames ending with the specified domain string. This variable may be set multiple times and is matched in the given order; the first match wins.

Can be overridden by the GIT_PROXY_COMMAND environment variable (which always applies universally, without the special "for" handling).

The special string none can be used as the proxy command to specify that no proxy be used for a given domain pattern. This is useful for excluding servers inside a firewall from proxy use, while defaulting to a common proxy for external domains.

core.ignoreStat

If true, Git will avoid using lstat() calls to detect if files have changed by setting the "assume-unchanged" bit for those tracked files which it has updated identically in both the index and working tree.

When files are modified outside of Git, the user will need to stage the modified files explicitly (e.g. see Examples section in Section G.3.137, “git-update-index(1)”). Git will not normally detect changes to those files.

This is useful on systems where lstat() calls are very slow, such as CIFS/Microsoft Windows.

False by default.

core.preferSymlinkRefs
Instead of the default "symref" format for HEAD and other symbolic reference files, use symbolic links. This is sometimes needed to work with old scripts that expect HEAD to be a symbolic link.
core.bare

If true this repository is assumed to be bare and has no working directory associated with it. If this is the case a number of commands that require a working directory will be disabled, such as Section G.3.2, “git-add(1)” or Section G.3.79, “git-merge(1)”.

This setting is automatically guessed by Section G.3.23, “git-clone(1)” or Section G.3.65, “git-init(1)” when the repository was created. By default a repository that ends in "/.git" is assumed to be not bare (bare = false), while all other repositories are assumed to be bare (bare = true).

core.worktree

Set the path to the root of the working tree. If GIT_COMMON_DIR environment variable is set, core.worktree is ignored and not used for determining the root of working tree. This can be overridden by the GIT_WORK_TREE environment variable and the --work-tree command-line option. The value can be an absolute path or relative to the path to the .git directory, which is either specified by --git-dir or GIT_DIR, or automatically discovered. If --git-dir or GIT_DIR is specified but none of --work-tree, GIT_WORK_TREE and core.worktree is specified, the current working directory is regarded as the top level of your working tree.

Note that this variable is honored even when set in a configuration file in a ".git" subdirectory of a directory and its value differs from the latter directory (e.g. "/path/to/.git/config" has core.worktree set to "/different/path"), which is most likely a misconfiguration. Running Git commands in the "/path/to" directory will still use "/different/path" as the root of the work tree and can cause confusion unless you know what you are doing (e.g. you are creating a read-only snapshot of the same index to a location different from the repository's usual working tree).

core.logAllRefUpdates

Enable the reflog. Updates to a ref <ref> is logged to the file "$GIT_DIR/logs/<ref>", by appending the new and old SHA-1, the date/time and the reason of the update, but only when the file exists. If this configuration variable is set to true, missing "$GIT_DIR/logs/<ref>" file is automatically created for branch heads (i.e. under refs/heads/), remote refs (i.e. under refs/remotes/), note refs (i.e. under refs/notes/), and the symbolic ref HEAD.

This information can be used to determine what commit was the tip of a branch "2 days ago".

This value is true by default in a repository that has a working directory associated with it, and false by default in a bare repository.

core.repositoryFormatVersion
Internal variable identifying the repository format and layout version.
core.sharedRepository
When group (or true), the repository is made shareable between several users in a group (making sure all the files and objects are group-writable). When all (or world or everybody), the repository will be readable by all users, additionally to being group-shareable. When umask (or false), Git will use permissions reported by umask(2). When 0xxx, where 0xxx is an octal number, files in the repository will have this mode value. 0xxx will override user's umask value (whereas the other options will only override requested parts of the user's umask value). Examples: 0660 will make the repo read/write-able for the owner and group, but inaccessible to others (equivalent to group unless umask is e.g. 0022). 0640 is a repository that is group-readable but not group-writable. See Section G.3.65, “git-init(1)”. False by default.
core.warnAmbiguousRefs
If true, Git will warn you if the ref name you passed it is ambiguous and might match multiple refs in the repository. True by default.
core.compression
An integer -1..9, indicating a default compression level. -1 is the zlib default. 0 means no compression, and 1..9 are various speed/size tradeoffs, 9 being slowest. If set, this provides a default to other compression variables, such as core.looseCompression and pack.compression.
core.looseCompression
An integer -1..9, indicating the compression level for objects that are not in a pack file. -1 is the zlib default. 0 means no compression, and 1..9 are various speed/size tradeoffs, 9 being slowest. If not set, defaults to core.compression. If that is not set, defaults to 1 (best speed).
core.packedGitWindowSize

Number of bytes of a pack file to map into memory in a single mapping operation. Larger window sizes may allow your system to process a smaller number of large pack files more quickly. Smaller window sizes will negatively affect performance due to increased calls to the operating system's memory manager, but may improve performance when accessing a large number of large pack files.

Default is 1 MiB if NO_MMAP was set at compile time, otherwise 32 MiB on 32 bit platforms and 1 GiB on 64 bit platforms. This should be reasonable for all users/operating systems. You probably do not need to adjust this value.

Common unit suffixes of k, m, or g are supported.

core.packedGitLimit

Maximum number of bytes to map simultaneously into memory from pack files. If Git needs to access more than this many bytes at once to complete an operation it will unmap existing regions to reclaim virtual address space within the process.

Default is 256 MiB on 32 bit platforms and 8 GiB on 64 bit platforms. This should be reasonable for all users/operating systems, except on the largest projects. You probably do not need to adjust this value.

Common unit suffixes of k, m, or g are supported.

core.deltaBaseCacheLimit

Maximum number of bytes to reserve for caching base objects that may be referenced by multiple deltified objects. By storing the entire decompressed base objects in a cache Git is able to avoid unpacking and decompressing frequently used base objects multiple times.

Default is 96 MiB on all platforms. This should be reasonable for all users/operating systems, except on the largest projects. You probably do not need to adjust this value.

Common unit suffixes of k, m, or g are supported.

core.bigFileThreshold

Files larger than this size are stored deflated, without attempting delta compression. Storing large files without delta compression avoids excessive memory usage, at the slight expense of increased disk usage. Additionally files larger than this size are always treated as binary.

Default is 512 MiB on all platforms. This should be reasonable for most projects as source code and other text files can still be delta compressed, but larger binary media files won't be.

Common unit suffixes of k, m, or g are supported.

core.excludesFile
In addition to .gitignore (per-directory) and .git/info/exclude, Git looks into this file for patterns of files which are not meant to be tracked. "~/" is expanded to the value of $HOME and "~user/" to the specified user's home directory. Its default value is $XDG_CONFIG_HOME/git/ignore. If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/ignore is used instead. See Section G.4.5, “gitignore(5)”.
core.askPass
Some commands (e.g. svn and http interfaces) that interactively ask for a password can be told to use an external program given via the value of this variable. Can be overridden by the GIT_ASKPASS environment variable. If not set, fall back to the value of the SSH_ASKPASS environment variable or, failing that, a simple password prompt. The external program shall be given a suitable prompt as command-line argument and write the password on its STDOUT.
core.attributesFile
In addition to .gitattributes (per-directory) and .git/info/attributes, Git looks into this file for attributes (see Section G.4.2, “gitattributes(5)”). Path expansions are made the same way as for core.excludesFile. Its default value is $XDG_CONFIG_HOME/git/attributes. If $XDG_CONFIG_HOME is either not set or empty, $HOME/.config/git/attributes is used instead.
core.editor
Commands such as commit and tag that lets you edit messages by launching an editor uses the value of this variable when it is set, and the environment variable GIT_EDITOR is not set. See Section G.3.142, “git-var(1)”.
core.commentChar

Commands such as commit and tag that lets you edit messages consider a line that begins with this character commented, and removes them after the editor returns (default #).

If set to "auto", git-commit would select a character that is not the beginning character of any line in existing commit messages.

core.packedRefsTimeout
The length of time, in milliseconds, to retry when trying to lock the packed-refs file. Value 0 means not to retry at all; -1 means to try indefinitely. Default is 1000 (i.e., retry for 1 second).
sequence.editor
Text editor used by git rebase -i for editing the rebase instruction file. The value is meant to be interpreted by the shell when it is used. It can be overridden by the GIT_SEQUENCE_EDITOR environment variable. When not configured the default commit message editor is used instead.
core.pager

Text viewer for use by Git commands (e.g., less). The value is meant to be interpreted by the shell. The order of preference is the $GIT_PAGER environment variable, then core.pager configuration, then $PAGER, and then the default chosen at compile time (usually less).

When the LESS environment variable is unset, Git sets it to FRX (if LESS environment variable is set, Git does not change it at all). If you want to selectively override Git's default setting for LESS, you can set core.pager to e.g. less -S. This will be passed to the shell by Git, which will translate the final command to LESS=FRX less -S. The environment does not set the S option but the command line does, instructing less to truncate long lines. Similarly, setting core.pager to less -+F will deactivate the F option specified by the environment from the command-line, deactivating the "quit if one screen" behavior of less. One can specifically activate some flags for particular commands: for example, setting pager.blame to less -S enables line truncation only for git blame.

Likewise, when the LV environment variable is unset, Git sets it to -c. You can override this setting by exporting LV with another value or setting core.pager to lv +c.

core.whitespace

A comma separated list of common whitespace problems to notice. git diff will use color.diff.whitespace to highlight them, and git apply --whitespace=error will consider them as errors. You can prefix - to disable any of them (e.g. -trailing-space):

  • blank-at-eol treats trailing whitespaces at the end of the line as an error (enabled by default).
  • space-before-tab treats a space character that appears immediately before a tab character in the initial indent part of the line as an error (enabled by default).
  • indent-with-non-tab treats a line that is indented with space characters instead of the equivalent tabs as an error (not enabled by default).
  • tab-in-indent treats a tab character in the initial indent part of the line as an error (not enabled by default).
  • blank-at-eof treats blank lines added at the end of file as an error (enabled by default).
  • trailing-space is a short-hand to cover both blank-at-eol and blank-at-eof.
  • cr-at-eol treats a carriage-return at the end of line as part of the line terminator, i.e. with it, trailing-space does not trigger if the character before such a carriage-return is not a whitespace (not enabled by default).
  • tabwidth=<n> tells how many character positions a tab occupies; this is relevant for indent-with-non-tab and when Git fixes tab-in-indent errors. The default tab width is 8. Allowed values are 1 to 63.
core.fsyncObjectFiles

This boolean will enable fsync() when writing object files.

This is a total waste of time and effort on a filesystem that orders data writes properly, but can be useful for filesystems that do not use journalling (traditional UNIX filesystems) or that only journal metadata and not file contents (OS X's HFS+, or Linux ext3 with "data=writeback").

core.preloadIndex

Enable parallel index preload for operations like git diff

This can speed up operations like git diff and git status especially on filesystems like NFS that have weak caching semantics and thus relatively high IO latencies. When enabled, Git will do the index comparison to the filesystem data in parallel, allowing overlapping IO's. Defaults to true.

core.createObject

You can set this to link, in which case a hardlink followed by a delete of the source are used to make sure that object creation will not overwrite existing objects.

On some file system/operating system combinations, this is unreliable. Set this config setting to rename there; However, This will remove the check that makes sure that existing object files will not get overwritten.

core.notesRef

When showing commit messages, also show notes which are stored in the given ref. The ref must be fully qualified. If the given ref does not exist, it is not an error but means that no notes should be printed.

This setting defaults to "refs/notes/commits", and it can be overridden by the GIT_NOTES_REF environment variable. See Section G.3.86, “git-notes(1)”.

core.sparseCheckout
Enable "sparse checkout" feature. See section "Sparse checkout" in Section G.3.98, “git-read-tree(1)” for more information.
core.abbrev
Set the length object names are abbreviated to. If unspecified, many commands abbreviate to 7 hexdigits, which may not be enough for abbreviated object names to stay unique for sufficiently long time.
add.ignoreErrors , add.ignore-errors (deprecated)
Tells git add to continue adding files when some files cannot be added due to indexing errors. Equivalent to the --ignore-errors option of Section G.3.2, “git-add(1)”. add.ignore-errors is deprecated, as it does not follow the usual naming convention for configuration variables.
alias.*

Command aliases for the Section G.3.1, “git(1)” command wrapper - e.g. after defining "alias.last = cat-file commit HEAD", the invocation "git last" is equivalent to "git cat-file commit HEAD". To avoid confusion and troubles with script usage, aliases that hide existing Git commands are ignored. Arguments are split by spaces, the usual shell quoting and escaping is supported. A quote pair or a backslash can be used to quote them.

If the alias expansion is prefixed with an exclamation point, it will be treated as a shell command. For example, defining "alias.new = !gitk --all --not ORIG_HEAD", the invocation "git new" is equivalent to running the shell command "gitk --all --not ORIG_HEAD". Note that shell commands will be executed from the top-level directory of a repository, which may not necessarily be the current directory. GIT_PREFIX is set as returned by running git rev-parse --show-prefix from the original current directory. See Section G.3.113, “git-rev-parse(1)”.

am.keepcr
If true, git-am will call git-mailsplit for patches in mbox format with parameter --keep-cr. In this case git-mailsplit will not remove \r from lines ending with \r\n. Can be overridden by giving --no-keep-cr from the command line. See Section G.3.3, “git-am(1)”, Section G.3.73, “git-mailsplit(1)”.
am.threeWay
By default, git am will fail if the patch does not apply cleanly. When set to true, this setting tells git am to fall back on 3-way merge if the patch records the identity of blobs it is supposed to apply to and we have those blobs available locally (equivalent to giving the --3way option from the command line). Defaults to false. See Section G.3.3, “git-am(1)”.
apply.ignoreWhitespace
When set to change, tells git apply to ignore changes in whitespace, in the same way as the --ignore-space-change option. When set to one of: no, none, never, false tells git apply to respect all whitespace differences. See Section G.3.5, “git-apply(1)”.
apply.whitespace
Tells git apply how to handle whitespaces, in the same way as the --whitespace option. See Section G.3.5, “git-apply(1)”.
branch.autoSetupMerge
Tells git branch and git checkout to set up new branches so that Section G.3.95, “git-pull(1)” will appropriately merge from the starting point branch. Note that even if this option is not set, this behavior can be chosen per-branch using the --track and --no-track options. The valid settings are: false -- no automatic setup is done; true -- automatic setup is done when the starting point is a remote-tracking branch; always -- automatic setup is done when the starting point is either a local branch or remote-tracking branch. This option defaults to true.
branch.autoSetupRebase
When a new branch is created with git branch or git checkout that tracks another branch, this variable tells Git to set up pull to rebase instead of merge (see "branch.<name>.rebase"). When never, rebase is never automatically set to true. When local, rebase is set to true for tracked branches of other local branches. When remote, rebase is set to true for tracked branches of remote-tracking branches. When always, rebase will be set to true for all tracking branches. See "branch.autoSetupMerge" for details on how to set up a branch to track another branch. This option defaults to never.
branch.<name>.remote
When on branch <name>, it tells git fetch and git push which remote to fetch from/push to. The remote to push to may be overridden with remote.pushDefault (for all branches). The remote to push to, for the current branch, may be further overridden by branch.<name>.pushRemote. If no remote is configured, or if you are not on any branch, it defaults to origin for fetching and remote.pushDefault for pushing. Additionally, . (a period) is the current local repository (a dot-repository), see branch.<name>.merge's final note below.
branch.<name>.pushRemote
When on branch <name>, it overrides branch.<name>.remote for pushing. It also overrides remote.pushDefault for pushing from branch <name>. When you pull from one place (e.g. your upstream) and push to another place (e.g. your own publishing repository), you would want to set remote.pushDefault to specify the remote to push to for all branches, and use this option to override it for a specific branch.
branch.<name>.merge
Defines, together with branch.<name>.remote, the upstream branch for the given branch. It tells git fetch/git pull/git rebase which branch to merge and can also affect git push (see push.default). When in branch <name>, it tells git fetch the default refspec to be marked for merging in FETCH_HEAD. The value is handled like the remote part of a refspec, and must match a ref which is fetched from the remote given by "branch.<name>.remote". The merge information is used by git pull (which at first calls git fetch) to lookup the default branch for merging. Without this option, git pull defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. If you wish to setup git pull so that it merges into <name> from another branch in the local repository, you can point branch.<name>.merge to the desired branch, and use the relative path setting . (a period) for branch.<name>.remote.
branch.<name>.mergeOptions
Sets default options for merging into branch <name>. The syntax and supported options are the same as those of Section G.3.79, “git-merge(1)”, but option values containing whitespace characters are currently not supported.
branch.<name>.rebase

When true, rebase the branch <name> on top of the fetched branch, instead of merging the default branch from the default remote when "git pull" is run. See "pull.rebase" for doing this in a non branch-specific manner.

When preserve, also pass --preserve-merges along to git rebase so that locally committed merge commits will not be flattened by running git pull.

When the value is interactive, the rebase is run in interactive mode.

NOTE: this is a possibly dangerous operation; do not use it unless you understand the implications (see Section G.3.99, “git-rebase(1)” for details).

branch.<name>.description
Branch description, can be edited with git branch --edit-description. Branch description is automatically added in the format-patch cover letter or request-pull summary.
browser.<tool>.cmd
Specify the command to invoke the specified browser. The specified command is evaluated in shell with the URLs passed as arguments. (See Section G.3.146, “git-web--browse(1)”.)
browser.<tool>.path
Override the path for the given tool that may be used to browse HTML help (see -w option in Section G.3.58, “git-help(1)”) or a working repository in gitweb (see Section G.3.66, “git-instaweb(1)”).
clean.requireForce
A boolean to make git-clean do nothing unless given -f, -i or -n. Defaults to true.
color.branch
A boolean to enable/disable color in the output of Section G.3.10, “git-branch(1)”. May be set to always, false (or never) or auto (or true), in which case colors are used only when the output is to a terminal. Defaults to false.
color.branch.<slot>
Use customized color for branch coloration. <slot> is one of current (the current branch), local (a local branch), remote (a remote-tracking branch in refs/remotes/), upstream (upstream tracking branch), plain (other refs).
color.diff

Whether to use ANSI escape sequences to add color to patches. If this is set to always, Section G.3.41, “git-diff(1)”, Section G.3.68, “git-log(1)”, and Section G.3.126, “git-show(1)” will use color for all patches. If it is set to true or auto, those commands will only use color when output is to the terminal. Defaults to false.

This does not affect Section G.3.50, “git-format-patch(1)” or the git-diff-* plumbing commands. Can be overridden on the command line with the --color[=<when>] option.

color.diff.<slot>
Use customized color for diff colorization. <slot> specifies which part of the patch to use the specified color, and is one of context (context text - plain is a historical synonym), meta (metainformation), frag (hunk header), func (function in hunk header), old (removed lines), new (added lines), commit (commit headers), or whitespace (highlighting whitespace errors).
color.decorate.<slot>
Use customized color for git log --decorate output. <slot> is one of branch, remoteBranch, tag, stash or HEAD for local branches, remote-tracking branches, tags, stash and HEAD, respectively.
color.grep
When set to always, always highlight matches. When false (or never), never. When set to true or auto, use color only when the output is written to the terminal. Defaults to false.
color.grep.<slot>

Use customized color for grep colorization. <slot> specifies which part of the line to use the specified color, and is one of

context
non-matching text in context lines (when using -A, -B, or -C)
filename
filename prefix (when not using -h)
function
function name lines (when using -p)
linenumber
line number prefix (when using -n)
match
matching text (same as setting matchContext and matchSelected)
matchContext
matching text in context lines
matchSelected
matching text in selected lines
selected
non-matching text in selected lines
separator
separators between fields on a line (:, -, and =) and between hunks (--)
color.interactive
When set to always, always use colors for interactive prompts and displays (such as those used by "git-add --interactive" and "git-clean --interactive"). When false (or never), never. When set to true or auto, use colors only when the output is to the terminal. Defaults to false.
color.interactive.<slot>
Use customized color for git add --interactive and git clean --interactive output. <slot> may be prompt, header, help or error, for four distinct types of normal output from interactive commands.
color.pager
A boolean to enable/disable colored output when the pager is in use (default is true).
color.showBranch
A boolean to enable/disable color in the output of Section G.3.123, “git-show-branch(1)”. May be set to always, false (or never) or auto (or true), in which case colors are used only when the output is to a terminal. Defaults to false.
color.status
A boolean to enable/disable color in the output of Section G.3.129, “git-status(1)”. May be set to always, false (or never) or auto (or true), in which case colors are used only when the output is to a terminal. Defaults to false.
color.status.<slot>
Use customized color for status colorization. <slot> is one of header (the header text of the status message), added or updated (files which are added but not committed), changed (files which are changed but not added in the index), untracked (files which are not tracked by Git), branch (the current branch), nobranch (the color the no branch warning is shown in, defaulting to red), or unmerged (files which have unmerged changes).
color.ui
This variable determines the default value for variables such as color.diff and color.grep that control the use of color per command family. Its scope will expand as more commands learn configuration to set a default for the --color option. Set it to false or never if you prefer Git commands not to use color unless enabled explicitly with some other configuration or the --color option. Set it to always if you want all output not intended for machine consumption to use color, to true or auto (this is the default since Git 1.8.4) if you want such output to use color when written to the terminal.
column.ui

Specify whether supported commands should output in columns. This variable consists of a list of tokens separated by spaces or commas:

These options control when the feature should be enabled (defaults to never):

always
always show in columns
never
never show in columns
auto
show in columns if the output is to the terminal

These options control layout (defaults to column). Setting any of these implies always if none of always, never, or auto are specified.

column
fill columns before rows
row
fill rows before columns
plain
show in one column

Finally, these options can be combined with a layout option (defaults to nodense):

dense
make unequal size columns to utilize more space
nodense
make equal size columns
column.branch
Specify whether to output branch listing in git branch in columns. See column.ui for details.
column.clean
Specify the layout when list items in git clean -i, which always shows files and directories in columns. See column.ui for details.
column.status
Specify whether to output untracked files in git status in columns. See column.ui for details.
column.tag
Specify whether to output tag listing in git tag in columns. See column.ui for details.
commit.cleanup
This setting overrides the default of the --cleanup option in git commit. See Section G.3.26, “git-commit(1)” for details. Changing the default can be useful when you always want to keep lines that begin with comment character # in your log message, in which case you would do git config commit.cleanup whitespace (note that you will have to remove the help lines that begin with # in the commit log template yourself, if you do this).
commit.gpgSign
A boolean to specify whether all commits should be GPG signed. Use of this option when doing operations such as rebase can result in a large number of commits being signed. It may be convenient to use an agent to avoid typing your GPG passphrase several times.
commit.status
A boolean to enable/disable inclusion of status information in the commit message template when using an editor to prepare the commit message. Defaults to true.
commit.template
Specify a file to use as the template for new commit messages. "~/" is expanded to the value of $HOME and "~user/" to the specified user's home directory.
credential.helper
Specify an external helper to be called when a username or password credential is needed; the helper may consult external storage to avoid prompting the user for the credentials. Note that multiple helpers may be defined. See Section G.4.3, “gitcredentials(7)” for details.
credential.useHttpPath
When acquiring credentials, consider the "path" component of an http or https URL to be important. Defaults to false. See Section G.4.3, “gitcredentials(7)” for more information.
credential.username
If no username is set for a network authentication, use this username by default. See credential.<context>.* below, and Section G.4.3, “gitcredentials(7)”.
credential.<url>.*
Any of the credential.* options above can be applied selectively to some credentials. For example "credential.https://example.com.username" would set the default username only for https connections to example.com. See Section G.4.3, “gitcredentials(7)” for details on how URLs are matched.
credentialCache.ignoreSIGHUP
Tell git-credential-cache--daemon to ignore SIGHUP, instead of quitting.
diff.autoRefreshIndex
When using git diff to compare with work tree files, do not consider stat-only change as changed. Instead, silently run git update-index --refresh to update the cached stat information for paths whose contents in the work tree match the contents in the index. This option defaults to true. Note that this affects only git diff Porcelain, and not lower level diff commands such as git diff-files.
diff.dirstat

A comma separated list of --dirstat parameters specifying the default behavior of the --dirstat option to Section G.3.41, “git-diff(1)”` and friends. The defaults can be overridden on the command line (using --dirstat=<param1,param2,...>). The fallback defaults (when not changed by diff.dirstat) are changes,noncumulative,3. The following parameters are available:

changes
Compute the dirstat numbers by counting the lines that have been removed from the source, or added to the destination. This ignores the amount of pure code movements within a file. In other words, rearranging lines in a file is not counted as much as other changes. This is the default behavior when no parameter is given.
lines
Compute the dirstat numbers by doing the regular line-based diff analysis, and summing the removed/added line counts. (For binary files, count 64-byte chunks instead, since binary files have no natural concept of lines). This is a more expensive --dirstat behavior than the changes behavior, but it does count rearranged lines within a file as much as other changes. The resulting output is consistent with what you get from the other --*stat options.
files
Compute the dirstat numbers by counting the number of files changed. Each changed file counts equally in the dirstat analysis. This is the computationally cheapest --dirstat behavior, since it does not have to look at the file contents at all.
cumulative
Count changes in a child directory for the parent directory as well. Note that when using cumulative, the sum of the percentages reported may exceed 100%. The default (non-cumulative) behavior can be specified with the noncumulative parameter.
<limit>
An integer parameter specifies a cut-off percent (3% by default). Directories contributing less than this percentage of the changes are not shown in the output.

Example: The following will count changed files, while ignoring directories with less than 10% of the total amount of changed files, and accumulating child directory counts in the parent directories: files,10,cumulative.

diff.statGraphWidth
Limit the width of the graph part in --stat output. If set, applies to all commands generating --stat output except format-patch.
diff.context
Generate diffs with <n> lines of context instead of the default of 3. This value is overridden by the -U option.
diff.external
If this config variable is set, diff generation is not performed using the internal diff machinery, but using the given command. Can be overridden with the GIT_EXTERNAL_DIFF environment variable. The command is called with parameters as described under "git Diffs" in Section G.3.1, “git(1)”. Note: if you want to use an external diff program only on a subset of your files, you might want to use Section G.4.2, “gitattributes(5)” instead.
diff.ignoreSubmodules
Sets the default value of --ignore-submodules. Note that this affects only git diff Porcelain, and not lower level diff commands such as git diff-files. git checkout also honors this setting when reporting uncommitted changes. Setting it to all disables the submodule summary normally shown by git commit and git status when status.submoduleSummary is set unless it is overridden by using the --ignore-submodules command-line option. The git submodule commands are not affected by this setting.
diff.mnemonicPrefix

If set, git diff uses a prefix pair that is different from the standard "a/" and "b/" depending on what is being compared. When this configuration is in effect, reverse diff output also swaps the order of the prefixes:

git diff
compares the (i)ndex and the (w)ork tree;
git diff HEAD
compares a (c)ommit and the (w)ork tree;
git diff --cached
compares a (c)ommit and the (i)ndex;
git diff HEAD:file1 file2
compares an (o)bject and a (w)ork tree entity;
git diff --no-index a b
compares two non-git things (1) and (2).
diff.noprefix
If set, git diff does not show any source or destination prefix.
diff.orderFile
File indicating how to order files within a diff, using one shell glob pattern per line. Can be overridden by the -O option to Section G.3.41, “git-diff(1)”.
diff.renameLimit
The number of files to consider when performing the copy/rename detection; equivalent to the git diff option -l.
diff.renames
Whether and how Git detects renames. If set to "false", rename detection is disabled. If set to "true", basic rename detection is enabled. If set to "copies" or "copy", Git will detect copies, as well. Defaults to true. Note that this affects only git diff Porcelain like Section G.3.41, “git-diff(1)” and Section G.3.68, “git-log(1)”, and not lower level commands such as Section G.3.38, “git-diff-files(1)”.
diff.suppressBlankEmpty
A boolean to inhibit the standard behavior of printing a space before each empty output line. Defaults to false.
diff.submodule
Specify the format in which differences in submodules are shown. The "log" format lists the commits in the range like Section G.3.131, “git-submodule(1)” summary does. The "short" format format just shows the names of the commits at the beginning and end of the range. Defaults to short.
diff.wordRegex
A POSIX Extended Regular Expression used to determine what is a "word" when performing word-by-word difference calculations. Character sequences that match the regular expression are "words", all other characters are ignorable whitespace.
diff.<driver>.command
The custom diff driver command. See Section G.4.2, “gitattributes(5)” for details.
diff.<driver>.xfuncname
The regular expression that the diff driver should use to recognize the hunk header. A built-in pattern may also be used. See Section G.4.2, “gitattributes(5)” for details.
diff.<driver>.binary
Set this option to true to make the diff driver treat files as binary. See Section G.4.2, “gitattributes(5)” for details.
diff.<driver>.textconv
The command that the diff driver should call to generate the text-converted version of a file. The result of the conversion is used to generate a human-readable diff. See Section G.4.2, “gitattributes(5)” for details.
diff.<driver>.wordRegex
The regular expression that the diff driver should use to split words in a line. See Section G.4.2, “gitattributes(5)” for details.
diff.<driver>.cachetextconv
Set this option to true to make the diff driver cache the text conversion outputs. See Section G.4.2, “gitattributes(5)” for details.
diff.tool

Controls which diff tool is used by Section G.3.42, “git-difftool(1)”. This variable overrides the value configured in merge.tool. The list below shows the valid built-in values. Any other value is treated as a custom diff tool and requires that a corresponding difftool.<tool>.cmd variable is defined.

  • araxis
  • bc
  • bc3
  • codecompare
  • deltawalker
  • diffmerge
  • diffuse
  • ecmerge
  • emerge
  • examdiff
  • gvimdiff
  • gvimdiff2
  • gvimdiff3
  • kdiff3
  • kompare
  • meld
  • opendiff
  • p4merge
  • tkdiff
  • vimdiff
  • vimdiff2
  • vimdiff3
  • winmerge
  • xxdiff
diff.algorithm

Choose a diff algorithm. The variants are as follows:

default, myers
The basic greedy diff algorithm. Currently, this is the default.
minimal
Spend extra time to make sure the smallest possible diff is produced.
patience
Use "patience diff" algorithm when generating patches.
histogram
This algorithm extends the patience algorithm to "support low-occurrence common elements".
difftool.<tool>.path
Override the path for the given tool. This is useful in case your tool is not in the PATH.
difftool.<tool>.cmd
Specify the command to invoke the specified diff tool. The specified command is evaluated in shell with the following variables available: LOCAL is set to the name of the temporary file containing the contents of the diff pre-image and REMOTE is set to the name of the temporary file containing the contents of the diff post-image.
difftool.prompt
Prompt before each invocation of the diff tool.
fetch.recurseSubmodules
This option can be either set to a boolean value or to on-demand. Setting it to a boolean changes the behavior of fetch and pull to unconditionally recurse into submodules when set to true or to not recurse at all when set to false. When set to on-demand (the default value), fetch and pull will only recurse into a populated submodule when its superproject retrieves a commit that updates the submodule's reference.
fetch.fsckObjects
If it is set to true, git-fetch-pack will check all fetched objects. It will abort in the case of a malformed object or a broken link. The result of an abort are only dangling objects. Defaults to false. If not set, the value of transfer.fsckObjects is used instead.
fetch.unpackLimit
If the number of objects fetched over the Git native transfer is below this limit, then the objects will be unpacked into loose object files. However if the number of received objects equals or exceeds this limit then the received pack will be stored as a pack, after adding any missing delta bases. Storing the pack from a push can make the push operation complete faster, especially on slow filesystems. If not set, the value of transfer.unpackLimit is used instead.
fetch.prune
If true, fetch will automatically behave as if the --prune option was given on the command line. See also remote.<name>.prune.
format.attach
Enable multipart/mixed attachments as the default for format-patch. The value can also be a double quoted string which will enable attachments as the default and set the value as the boundary. See the --attach option in Section G.3.50, “git-format-patch(1)”.
format.numbered
A boolean which can enable or disable sequence numbers in patch subjects. It defaults to "auto" which enables it only if there is more than one patch. It can be enabled or disabled for all messages by setting it to "true" or "false". See --numbered option in Section G.3.50, “git-format-patch(1)”.
format.headers
Additional email headers to include in a patch to be submitted by mail. See Section G.3.50, “git-format-patch(1)”.
format.to , format.cc
Additional recipients to include in a patch to be submitted by mail. See the --to and --cc options in Section G.3.50, “git-format-patch(1)”.
format.subjectPrefix
The default for format-patch is to output files with the [PATCH] subject prefix. Use this variable to change that prefix.
format.signature
The default for format-patch is to output a signature containing the Git version number. Use this variable to change that default. Set this variable to the empty string ("") to suppress signature generation.
format.signatureFile
Works just like format.signature except the contents of the file specified by this variable will be used as the signature.
format.suffix
The default for format-patch is to output files with the suffix .patch. Use this variable to change that suffix (make sure to include the dot if you want it).
format.pretty
The default pretty format for log/show/whatchanged command, See Section G.3.68, “git-log(1)”, Section G.3.126, “git-show(1)”, Section G.3.147, “git-whatchanged(1)”.
format.thread
The default threading style for git format-patch. Can be a boolean value, or shallow or deep. shallow threading makes every mail a reply to the head of the series, where the head is chosen from the cover letter, the --in-reply-to, and the first patch mail, in this order. deep threading makes every mail a reply to the previous one. A true boolean value is the same as shallow, and a false value disables threading.
format.signOff
A boolean value which lets you enable the -s/--signoff option of format-patch by default. Note: Adding the Signed-off-by: line to a patch should be a conscious act and means that you certify you have the rights to submit this work under the same open source license. Please see the SubmittingPatches document for further discussion.
format.coverLetter
A boolean that controls whether to generate a cover-letter when format-patch is invoked, but in addition can be set to "auto", to generate a cover-letter only when there's more than one patch.
format.outputDirectory
Set a custom directory to store the resulting files instead of the current working directory.
filter.<driver>.clean
The command which is used to convert the content of a worktree file to a blob upon checkin. See Section G.4.2, “gitattributes(5)” for details.
filter.<driver>.smudge
The command which is used to convert the content of a blob object to a worktree file upon checkout. See Section G.4.2, “gitattributes(5)” for details.
fsck.<msg-id>

Allows overriding the message type (error, warn or ignore) of a specific message ID such as missingEmail.

For convenience, fsck prefixes the error/warning with the message ID, e.g. "missingEmail: invalid author/committer line - missing email" means that setting fsck.missingEmail = ignore will hide that issue.

This feature is intended to support working with legacy repositories which cannot be repaired without disruptive changes.

fsck.skipList
The path to a sorted list of object names (i.e. one SHA-1 per line) that are known to be broken in a non-fatal way and should be ignored. This feature is useful when an established project should be accepted despite early commits containing errors that can be safely ignored such as invalid committer email addresses. Note: corrupt objects cannot be skipped with this setting.
gc.aggressiveDepth
The depth parameter used in the delta compression algorithm used by git gc --aggressive. This defaults to 250.
gc.aggressiveWindow
The window size parameter used in the delta compression algorithm used by git gc --aggressive. This defaults to 250.
gc.auto
When there are approximately more than this many loose objects in the repository, git gc --auto will pack them. Some Porcelain commands use this command to perform a light-weight garbage collection from time to time. The default value is 6700. Setting this to 0 disables it.
gc.autoPackLimit
When there are more than this many packs that are not marked with *.keep file in the repository, git gc --auto consolidates them into one larger pack. The default value is 50. Setting this to 0 disables it.
gc.autoDetach
Make git gc --auto return immediately and run in background if the system supports it. Default is true.
gc.packRefs
Running git pack-refs in a repository renders it unclonable by Git versions prior to 1.5.1.2 over dumb transports such as HTTP. This variable determines whether git gc runs git pack-refs. This can be set to notbare to enable it within all non-bare repos or it can be set to a boolean value. The default is true.
gc.pruneExpire
When git gc is run, it will call prune --expire 2.weeks.ago. Override the grace period with this config variable. The value "now" may be used to disable this grace period and always prune unreachable objects immediately, or "never" may be used to suppress pruning.
gc.worktreePruneExpire
When git gc is run, it calls git worktree prune --expire 3.months.ago. This config variable can be used to set a different grace period. The value "now" may be used to disable the grace period and prune $GIT_DIR/worktrees immediately, or "never" may be used to suppress pruning.
gc.reflogExpire , gc.<pattern>.reflogExpire
git reflog expire removes reflog entries older than this time; defaults to 90 days. The value "now" expires all entries immediately, and "never" suppresses expiration altogether. With "<pattern>" (e.g. "refs/stash") in the middle the setting applies only to the refs that match the <pattern>.
gc.reflogExpireUnreachable , gc.<pattern>.reflogExpireUnreachable
git reflog expire removes reflog entries older than this time and are not reachable from the current tip; defaults to 30 days. The value "now" expires all entries immediately, and "never" suppresses expiration altogether. With "<pattern>" (e.g. "refs/stash") in the middle, the setting applies only to the refs that match the <pattern>.
gc.rerereResolved
Records of conflicted merge you resolved earlier are kept for this many days when git rerere gc is run. The default is 60 days. See Section G.3.110, “git-rerere(1)”.
gc.rerereUnresolved
Records of conflicted merge you have not resolved are kept for this many days when git rerere gc is run. The default is 15 days. See Section G.3.110, “git-rerere(1)”.
gitcvs.commitMsgAnnotation
Append this string to each commit message. Set to empty string to disable this feature. Defaults to "via git-CVS emulator".
gitcvs.enabled
Whether the CVS server interface is enabled for this repository. See Section G.3.35, “git-cvsserver(1)”.
gitcvs.logFile
Path to a log file where the CVS server interface well… logs various stuff. See Section G.3.35, “git-cvsserver(1)”.
gitcvs.usecrlfattr
If true, the server will look up the end-of-line conversion attributes for files to determine the -k modes to use. If the attributes force Git to treat a file as text, the -k mode will be left blank so CVS clients will treat it as text. If they suppress text conversion, the file will be set with -kb mode, which suppresses any newline munging the client might otherwise do. If the attributes do not allow the file type to be determined, then gitcvs.allBinary is used. See Section G.4.2, “gitattributes(5)”.
gitcvs.allBinary
This is used if gitcvs.usecrlfattr does not resolve the correct -kb mode to use. If true, all unresolved files are sent to the client in mode -kb. This causes the client to treat them as binary files, which suppresses any newline munging it otherwise might do. Alternatively, if it is set to "guess", then the contents of the file are examined to decide if it is binary, similar to core.autocrlf.
gitcvs.dbName
Database used by git-cvsserver to cache revision information derived from the Git repository. The exact meaning depends on the used database driver, for SQLite (which is the default driver) this is a filename. Supports variable substitution (see Section G.3.35, “git-cvsserver(1)” for details). May not contain semicolons (;). Default: %Ggitcvs.%m.sqlite
gitcvs.dbDriver
Used Perl DBI driver. You can specify any available driver for this here, but it might not work. git-cvsserver is tested with DBD::SQLite, reported to work with DBD::Pg, and reported not to work with DBD::mysql. Experimental feature. May not contain double colons (:). Default: SQLite. See Section G.3.35, “git-cvsserver(1)”.
gitcvs.dbUser, gitcvs.dbPass
Database user and password. Only useful if setting gitcvs.dbDriver, since SQLite has no concept of database users and/or passwords. gitcvs.dbUser supports variable substitution (see Section G.3.35, “git-cvsserver(1)” for details).
gitcvs.dbTableNamePrefix
Database table name prefix. Prepended to the names of any database tables used, allowing a single database to be used for several repositories. Supports variable substitution (see Section G.3.35, “git-cvsserver(1)” for details). Any non-alphabetic characters will be replaced with underscores.

All gitcvs variables except for gitcvs.usecrlfattr and gitcvs.allBinary can also be specified as gitcvs.<access_method>.<varname> (where access_method is one of "ext" and "pserver") to make them apply only for the given access method.

gitweb.category , gitweb.description , gitweb.owner , gitweb.url
See Section G.4.13, “gitweb(1)” for description.
gitweb.avatar , gitweb.blame , gitweb.grep , gitweb.highlight , gitweb.patches , gitweb.pickaxe , gitweb.remote_heads , gitweb.showSizes , gitweb.snapshot
See Section G.4.14, “gitweb.conf(5)” for description.
grep.lineNumber
If set to true, enable -n option by default.
grep.patternType
Set the default matching behavior. Using a value of basic, extended, fixed, or perl will enable the --basic-regexp, --extended-regexp, --fixed-strings, or --perl-regexp option accordingly, while the value default will return to the default matching behavior.
grep.extendedRegexp
If set to true, enable --extended-regexp option by default. This option is ignored when the grep.patternType option is set to a value other than default.
grep.threads
Number of grep worker threads to use. See grep.threads in Section G.3.55, “git-grep(1)” for more information.
grep.fallbackToNoIndex
If set to true, fall back to git grep --no-index if git grep is executed outside of a git repository. Defaults to false.
gpg.program
Use this custom program instead of "gpg" found on $PATH when making or verifying a PGP signature. The program must support the same command-line interface as GPG, namely, to verify a detached signature, "gpg --verify $file - <$signature" is run, and the program is expected to signal a good signature by exiting with code 0, and to generate an ASCII-armored detached signature, the standard input of "gpg -bsau $key" is fed with the contents to be signed, and the program is expected to send the result to its standard output.
gui.commitMsgWidth
Defines how wide the commit message window is in the Section G.3.56, “git-gui(1)”. "75" is the default.
gui.diffContext
Specifies how many context lines should be used in calls to diff made by the Section G.3.56, “git-gui(1)”. The default is "5".
gui.displayUntracked
Determines if ??? shows untracked files in the file list. The default is "true".
gui.encoding
Specifies the default encoding to use for displaying of file contents in Section G.3.56, “git-gui(1)” and Section G.4.7, “gitk(1)”. It can be overridden by setting the encoding attribute for relevant files (see Section G.4.2, “gitattributes(5)”). If this option is not set, the tools default to the locale encoding.
gui.matchTrackingBranch
Determines if new branches created with Section G.3.56, “git-gui(1)” should default to tracking remote branches with matching names or not. Default: "false".
gui.newBranchTemplate
Is used as suggested name when creating new branches using the Section G.3.56, “git-gui(1)”.
gui.pruneDuringFetch
"true" if Section G.3.56, “git-gui(1)” should prune remote-tracking branches when performing a fetch. The default value is "false".
gui.trustmtime
Determines if Section G.3.56, “git-gui(1)” should trust the file modification timestamp or not. By default the timestamps are not trusted.
gui.spellingDictionary
Specifies the dictionary used for spell checking commit messages in the Section G.3.56, “git-gui(1)”. When set to "none" spell checking is turned off.
gui.fastCopyBlame
If true, git gui blame uses -C instead of -C -C for original location detection. It makes blame significantly faster on huge repositories at the expense of less thorough copy detection.
gui.copyBlameThreshold
Specifies the threshold to use in git gui blame original location detection, measured in alphanumeric characters. See the Section G.3.9, “git-blame(1)” manual for more information on copy detection.
gui.blamehistoryctx
Specifies the radius of history context in days to show in Section G.4.7, “gitk(1)” for the selected commit, when the Show History Context menu item is invoked from git gui blame. If this variable is set to zero, the whole history is shown.
guitool.<name>.cmd
Specifies the shell command line to execute when the corresponding item of the Section G.3.56, “git-gui(1)” Tools menu is invoked. This option is mandatory for every tool. The command is executed from the root of the working directory, and in the environment it receives the name of the tool as GIT_GUITOOL, the name of the currently selected file as FILENAME, and the name of the current branch as CUR_BRANCH (if the head is detached, CUR_BRANCH is empty).
guitool.<name>.needsFile
Run the tool only if a diff is selected in the GUI. It guarantees that FILENAME is not empty.
guitool.<name>.noConsole
Run the command silently, without creating a window to display its output.
guitool.<name>.noRescan
Don't rescan the working directory for changes after the tool finishes execution.
guitool.<name>.confirm
Show a confirmation dialog before actually running the tool.
guitool.<name>.argPrompt
Request a string argument from the user, and pass it to the tool through the ARGS environment variable. Since requesting an argument implies confirmation, the confirm option has no effect if this is enabled. If the option is set to true, yes, or 1, the dialog uses a built-in generic prompt; otherwise the exact value of the variable is used.
guitool.<name>.revPrompt
Request a single valid revision from the user, and set the REVISION environment variable. In other aspects this option is similar to argPrompt, and can be used together with it.
guitool.<name>.revUnmerged
Show only unmerged branches in the revPrompt subdialog. This is useful for tools similar to merge or rebase, but not for things like checkout or reset.
guitool.<name>.title
Specifies the title to use for the prompt dialog. The default is the tool name.
guitool.<name>.prompt
Specifies the general prompt string to display at the top of the dialog, before subsections for argPrompt and revPrompt. The default value includes the actual command.
help.browser
Specify the browser that will be used to display help in the web format. See Section G.3.58, “git-help(1)”.
help.format
Override the default help format used by Section G.3.58, “git-help(1)”. Values man, info, web and html are supported. man is the default. web and html are the same.
help.autoCorrect
Automatically correct and execute mistyped commands after waiting for the given number of deciseconds (0.1 sec). If more than one command can be deduced from the entered text, nothing will be executed. If the value of this option is negative, the corrected command will be executed immediately. If the value is 0 - the command will be just shown but not executed. This is the default.
help.htmlPath
Specify the path where the HTML documentation resides. File system paths and URLs are supported. HTML pages will be prefixed with this path when help is displayed in the web format. This defaults to the documentation path of your Git installation.
http.proxy
Override the HTTP proxy, normally configured using the http_proxy, https_proxy, and all_proxy environment variables (see curl(1)). In addition to the syntax understood by curl, it is possible to specify a proxy string with a user name but no password, in which case git will attempt to acquire one in the same way it does for other credentials. See Section G.4.3, “gitcredentials(7)” for more information. The syntax thus is [protocol://][user[:password]@]proxyhost[:port]. This can be overridden on a per-remote basis; see remote.<name>.proxy
http.proxyAuthMethod

Set the method with which to authenticate against the HTTP proxy. This only takes effect if the configured proxy string contains a user name part (i.e. is of the form [email protected] or [email protected]:port). This can be overridden on a per-remote basis; see remote.<name>.proxyAuthMethod. Both can be overridden by the GIT_HTTP_PROXY_AUTHMETHOD environment variable. Possible values are:

  • anyauth - Automatically pick a suitable authentication method. It is assumed that the proxy answers an unauthenticated request with a 407 status code and one or more Proxy-authenticate headers with supported authentication methods. This is the default.
  • basic - HTTP Basic authentication
  • digest - HTTP Digest authentication; this prevents the password from being transmitted to the proxy in clear text
  • negotiate - GSS-Negotiate authentication (compare the --negotiate option of curl(1))
  • ntlm - NTLM authentication (compare the --ntlm option of curl(1))
http.emptyAuth
Attempt authentication without seeking a username or password. This can be used to attempt GSS-Negotiate authentication without specifying a username in the URL, as libcurl normally requires a username for authentication.
http.cookieFile
File containing previously stored cookie lines which should be used in the Git http session, if they match the server. The file format of the file to read cookies from should be plain HTTP headers or the Netscape/Mozilla cookie file format (see ???). NOTE that the file specified with http.cookieFile is only used as input unless http.saveCookies is set.
http.saveCookies
If set, store cookies received during requests to the file specified by http.cookieFile. Has no effect if http.cookieFile is unset.
http.sslVersion

The SSL version to use when negotiating an SSL connection, if you want to force the default. The available and default version depend on whether libcurl was built against NSS or OpenSSL and the particular configuration of the crypto library in use. Internally this sets the CURLOPT_SSL_VERSION option; see the libcurl documentation for more details on the format of this option and for the ssl version supported. Actually the possible values of this option are:

  • sslv2
  • sslv3
  • tlsv1
  • tlsv1.0
  • tlsv1.1
  • tlsv1.2

Can be overridden by the GIT_SSL_VERSION environment variable. To force git to use libcurl's default ssl version and ignore any explicit http.sslversion option, set GIT_SSL_VERSION to the empty string.

http.sslCipherList

A list of SSL ciphers to use when negotiating an SSL connection. The available ciphers depend on whether libcurl was built against NSS or OpenSSL and the particular configuration of the crypto library in use. Internally this sets the CURLOPT_SSL_CIPHER_LIST option; see the libcurl documentation for more details on the format of this list.

Can be overridden by the GIT_SSL_CIPHER_LIST environment variable. To force git to use libcurl's default cipher list and ignore any explicit http.sslCipherList option, set GIT_SSL_CIPHER_LIST to the empty string.

http.sslVerify
Whether to verify the SSL certificate when fetching or pushing over HTTPS. Can be overridden by the GIT_SSL_NO_VERIFY environment variable.
http.sslCert
File containing the SSL certificate when fetching or pushing over HTTPS. Can be overridden by the GIT_SSL_CERT environment variable.
http.sslKey
File containing the SSL private key when fetching or pushing over HTTPS. Can be overridden by the GIT_SSL_KEY environment variable.
http.sslCertPasswordProtected
Enable Git's password prompt for the SSL certificate. Otherwise OpenSSL will prompt the user, possibly many times, if the certificate or private key is encrypted. Can be overridden by the GIT_SSL_CERT_PASSWORD_PROTECTED environment variable.
http.sslCAInfo
File containing the certificates to verify the peer with when fetching or pushing over HTTPS. Can be overridden by the GIT_SSL_CAINFO environment variable.
http.sslCAPath
Path containing files with the CA certificates to verify the peer with when fetching or pushing over HTTPS. Can be overridden by the GIT_SSL_CAPATH environment variable.
http.pinnedpubkey
Public key of the https service. It may either be the filename of a PEM or DER encoded public key file or a string starting with sha256// followed by the base64 encoded sha256 hash of the public key. See also libcurl CURLOPT_PINNEDPUBLICKEY. git will exit with an error if this option is set but not supported by cURL.
http.sslTry
Attempt to use AUTH SSL/TLS and encrypted data transfers when connecting via regular FTP protocol. This might be needed if the FTP server requires it for security reasons or you wish to connect securely whenever remote FTP server supports it. Default is false since it might trigger certificate verification errors on misconfigured servers.
http.maxRequests
How many HTTP requests to launch in parallel. Can be overridden by the GIT_HTTP_MAX_REQUESTS environment variable. Default is 5.
http.minSessions
The number of curl sessions (counted across slots) to be kept across requests. They will not be ended with curl_easy_cleanup() until http_cleanup() is invoked. If USE_CURL_MULTI is not defined, this value will be capped at 1. Defaults to 1.
http.postBuffer
Maximum size in bytes of the buffer used by smart HTTP transports when POSTing data to the remote system. For requests larger than this buffer size, HTTP/1.1 and Transfer-Encoding: chunked is used to avoid creating a massive pack file locally. Default is 1 MiB, which is sufficient for most requests.
http.lowSpeedLimit, http.lowSpeedTime
If the HTTP transfer speed is less than http.lowSpeedLimit for longer than http.lowSpeedTime seconds, the transfer is aborted. Can be overridden by the GIT_HTTP_LOW_SPEED_LIMIT and GIT_HTTP_LOW_SPEED_TIME environment variables.
http.noEPSV
A boolean which disables using of EPSV ftp command by curl. This can helpful with some "poor" ftp servers which don't support EPSV mode. Can be overridden by the GIT_CURL_FTP_NO_EPSV environment variable. Default is false (curl will use EPSV).
http.userAgent
The HTTP USER_AGENT string presented to an HTTP server. The default value represents the version of the client Git such as git/1.7.1. This option allows you to override this value to a more common value such as Mozilla/4.0. This may be necessary, for instance, if connecting through a firewall that restricts HTTP connections to a set of common USER_AGENT strings (but not including those like git/1.7.1). Can be overridden by the GIT_HTTP_USER_AGENT environment variable.
http.<url>.*

Any of the http.* options above can be applied selectively to some URLs. For a config key to match a URL, each element of the config key is compared to that of the URL, in the following order:

  1. Scheme (e.g., https in https://example.com/). This field must match exactly between the config key and the URL.
  2. Host/domain name (e.g., example.com in https://example.com/). This field must match exactly between the config key and the URL.
  3. Port number (e.g., 8080 in http://example.com:8080/). This field must match exactly between the config key and the URL. Omitted port numbers are automatically converted to the correct default for the scheme before matching.
  4. Path (e.g., repo.git in https://example.com/repo.git). The path field of the config key must match the path field of the URL either exactly or as a prefix of slash-delimited path elements. This means a config key with path foo/ matches URL path foo/bar. A prefix can only match on a slash (/) boundary. Longer matches take precedence (so a config key with path foo/bar is a better match to URL path foo/bar than a config key with just path foo/).
  5. User name (e.g., user in https://[email protected]/repo.git). If the config key has a user name it must match the user name in the URL exactly. If the config key does not have a user name, that config key will match a URL with any user name (including none), but at a lower precedence than a config key with a user name.

The list above is ordered by decreasing precedence; a URL that matches a config key's path is preferred to one that matches its user name. For example, if the URL is https://[email protected]/foo/bar a config key match of https://example.com/foo will be preferred over a config key match of https://[email protected].

All URLs are normalized before attempting any matching (the password part, if embedded in the URL, is always ignored for matching purposes) so that equivalent URLs that are simply spelled differently will match properly. Environment variable settings always override any matches. The URLs that are matched against are those given directly to Git commands. This means any URLs visited as a result of a redirection do not participate in matching.

i18n.commitEncoding
Character encoding the commit messages are stored in; Git itself does not care per se, but this information is necessary e.g. when importing commits from emails or in the gitk graphical history browser (and possibly at other places in the future or in other porcelains). See e.g. Section G.3.72, “git-mailinfo(1)”. Defaults to utf-8.
i18n.logOutputEncoding
Character encoding the commit messages are converted to when running git log and friends.
imap
The configuration variables in the imap section are described in Section G.3.62, “git-imap-send(1)”.
index.version
Specify the version with which new index files should be initialized. This does not affect existing repositories.
init.templateDir
Specify the directory from which templates will be copied. (See the "TEMPLATE DIRECTORY" section of Section G.3.65, “git-init(1)”.)
instaweb.browser
Specify the program that will be used to browse your working repository in gitweb. See Section G.3.66, “git-instaweb(1)”.
instaweb.httpd
The HTTP daemon command-line to start gitweb on your working repository. See Section G.3.66, “git-instaweb(1)”.
instaweb.local
If true the web server started by Section G.3.66, “git-instaweb(1)” will be bound to the local IP (127.0.0.1).
instaweb.modulePath
The default module path for Section G.3.66, “git-instaweb(1)” to use instead of /usr/lib/apache2/modules. Only used if httpd is Apache.
instaweb.port
The port number to bind the gitweb httpd to. See Section G.3.66, “git-instaweb(1)”.
interactive.singleKey
In interactive commands, allow the user to provide one-letter input with a single key (i.e., without hitting enter). Currently this is used by the --patch mode of Section G.3.2, “git-add(1)”, Section G.3.18, “git-checkout(1)”, Section G.3.26, “git-commit(1)”, Section G.3.111, “git-reset(1)”, and Section G.3.128, “git-stash(1)”. Note that this setting is silently ignored if portable keystroke input is not available; requires the Perl module Term::ReadKey.
interactive.diffFilter
When an interactive command (such as git add --patch) shows a colorized diff, git will pipe the diff through the shell command defined by this configuration variable. The command may mark up the diff further for human consumption, provided that it retains a one-to-one correspondence with the lines in the original diff. Defaults to disabled (no filtering).
log.abbrevCommit
If true, makes Section G.3.68, “git-log(1)”, Section G.3.126, “git-show(1)”, and Section G.3.147, “git-whatchanged(1)” assume --abbrev-commit. You may override this option with --no-abbrev-commit.
log.date
Set the default date-time mode for the log command. Setting a value for log.date is similar to using git log's --date option. See Section G.3.68, “git-log(1)” for details.
log.decorate
Print out the ref names of any commits that are shown by the log command. If short is specified, the ref name prefixes refs/heads/, refs/tags/ and refs/remotes/ will not be printed. If full is specified, the full ref name (including prefix) will be printed. This is the same as the log commands --decorate option.
log.follow
If true, git log will act as if the --follow option was used when a single <path> is given. This has the same limitations as --follow, i.e. it cannot be used to follow multiple files and does not work well on non-linear history.
log.showRoot
If true, the initial commit will be shown as a big creation event. This is equivalent to a diff against an empty tree. Tools like Section G.3.68, “git-log(1)” or Section G.3.147, “git-whatchanged(1)”, which normally hide the root commit will now show it. True by default.
log.mailmap
If true, makes Section G.3.68, “git-log(1)”, Section G.3.126, “git-show(1)”, and Section G.3.147, “git-whatchanged(1)” assume --use-mailmap.
mailinfo.scissors
If true, makes Section G.3.72, “git-mailinfo(1)” (and therefore Section G.3.3, “git-am(1)”) act by default as if the --scissors option was provided on the command-line. When active, this features removes everything from the message body before a scissors line (i.e. consisting mainly of ">8", "8<" and "-").
mailmap.file
The location of an augmenting mailmap file. The default mailmap, located in the root of the repository, is loaded first, then the mailmap file pointed to by this variable. The location of the mailmap file may be in a repository subdirectory, or somewhere outside of the repository itself. See Section G.3.122, “git-shortlog(1)” and Section G.3.9, “git-blame(1)”.
mailmap.blob
Like mailmap.file, but consider the value as a reference to a blob in the repository. If both mailmap.file and mailmap.blob are given, both are parsed, with entries from mailmap.file taking precedence. In a bare repository, this defaults to HEAD:.mailmap. In a non-bare repository, it defaults to empty.
man.viewer
Specify the programs that may be used to display help in the man format. See Section G.3.58, “git-help(1)”.
man.<tool>.cmd
Specify the command to invoke the specified man viewer. The specified command is evaluated in shell with the man page passed as argument. (See Section G.3.58, “git-help(1)”.)
man.<tool>.path
Override the path for the given tool that may be used to display help in the man format. See Section G.3.58, “git-help(1)”.
merge.conflictStyle
Specify the style in which conflicted hunks are written out to working tree files upon merge. The default is "merge", which shows a <<<<<<< conflict marker, changes made by one side, a ======= marker, changes made by the other side, and then a >>>>>>> marker. An alternate style, "diff3", adds a ||||||| marker and the original text before the ======= marker.
merge.defaultToUpstream
If merge is called without any commit argument, merge the upstream branches configured for the current branch by using their last observed values stored in their remote-tracking branches. The values of the branch.<current branch>.merge that name the branches at the remote named by branch.<current branch>.remote are consulted, and then they are mapped via remote.<remote>.fetch to their corresponding remote-tracking branches, and the tips of these tracking branches are merged.
merge.ff
By default, Git does not create an extra merge commit when merging a commit that is a descendant of the current commit. Instead, the tip of the current branch is fast-forwarded. When set to false, this variable tells Git to create an extra merge commit in such a case (equivalent to giving the --no-ff option from the command line). When set to only, only such fast-forward merges are allowed (equivalent to giving the --ff-only option from the command line).
merge.branchdesc
In addition to branch names, populate the log message with the branch description text associated with them. Defaults to false.
merge.log
In addition to branch names, populate the log message with at most the specified number of one-line descriptions from the actual commits that are being merged. Defaults to false, and true is a synonym for 20.
merge.renameLimit
The number of files to consider when performing rename detection during a merge; if not specified, defaults to the value of diff.renameLimit.
merge.renormalize
Tell Git that canonical representation of files in the repository has changed over time (e.g. earlier commits record text files with CRLF line endings, but recent ones use LF line endings). In such a repository, Git can convert the data recorded in commits to a canonical form before performing a merge to reduce unnecessary conflicts. For more information, see section "Merging branches with differing checkin/checkout attributes" in Section G.4.2, “gitattributes(5)”.
merge.stat
Whether to print the diffstat between ORIG_HEAD and the merge result at the end of the merge. True by default.
merge.tool

Controls which merge tool is used by Section G.3.81, “git-mergetool(1)”. The list below shows the valid built-in values. Any other value is treated as a custom merge tool and requires that a corresponding mergetool.<tool>.cmd variable is defined.

  • araxis
  • bc
  • bc3
  • codecompare
  • deltawalker
  • diffmerge
  • diffuse
  • ecmerge
  • emerge
  • examdiff
  • gvimdiff
  • gvimdiff2
  • gvimdiff3
  • kdiff3
  • meld
  • opendiff
  • p4merge
  • tkdiff
  • tortoisemerge
  • vimdiff
  • vimdiff2
  • vimdiff3
  • winmerge
  • xxdiff
merge.verbosity
Controls the amount of output shown by the recursive merge strategy. Level 0 outputs nothing except a final error message if conflicts were detected. Level 1 outputs only conflicts, 2 outputs conflicts and file changes. Level 5 and above outputs debugging information. The default is level 2. Can be overridden by the GIT_MERGE_VERBOSITY environment variable.
merge.<driver>.name
Defines a human-readable name for a custom low-level merge driver. See Section G.4.2, “gitattributes(5)” for details.
merge.<driver>.driver
Defines the command that implements a custom low-level merge driver. See Section G.4.2, “gitattributes(5)” for details.
merge.<driver>.recursive
Names a low-level merge driver to be used when performing an internal merge between common ancestors. See Section G.4.2, “gitattributes(5)” for details.
mergetool.<tool>.path
Override the path for the given tool. This is useful in case your tool is not in the PATH.
mergetool.<tool>.cmd
Specify the command to invoke the specified merge tool. The specified command is evaluated in shell with the following variables available: BASE is the name of a temporary file containing the common base of the files to be merged, if available; LOCAL is the name of a temporary file containing the contents of the file on the current branch; REMOTE is the name of a temporary file containing the contents of the file from the branch being merged; MERGED contains the name of the file to which the merge tool should write the results of a successful merge.
mergetool.<tool>.trustExitCode
For a custom merge command, specify whether the exit code of the merge command can be used to determine whether the merge was successful. If this is not set to true then the merge target file timestamp is checked and the merge assumed to have been successful if the file has been updated, otherwise the user is prompted to indicate the success of the merge.
mergetool.meld.hasOutput
Older versions of meld do not support the --output option. Git will attempt to detect whether meld supports --output by inspecting the output of meld --help. Configuring mergetool.meld.hasOutput will make Git skip these checks and use the configured value instead. Setting mergetool.meld.hasOutput to true tells Git to unconditionally use the --output option, and false avoids using --output.
mergetool.keepBackup
After performing a merge, the original file with conflict markers can be saved as a file with a .orig extension. If this variable is set to false then this file is not preserved. Defaults to true (i.e. keep the backup files).
mergetool.keepTemporaries
When invoking a custom merge tool, Git uses a set of temporary files to pass to the tool. If the tool returns an error and this variable is set to true, then these temporary files will be preserved, otherwise they will be removed after the tool has exited. Defaults to false.
mergetool.writeToTemp
Git writes temporary BASE, LOCAL, and REMOTE versions of conflicting files in the worktree by default. Git will attempt to use a temporary directory for these files when set true. Defaults to false.
mergetool.prompt
Prompt before each invocation of the merge resolution program.
notes.mergeStrategy
Which merge strategy to choose by default when resolving notes conflicts. Must be one of manual, ours, theirs, union, or cat_sort_uniq. Defaults to manual. See "NOTES MERGE STRATEGIES" section of Section G.3.86, “git-notes(1)” for more information on each strategy.
notes.<name>.mergeStrategy
Which merge strategy to choose when doing a notes merge into refs/notes/<name>. This overrides the more general "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section in Section G.3.86, “git-notes(1)” for more information on the available strategies.
notes.displayRef

The (fully qualified) refname from which to show notes when showing commit messages. The value of this variable can be set to a glob, in which case notes from all matching refs will be shown. You may also specify this configuration variable several times. A warning will be issued for refs that do not exist, but a glob that does not match any refs is silently ignored.

This setting can be overridden with the GIT_NOTES_DISPLAY_REF environment variable, which must be a colon separated list of refs or globs.

The effective value of "core.notesRef" (possibly overridden by GIT_NOTES_REF) is also implicitly added to the list of refs to be displayed.

notes.rewrite.<command>
When rewriting commits with <command> (currently amend or rebase) and this variable is set to true, Git automatically copies your notes from the original to the rewritten commit. Defaults to true, but see "notes.rewriteRef" below.
notes.rewriteMode

When copying notes during a rewrite (see the "notes.rewrite.<command>" option), determines what to do if the target commit already has a note. Must be one of overwrite, concatenate, cat_sort_uniq, or ignore. Defaults to concatenate.

This setting can be overridden with the GIT_NOTES_REWRITE_MODE environment variable.

notes.rewriteRef

When copying notes during a rewrite, specifies the (fully qualified) ref whose notes should be copied. The ref may be a glob, in which case notes in all matching refs will be copied. You may also specify this configuration several times.

Does not have a default value; you must configure this variable to enable note rewriting. Set it to refs/notes/commits to enable rewriting for the default commit notes.

This setting can be overridden with the GIT_NOTES_REWRITE_REF environment variable, which must be a colon separated list of refs or globs.

pack.window
The size of the window used by Section G.3.88, “git-pack-objects(1)” when no window size is given on the command line. Defaults to 10.
pack.depth
The maximum delta depth used by Section G.3.88, “git-pack-objects(1)” when no maximum depth is given on the command line. Defaults to 50.
pack.windowMemory
The maximum size of memory that is consumed by each thread in Section G.3.88, “git-pack-objects(1)” for pack window memory when no limit is given on the command line. The value can be suffixed with "k", "m", or "g". When left unconfigured (or set explicitly to 0), there will be no limit.
pack.compression

An integer -1..9, indicating the compression level for objects in a pack file. -1 is the zlib default. 0 means no compression, and 1..9 are various speed/size tradeoffs, 9 being slowest. If not set, defaults to core.compression. If that is not set, defaults to -1, the zlib default, which is "a default compromise between speed and compression (currently equivalent to level 6)."

Note that changing the compression level will not automatically recompress all existing objects. You can force recompression by passing the -F option to Section G.3.107, “git-repack(1)”.

pack.deltaCacheSize
The maximum memory in bytes used for caching deltas in Section G.3.88, “git-pack-objects(1)” before writing them out to a pack. This cache is used to speed up the writing object phase by not having to recompute the final delta result once the best match for all objects is found. Repacking large repositories on machines which are tight with memory might be badly impacted by this though, especially if this cache pushes the system into swapping. A value of 0 means no limit. The smallest size of 1 byte may be used to virtually disable this cache. Defaults to 256 MiB.
pack.deltaCacheLimit
The maximum size of a delta, that is cached in Section G.3.88, “git-pack-objects(1)”. This cache is used to speed up the writing object phase by not having to recompute the final delta result once the best match for all objects is found. Defaults to 1000.
pack.threads
Specifies the number of threads to spawn when searching for best delta matches. This requires that Section G.3.88, “git-pack-objects(1)” be compiled with pthreads otherwise this option is ignored with a warning. This is meant to reduce packing time on multiprocessor machines. The required amount of memory for the delta search window is however multiplied by the number of threads. Specifying 0 will cause Git to auto-detect the number of CPU's and set the number of threads accordingly.
pack.indexVersion

Specify the default pack index version. Valid values are 1 for legacy pack index used by Git versions prior to 1.5.2, and 2 for the new pack index with capabilities for packs larger than 4 GB as well as proper protection against the repacking of corrupted packs. Version 2 is the default. Note that version 2 is enforced and this config option ignored whenever the corresponding pack is larger than 2 GB.

If you have an old Git that does not understand the version 2 *.idx file, cloning or fetching over a non native protocol (e.g. "http") that will copy both *.pack file and corresponding *.idx file from the other side may give you a repository that cannot be accessed with your older version of Git. If the *.pack file is smaller than 2 GB, however, you can use Section G.3.63, “git-index-pack(1)” on the *.pack file to regenerate the *.idx file.

pack.packSizeLimit
The maximum size of a pack. This setting only affects packing to a file when repacking, i.e. the git:// protocol is unaffected. It can be overridden by the --max-pack-size option of Section G.3.107, “git-repack(1)”. The minimum size allowed is limited to 1 MiB. The default is unlimited. Common unit suffixes of k, m, or g are supported.
pack.useBitmaps
When true, git will use pack bitmaps (if available) when packing to stdout (e.g., during the server side of a fetch). Defaults to true. You should not generally need to turn this off unless you are debugging pack bitmaps.
pack.writeBitmaps (deprecated)
This is a deprecated synonym for repack.writeBitmaps.
pack.writeBitmapHashCache
When true, git will include a "hash cache" section in the bitmap index (if one is written). This cache can be used to feed git's delta heuristics, potentially leading to better deltas between bitmapped and non-bitmapped objects (e.g., when serving a fetch between an older, bitmapped pack and objects that have been pushed since the last gc). The downside is that it consumes 4 bytes per object of disk space, and that JGit's bitmap implementation does not understand it, causing it to complain if Git and JGit are used on the same repository. Defaults to false.
pager.<cmd>
If the value is boolean, turns on or off pagination of the output of a particular Git subcommand when writing to a tty. Otherwise, turns on pagination for the subcommand using the pager specified by the value of pager.<cmd>. If --paginate or --no-pager is specified on the command line, it takes precedence over this option. To disable pagination for all commands, set core.pager or GIT_PAGER to cat.
pretty.<name>
Alias for a --pretty= format string, as specified in Section G.3.68, “git-log(1)”. Any aliases defined here can be used just as the built-in pretty formats could. For example, running git config pretty.changelog "format:* %H %s" would cause the invocation git log --pretty=changelog to be equivalent to running git log "--pretty=format:* %H %s". Note that an alias with the same name as a built-in format will be silently ignored.
pull.ff
By default, Git does not create an extra merge commit when merging a commit that is a descendant of the current commit. Instead, the tip of the current branch is fast-forwarded. When set to false, this variable tells Git to create an extra merge commit in such a case (equivalent to giving the --no-ff option from the command line). When set to only, only such fast-forward merges are allowed (equivalent to giving the --ff-only option from the command line). This setting overrides merge.ff when pulling.
pull.rebase

When true, rebase branches on top of the fetched branch, instead of merging the default branch from the default remote when "git pull" is run. See "branch.<name>.rebase" for setting this on a per-branch basis.

When preserve, also pass --preserve-merges along to git rebase so that locally committed merge commits will not be flattened by running git pull.

When the value is interactive, the rebase is run in interactive mode.

NOTE: this is a possibly dangerous operation; do not use it unless you understand the implications (see Section G.3.99, “git-rebase(1)” for details).

pull.octopus
The default merge strategy to use when pulling multiple branches at once.
pull.twohead
The default merge strategy to use when pulling a single branch.
push.default

Defines the action git push should take if no refspec is explicitly given. Different values are well-suited for specific workflows; for instance, in a purely central workflow (i.e. the fetch source is equal to the push destination), upstream is probably what you want. Possible values are:

  • nothing - do not push anything (error out) unless a refspec is explicitly given. This is primarily meant for people who want to avoid mistakes by always being explicit.
  • current - push the current branch to update a branch with the same name on the receiving end. Works in both central and non-central workflows.
  • upstream - push the current branch back to the branch whose changes are usually integrated into the current branch (which is called @{upstream}). This mode only makes sense if you are pushing to the same repository you would normally pull from (i.e. central workflow).
  • simple - in centralized workflow, work like upstream with an added safety to refuse to push if the upstream branch's name is different from the local one.

    When pushing to a remote that is different from the remote you normally pull from, work as current. This is the safest option and is suited for beginners.

    This mode has become the default in Git 2.0.

  • matching - push all branches having the same name on both ends. This makes the repository you are pushing to remember the set of branches that will be pushed out (e.g. if you always push maint and master there and no other branches, the repository you push to will have these two branches, and your local maint and master will be pushed there).

    To use this mode effectively, you have to make sure all the branches you would push out are ready to be pushed out before running git push, as the whole point of this mode is to allow you to push all of the branches in one go. If you usually finish work on only one branch and push out the result, while other branches are unfinished, this mode is not for you. Also this mode is not suitable for pushing into a shared central repository, as other people may add new branches there, or update the tip of existing branches outside your control.

    This used to be the default, but not since Git 2.0 (simple is the new default).

push.followTags
If set to true enable --follow-tags option by default. You may override this configuration at time of push by specifying --no-follow-tags.
push.gpgSign
May be set to a boolean value, or the string if-asked. A true value causes all pushes to be GPG signed, as if --signed is passed to Section G.3.96, “git-push(1)”. The string if-asked causes pushes to be signed if the server supports it, as if --signed=if-asked is passed to git push. A false value may override a value from a lower-priority config file. An explicit command-line flag always overrides this config option.
push.recurseSubmodules
Make sure all submodule commits used by the revisions to be pushed are available on a remote-tracking branch. If the value is check then Git will verify that all submodule commits that changed in the revisions to be pushed are available on at least one remote of the submodule. If any commits are missing, the push will be aborted and exit with non-zero status. If the value is on-demand then all submodules that changed in the revisions to be pushed will be pushed. If on-demand was not able to push all necessary revisions it will also be aborted and exit with non-zero status. If the value is no then default behavior of ignoring submodules when pushing is retained. You may override this configuration at time of push by specifying --recurse-submodules=check|on-demand|no.
rebase.stat
Whether to show a diffstat of what changed upstream since the last rebase. False by default.
rebase.autoSquash
If set to true enable --autosquash option by default.
rebase.autoStash
When set to true, automatically create a temporary stash before the operation begins, and apply it after the operation ends. This means that you can run rebase on a dirty worktree. However, use with care: the final stash application after a successful rebase might result in non-trivial conflicts. Defaults to false.
rebase.missingCommitsCheck
If set to "warn", git rebase -i will print a warning if some commits are removed (e.g. a line was deleted), however the rebase will still proceed. If set to "error", it will print the previous warning and stop the rebase, git rebase --edit-todo can then be used to correct the error. If set to "ignore", no checking is done. To drop a commit without warning or error, use the drop command in the todo-list. Defaults to "ignore".

rebase.instructionFormat A format string, as specified in Section G.3.68, “git-log(1)”, to be used for the instruction list during an interactive rebase. The format will automatically have the long commit hash prepended to the format.

receive.advertiseAtomic
By default, git-receive-pack will advertise the atomic push capability to its clients. If you don't want to this capability to be advertised, set this variable to false.
receive.autogc
By default, git-receive-pack will run "git-gc --auto" after receiving data from git-push and updating refs. You can stop it by setting this variable to false.
receive.certNonceSeed
By setting this variable to a string, git receive-pack will accept a git push --signed and verifies it by using a "nonce" protected by HMAC using this string as a secret key.
receive.certNonceSlop
When a git push --signed sent a push certificate with a "nonce" that was issued by a receive-pack serving the same repository within this many seconds, export the "nonce" found in the certificate to GIT_PUSH_CERT_NONCE to the hooks (instead of what the receive-pack asked the sending side to include). This may allow writing checks in pre-receive and post-receive a bit easier. Instead of checking GIT_PUSH_CERT_NONCE_SLOP environment variable that records by how many seconds the nonce is stale to decide if they want to accept the certificate, they only can check GIT_PUSH_CERT_NONCE_STATUS is OK.
receive.fsckObjects
If it is set to true, git-receive-pack will check all received objects. It will abort in the case of a malformed object or a broken link. The result of an abort are only dangling objects. Defaults to false. If not set, the value of transfer.fsckObjects is used instead.
receive.fsck.<msg-id>

When receive.fsckObjects is set to true, errors can be switched to warnings and vice versa by configuring the receive.fsck.<msg-id> setting where the <msg-id> is the fsck message ID and the value is one of error, warn or ignore. For convenience, fsck prefixes the error/warning with the message ID, e.g. "missingEmail: invalid author/committer line - missing email" means that setting receive.fsck.missingEmail = ignore will hide that issue.

This feature is intended to support working with legacy repositories which would not pass pushing when receive.fsckObjects = true, allowing the host to accept repositories with certain known issues but still catch other issues.

receive.fsck.skipList
The path to a sorted list of object names (i.e. one SHA-1 per line) that are known to be broken in a non-fatal way and should be ignored. This feature is useful when an established project should be accepted despite early commits containing errors that can be safely ignored such as invalid committer email addresses. Note: corrupt objects cannot be skipped with this setting.
receive.unpackLimit
If the number of objects received in a push is below this limit then the objects will be unpacked into loose object files. However if the number of received objects equals or exceeds this limit then the received pack will be stored as a pack, after adding any missing delta bases. Storing the pack from a push can make the push operation complete faster, especially on slow filesystems. If not set, the value of transfer.unpackLimit is used instead.
receive.denyDeletes
If set to true, git-receive-pack will deny a ref update that deletes the ref. Use this to prevent such a ref deletion via a push.
receive.denyDeleteCurrent
If set to true, git-receive-pack will deny a ref update that deletes the currently checked out branch of a non-bare repository.
receive.denyCurrentBranch

If set to true or "refuse", git-receive-pack will deny a ref update to the currently checked out branch of a non-bare repository. Such a push is potentially dangerous because it brings the HEAD out of sync with the index and working tree. If set to "warn", print a warning of such a push to stderr, but allow the push to proceed. If set to false or "ignore", allow such pushes with no message. Defaults to "refuse".

Another option is "updateInstead" which will update the working tree if pushing into the current branch. This option is intended for synchronizing working directories when one side is not easily accessible via interactive ssh (e.g. a live web site, hence the requirement that the working directory be clean). This mode also comes in handy when developing inside a VM to test and fix code on different Operating Systems.

By default, "updateInstead" will refuse the push if the working tree or the index have any difference from the HEAD, but the push-to-checkout hook can be used to customize this. See Section G.4.6, “githooks(5)”.

receive.denyNonFastForwards
If set to true, git-receive-pack will deny a ref update which is not a fast-forward. Use this to prevent such an update via a push, even if that push is forced. This configuration variable is set when initializing a shared repository.
receive.hideRefs
This variable is the same as transfer.hideRefs, but applies only to receive-pack (and so affects pushes, but not fetches). An attempt to update or delete a hidden ref by git push is rejected.
receive.updateServerInfo
If set to true, git-receive-pack will run git-update-server-info after receiving data from git-push and updating refs.
receive.shallowUpdate
If set to true, .git/shallow can be updated when new refs require new shallow roots. Otherwise those refs are rejected.
remote.pushDefault
The remote to push to by default. Overrides branch.<name>.remote for all branches, and is overridden by branch.<name>.pushRemote for specific branches.
remote.<name>.url
The URL of a remote repository. See Section G.3.46, “git-fetch(1)” or Section G.3.96, “git-push(1)”.
remote.<name>.pushurl
The push URL of a remote repository. See Section G.3.96, “git-push(1)”.
remote.<name>.proxy
For remotes that require curl (http, https and ftp), the URL to the proxy to use for that remote. Set to the empty string to disable proxying for that remote.
remote.<name>.proxyAuthMethod
For remotes that require curl (http, https and ftp), the method to use for authenticating against the proxy in use (probably set in remote.<name>.proxy). See http.proxyAuthMethod.
remote.<name>.fetch
The default set of "refspec" for Section G.3.46, “git-fetch(1)”. See Section G.3.46, “git-fetch(1)”.
remote.<name>.push
The default set of "refspec" for Section G.3.96, “git-push(1)”. See Section G.3.96, “git-push(1)”.
remote.<name>.mirror
If true, pushing to this remote will automatically behave as if the --mirror option was given on the command line.
remote.<name>.skipDefaultUpdate
If true, this remote will be skipped by default when updating using Section G.3.46, “git-fetch(1)” or the update subcommand of Section G.3.106, “git-remote(1)”.
remote.<name>.skipFetchAll
If true, this remote will be skipped by default when updating using Section G.3.46, “git-fetch(1)” or the update subcommand of Section G.3.106, “git-remote(1)”.
remote.<name>.receivepack
The default program to execute on the remote side when pushing. See option --receive-pack of Section G.3.96, “git-push(1)”.
remote.<name>.uploadpack
The default program to execute on the remote side when fetching. See option --upload-pack of Section G.3.45, “git-fetch-pack(1)”.
remote.<name>.tagOpt
Setting this value to --no-tags disables automatic tag following when fetching from remote <name>. Setting it to --tags will fetch every tag from remote <name>, even if they are not reachable from remote branch heads. Passing these flags directly to Section G.3.46, “git-fetch(1)” can override this setting. See options --tags and --no-tags of Section G.3.46, “git-fetch(1)”.
remote.<name>.vcs
Setting this to a value <vcs> will cause Git to interact with the remote with the git-remote-<vcs> helper.
remote.<name>.prune
When set to true, fetching from this remote by default will also remove any remote-tracking references that no longer exist on the remote (as if the --prune option was given on the command line). Overrides fetch.prune settings, if any.
remotes.<group>
The list of remotes which are fetched by "git remote update <group>". See Section G.3.106, “git-remote(1)”.
repack.useDeltaBaseOffset
By default, Section G.3.107, “git-repack(1)” creates packs that use delta-base offset. If you need to share your repository with Git older than version 1.4.4, either directly or via a dumb protocol such as http, then you need to set this option to "false" and repack. Access from old Git versions over the native protocol are unaffected by this option.
repack.packKeptObjects
If set to true, makes git repack act as if --pack-kept-objects was passed. See Section G.3.107, “git-repack(1)” for details. Defaults to false normally, but true if a bitmap index is being written (either via --write-bitmap-index or repack.writeBitmaps).
repack.writeBitmaps
When true, git will write a bitmap index when packing all objects to disk (e.g., when git repack -a is run). This index can speed up the "counting objects" phase of subsequent packs created for clones and fetches, at the cost of some disk space and extra time spent on the initial repack. Defaults to false.
rerere.autoUpdate
When set to true, git-rerere updates the index with the resulting contents after it cleanly resolves conflicts using previously recorded resolution. Defaults to false.
rerere.enabled
Activate recording of resolved conflicts, so that identical conflict hunks can be resolved automatically, should they be encountered again. By default, Section G.3.110, “git-rerere(1)” is enabled if there is an rr-cache directory under the $GIT_DIR, e.g. if "rerere" was previously used in the repository.
sendemail.identity
A configuration identity. When given, causes values in the sendemail.<identity> subsection to take precedence over values in the sendemail section. The default identity is the value of sendemail.identity.
sendemail.smtpEncryption
See Section G.3.116, “git-send-email(1)” for description. Note that this setting is not subject to the identity mechanism.
sendemail.smtpssl (deprecated)
Deprecated alias for sendemail.smtpEncryption = ssl.
sendemail.smtpsslcertpath
Path to ca-certificates (either a directory or a single file). Set it to an empty string to disable certificate verification.
sendemail.<identity>.*
Identity-specific versions of the sendemail.* parameters found below, taking precedence over those when the this identity is selected, through command-line or sendemail.identity.
sendemail.aliasesFile , sendemail.aliasFileType , sendemail.annotate , sendemail.bcc , sendemail.cc , sendemail.ccCmd , sendemail.chainReplyTo , sendemail.confirm , sendemail.envelopeSender , sendemail.from , sendemail.multiEdit , sendemail.signedoffbycc , sendemail.smtpPass , sendemail.suppresscc , sendemail.suppressFrom , sendemail.to , sendemail.smtpDomain , sendemail.smtpServer , sendemail.smtpServerPort , sendemail.smtpServerOption , sendemail.smtpUser , sendemail.thread , sendemail.transferEncoding , sendemail.validate , sendemail.xmailer
See Section G.3.116, “git-send-email(1)” for description.
sendemail.signedoffcc (deprecated)
Deprecated alias for sendemail.signedoffbycc.
showbranch.default
The default set of branches for Section G.3.123, “git-show-branch(1)”. See Section G.3.123, “git-show-branch(1)”.
status.relativePaths
By default, Section G.3.129, “git-status(1)” shows paths relative to the current directory. Setting this variable to false shows paths relative to the repository root (this was the default for Git prior to v1.5.4).
status.short
Set to true to enable --short by default in Section G.3.129, “git-status(1)”. The option --no-short takes precedence over this variable.
status.branch
Set to true to enable --branch by default in Section G.3.129, “git-status(1)”. The option --no-branch takes precedence over this variable.
status.displayCommentPrefix
If set to true, Section G.3.129, “git-status(1)” will insert a comment prefix before each output line (starting with core.commentChar, i.e. # by default). This was the behavior of Section G.3.129, “git-status(1)” in Git 1.8.4 and previous. Defaults to false.
status.showUntrackedFiles

By default, Section G.3.129, “git-status(1)” and Section G.3.26, “git-commit(1)” show files which are not currently tracked by Git. Directories which contain only untracked files, are shown with the directory name only. Showing untracked files means that Git needs to lstat() all the files in the whole repository, which might be slow on some systems. So, this variable controls how the commands displays the untracked files. Possible values are:

  • no - Show no untracked files.
  • normal - Show untracked files and directories.
  • all - Show also individual files in untracked directories.

If this variable is not specified, it defaults to normal. This variable can be overridden with the -u|--untracked-files option of Section G.3.129, “git-status(1)” and Section G.3.26, “git-commit(1)”.

status.submoduleSummary
Defaults to false. If this is set to a non zero number or true (identical to -1 or an unlimited number), the submodule summary will be enabled and a summary of commits for modified submodules will be shown (see --summary-limit option of Section G.3.131, “git-submodule(1)”). Please note that the summary output command will be suppressed for all submodules when diff.ignoreSubmodules is set to all or only for those submodules where submodule.<name>.ignore=all. The only exception to that rule is that status and commit will show staged submodule changes. To also view the summary for ignored submodules you can either use the --ignore-submodules=dirty command-line option or the git submodule summary command, which shows a similar output but does not honor these settings.
stash.showPatch
If this is set to true, the git stash show command without an option will show the stash in patch form. Defaults to false. See description of show command in Section G.3.128, “git-stash(1)”.
stash.showStat
If this is set to true, the git stash show command without an option will show diffstat of the stash. Defaults to true. See description of show command in Section G.3.128, “git-stash(1)”.
submodule.<name>.path , submodule.<name>.url
The path within this project and URL for a submodule. These variables are initially populated by git submodule init. See Section G.3.131, “git-submodule(1)” and Section G.4.8, “gitmodules(5)” for details.
submodule.<name>.update
The default update procedure for a submodule. This variable is populated by git submodule init from the Section G.4.8, “gitmodules(5)” file. See description of update command in Section G.3.131, “git-submodule(1)”.
submodule.<name>.branch
The remote branch name for a submodule, used by git submodule update --remote. Set this option to override the value found in the .gitmodules file. See Section G.3.131, “git-submodule(1)” and Section G.4.8, “gitmodules(5)” for details.
submodule.<name>.fetchRecurseSubmodules
This option can be used to control recursive fetching of this submodule. It can be overridden by using the --[no-]recurse-submodules command-line option to "git fetch" and "git pull". This setting will override that from in the Section G.4.8, “gitmodules(5)” file.
submodule.<name>.ignore
Defines under what circumstances "git status" and the diff family show a submodule as modified. When set to "all", it will never be considered modified (but it will nonetheless show up in the output of status and commit when it has been staged), "dirty" will ignore all changes to the submodules work tree and takes only differences between the HEAD of the submodule and the commit recorded in the superproject into account. "untracked" will additionally let submodules with modified tracked files in their work tree show up. Using "none" (the default when this option is not set) also shows submodules that have untracked files in their work tree as changed. This setting overrides any setting made in .gitmodules for this submodule, both settings can be overridden on the command line by using the "--ignore-submodules" option. The git submodule commands are not affected by this setting.
submodule.fetchJobs
Specifies how many submodules are fetched/cloned at the same time. A positive integer allows up to that number of submodules fetched in parallel. A value of 0 will give some reasonable default. If unset, it defaults to 1.
tag.forceSignAnnotated
A boolean to specify whether annotated tags created should be GPG signed. If --annotate is specified on the command line, it takes precedence over this option.
tag.sort
This variable controls the sort ordering of tags when displayed by Section G.3.134, “git-tag(1)”. Without the "--sort=<value>" option provided, the value of this variable will be used as the default.
tar.umask
This variable can be used to restrict the permission bits of tar archive entries. The default is 0002, which turns off the world write bit. The special value "user" indicates that the archiving user's umask will be used instead. See umask(2) and Section G.3.7, “git-archive(1)”.
transfer.fsckObjects
When fetch.fsckObjects or receive.fsckObjects are not set, the value of this variable is used instead. Defaults to false.
transfer.hideRefs

String(s) receive-pack and upload-pack use to decide which refs to omit from their initial advertisements. Use more than one definition to specify multiple prefix strings. A ref that is under the hierarchies listed in the value of this variable is excluded, and is hidden when responding to git push or git fetch. See receive.hideRefs and uploadpack.hideRefs for program-specific versions of this config.

You may also include a ! in front of the ref name to negate the entry, explicitly exposing it, even if an earlier entry marked it as hidden. If you have multiple hideRefs values, later entries override earlier ones (and entries in more-specific config files override less-specific ones).

If a namespace is in use, the namespace prefix is stripped from each reference before it is matched against transfer.hiderefs patterns. For example, if refs/heads/master is specified in transfer.hideRefs and the current namespace is foo, then refs/namespaces/foo/refs/heads/master is omitted from the advertisements but refs/heads/master and refs/namespaces/bar/refs/heads/master are still advertised as so-called "have" lines. In order to match refs before stripping, add a ^ in front of the ref name. If you combine ! and ^, ! must be specified first.

transfer.unpackLimit
When fetch.unpackLimit or receive.unpackLimit are not set, the value of this variable is used instead. The default value is 100.
uploadarchive.allowUnreachable
If true, allow clients to use git archive --remote to request any tree, whether reachable from the ref tips or not. See the discussion in the SECURITY section of Section G.3.140, “git-upload-archive(1)” for more details. Defaults to false.
uploadpack.hideRefs
This variable is the same as transfer.hideRefs, but applies only to upload-pack (and so affects only fetches, not pushes). An attempt to fetch a hidden ref by git fetch will fail. See also uploadpack.allowTipSHA1InWant.
uploadpack.allowTipSHA1InWant
When uploadpack.hideRefs is in effect, allow upload-pack to accept a fetch request that asks for an object at the tip of a hidden ref (by default, such a request is rejected). see also uploadpack.hideRefs.
uploadpack.allowReachableSHA1InWant
Allow upload-pack to accept a fetch request that asks for an object that is reachable from any ref tip. However, note that calculating object reachability is computationally expensive. Defaults to false.
uploadpack.keepAlive
When upload-pack has started pack-objects, there may be a quiet period while pack-objects prepares the pack. Normally it would output progress information, but if --quiet was used for the fetch, pack-objects will output nothing at all until the pack data begins. Some clients and networks may consider the server to be hung and give up. Setting this option instructs upload-pack to send an empty keepalive packet every uploadpack.keepAlive seconds. Setting this option to 0 disables keepalive packets entirely. The default is 5 seconds.
url.<base>.insteadOf
Any URL that starts with this value will be rewritten to start, instead, with <base>. In cases where some site serves a large number of repositories, and serves them with multiple access methods, and some users need to use different access methods, this feature allows people to specify any of the equivalent URLs and have Git automatically rewrite the URL to the best alternative for the particular user, even for a never-before-seen repository on the site. When more than one insteadOf strings match a given URL, the longest match is used.
url.<base>.pushInsteadOf
Any URL that starts with this value will not be pushed to; instead, it will be rewritten to start with <base>, and the resulting URL will be pushed to. In cases where some site serves a large number of repositories, and serves them with multiple access methods, some of which do not allow push, this feature allows people to specify a pull-only URL and have Git automatically use an appropriate URL to push, even for a never-before-seen repository on the site. When more than one pushInsteadOf strings match a given URL, the longest match is used. If a remote has an explicit pushurl, Git will ignore this setting for that remote.
user.email
Your email address to be recorded in any newly created commits. Can be overridden by the GIT_AUTHOR_EMAIL, GIT_COMMITTER_EMAIL, and EMAIL environment variables. See Section G.3.25, “git-commit-tree(1)”.
user.name
Your full name to be recorded in any newly created commits. Can be overridden by the GIT_AUTHOR_NAME and GIT_COMMITTER_NAME environment variables. See Section G.3.25, “git-commit-tree(1)”.
user.useConfigOnly
Instruct Git to avoid trying to guess defaults for user.email and user.name, and instead retrieve the values only from the configuration. For example, if you have multiple email addresses and would like to use a different one for each repository, then with this configuration option set to true in the global config along with a name, Git will prompt you to set up an email before making new commits in a newly cloned repository. Defaults to false.
user.signingKey
If Section G.3.134, “git-tag(1)” or Section G.3.26, “git-commit(1)” is not selecting the key you want it to automatically when creating a signed tag or commit, you can override the default selection with this variable. This option is passed unchanged to gpg's --local-user parameter, so you may specify a key using any method that gpg supports.
versionsort.prereleaseSuffix

When version sort is used in Section G.3.134, “git-tag(1)”, prerelease tags (e.g. "1.0-rc1") may appear after the main release "1.0". By specifying the suffix "-rc" in this variable, "1.0-rc1" will appear before "1.0".

This variable can be specified multiple times, once per suffix. The order of suffixes in the config file determines the sorting order (e.g. if "-pre" appears before "-rc" in the config file then 1.0-preXX is sorted before 1.0-rcXX). The sorting order between different suffixes is undefined if they are in multiple config files.

web.browser
Specify a web browser that may be used by some commands. Currently only Section G.3.66, “git-instaweb(1)” and Section G.3.58, “git-help(1)” may use it.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.28. git-count-objects(1)

NAME

git-count-objects - Count unpacked number of objects and their disk consumption

SYNOPSIS

git count-objects [-v] [-H | --human-readable]

DESCRIPTION

This counts the number of unpacked object files and disk space consumed by them, to help you decide when it is a good time to repack.

OPTIONS

-v , --verbose

Report in more detail:

count: the number of loose objects

size: disk space consumed by loose objects, in KiB (unless -H is specified)

in-pack: the number of in-pack objects

size-pack: disk space consumed by the packs, in KiB (unless -H is specified)

prune-packable: the number of loose objects that are also present in the packs. These objects could be pruned using git prune-packed.

garbage: the number of files in object database that are neither valid loose objects nor valid packs

size-garbage: disk space consumed by garbage files, in KiB (unless -H is specified)

-H , --human-readable
Print sizes in human readable format

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.29. git-credential(1)

NAME

git-credential - Retrieve and store user credentials

SYNOPSIS

git credential <fill|approve|reject>

DESCRIPTION

Git has an internal interface for storing and retrieving credentials from system-specific helpers, as well as prompting the user for usernames and passwords. The git-credential command exposes this interface to scripts which may want to retrieve, store, or prompt for credentials in the same manner as Git. The design of this scriptable interface models the internal C API; see the Git credential API for more background on the concepts.

git-credential takes an "action" option on the command-line (one of fill, approve, or reject) and reads a credential description on stdin (see INPUT/OUTPUT FORMAT).

If the action is fill, git-credential will attempt to add "username" and "password" attributes to the description by reading config files, by contacting any configured credential helpers, or by prompting the user. The username and password attributes of the credential description are then printed to stdout together with the attributes already provided.

If the action is approve, git-credential will send the description to any configured credential helpers, which may store the credential for later use.

If the action is reject, git-credential will send the description to any configured credential helpers, which may erase any stored credential matching the description.

If the action is approve or reject, no output should be emitted.

TYPICAL USE OF GIT CREDENTIAL

An application using git-credential will typically use git credential following these steps:

  1. Generate a credential description based on the context.

    For example, if we want a password for https://example.com/foo.git, we might generate the following credential description (don't forget the blank line at the end; it tells git credential that the application finished feeding all the information it has):

    protocol=https
    host=example.com
    path=foo.git
  2. Ask git-credential to give us a username and password for this description. This is done by running git credential fill, feeding the description from step (1) to its standard input. The complete credential description (including the credential per se, i.e. the login and password) will be produced on standard output, like:

    protocol=https
    host=example.com
    username=bob
    password=secr3t

    In most cases, this means the attributes given in the input will be repeated in the output, but Git may also modify the credential description, for example by removing the path attribute when the protocol is HTTP(s) and credential.useHttpPath is false.

    If the git credential knew about the password, this step may not have involved the user actually typing this password (the user may have typed a password to unlock the keychain instead, or no user interaction was done if the keychain was already unlocked) before it returned password=secr3t.

  3. Use the credential (e.g., access the URL with the username and password from step (2)), and see if it's accepted.
  4. Report on the success or failure of the password. If the credential allowed the operation to complete successfully, then it can be marked with an "approve" action to tell git credential to reuse it in its next invocation. If the credential was rejected during the operation, use the "reject" action so that git credential will ask for a new password in its next invocation. In either case, git credential should be fed with the credential description obtained from step (2) (which also contain the ones provided in step (1)).

INPUT/OUTPUT FORMAT

git credential reads and/or writes (depending on the action used) credential information in its standard input/output. This information can correspond either to keys for which git credential will obtain the login/password information (e.g. host, protocol, path), or to the actual credential data to be obtained (login/password).

The credential is split into a set of named attributes, with one attribute per line. Each attribute is specified by a key-value pair, separated by an = (equals) sign, followed by a newline. The key may contain any bytes except =, newline, or NUL. The value may contain any bytes except newline or NUL. In both cases, all bytes are treated as-is (i.e., there is no quoting, and one cannot transmit a value with newline or NUL in it). The list of attributes is terminated by a blank line or end-of-file. Git understands the following attributes:

protocol
The protocol over which the credential will be used (e.g., https).
host
The remote hostname for a network credential.
path
The path with which the credential will be used. E.g., for accessing a remote https repository, this will be the repository's path on the server.
username
The credential's username, if we already have one (e.g., from a URL, from the user, or from a previously run helper).
password
The credential's password, if we are asking it to be stored.
url
When this special attribute is read by git credential, the value is parsed as a URL and treated as if its constituent parts were read (e.g., url=https://example.com would behave as if protocol=https and host=example.com had been provided). This can help callers avoid parsing URLs themselves. Note that any components which are missing from the URL (e.g., there is no username in the example above) will be set to empty; if you want to provide a URL and override some attributes, provide the URL attribute first, followed by any overrides.

G.3.30. git-credential-cache--daemon(1)

NAME

git-credential-cache--daemon - Temporarily store user credentials in memory

SYNOPSIS

git credential-cache--daemon [--debug] <socket>

DESCRIPTION

[Note] Note

You probably don't want to invoke this command yourself; it is started automatically when you use Section G.3.31, “git-credential-cache(1)”.

This command listens on the Unix domain socket specified by <socket> for git-credential-cache clients. Clients may store and retrieve credentials. Each credential is held for a timeout specified by the client; once no credentials are held, the daemon exits.

If the --debug option is specified, the daemon does not close its stderr stream, and may output extra diagnostics to it even after it has begun listening for clients.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.31. git-credential-cache(1)

NAME

git-credential-cache - Helper to temporarily store passwords in memory

SYNOPSIS

git config credential.helper 'cache [options]'

DESCRIPTION

This command caches credentials in memory for use by future Git programs. The stored credentials never touch the disk, and are forgotten after a configurable timeout. The cache is accessible over a Unix domain socket, restricted to the current user by filesystem permissions.

You probably don't want to invoke this command directly; it is meant to be used as a credential helper by other parts of Git. See Section G.4.3, “gitcredentials(7)” or EXAMPLES below.

OPTIONS

--timeout <seconds>
Number of seconds to cache credentials (default: 900).
--socket <path>
Use <path> to contact a running cache daemon (or start a new cache daemon if one is not started). Defaults to ~/.git-credential-cache/socket. If your home directory is on a network-mounted filesystem, you may need to change this to a local filesystem. You must specify an absolute path.

CONTROLLING THE DAEMON

If you would like the daemon to exit early, forgetting all cached credentials before their timeout, you can issue an exit action:

git credential-cache exit

EXAMPLES

The point of this helper is to reduce the number of times you must type your username or password. For example:

$ git config credential.helper cache
$ git push http://example.com/repo.git
Username: <type your username>
Password: <type your password>

[work for 5 more minutes]
$ git push http://example.com/repo.git
[your credentials are used automatically]

You can provide options via the credential.helper configuration variable (this example drops the cache time to 5 minutes):

$ git config credential.helper 'cache --timeout=300'

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.32. git-credential-store(1)

NAME

git-credential-store - Helper to store credentials on disk

SYNOPSIS

git config credential.helper 'store [options]'

DESCRIPTION

[Note] Note

Using this helper will store your passwords unencrypted on disk, protected only by filesystem permissions. If this is not an acceptable security tradeoff, try Section G.3.31, “git-credential-cache(1)”, or find a helper that integrates with secure storage provided by your operating system.

This command stores credentials indefinitely on disk for use by future Git programs.

You probably don't want to invoke this command directly; it is meant to be used as a credential helper by other parts of git. See Section G.4.3, “gitcredentials(7)” or EXAMPLES below.

OPTIONS

--file=<path>
Use <path> to lookup and store credentials. The file will have its filesystem permissions set to prevent other users on the system from reading it, but will not be encrypted or otherwise protected. If not specified, credentials will be searched for from ~/.git-credentials and $XDG_CONFIG_HOME/git/credentials, and credentials will be written to ~/.git-credentials if it exists, or $XDG_CONFIG_HOME/git/credentials if it exists and the former does not. See also the section called “FILES”.

FILES

If not set explicitly with --file, there are two files where git-credential-store will search for credentials in order of precedence:

~/.git-credentials
User-specific credentials file.
$XDG_CONFIG_HOME/git/credentials
Second user-specific credentials file. If $XDG_CONFIG_HOME is not set or empty, $HOME/.config/git/credentials will be used. Any credentials stored in this file will not be used if ~/.git-credentials has a matching credential as well. It is a good idea not to create this file if you sometimes use older versions of Git that do not support it.

For credential lookups, the files are read in the order given above, with the first matching credential found taking precedence over credentials found in files further down the list.

Credential storage will by default write to the first existing file in the list. If none of these files exist, ~/.git-credentials will be created and written to.

When erasing credentials, matching credentials will be erased from all files.

EXAMPLES

The point of this helper is to reduce the number of times you must type your username or password. For example:

$ git config credential.helper store
$ git push http://example.com/repo.git
Username: <type your username>
Password: <type your password>

[several days later]
$ git push http://example.com/repo.git
[your credentials are used automatically]

STORAGE FORMAT

The .git-credentials file is stored in plaintext. Each credential is stored on its own line as a URL like:

https://user:[email protected]

When Git needs authentication for a particular URL context, credential-store will consider that context a pattern to match against each entry in the credentials file. If the protocol, hostname, and username (if we already have one) match, then the password is returned to Git. See the discussion of configuration in Section G.4.3, “gitcredentials(7)” for more information.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.33. git-cvsexportcommit(1)

NAME

git-cvsexportcommit - Export a single commit to a CVS checkout

SYNOPSIS

git cvsexportcommit [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot]
        [-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID

DESCRIPTION

Exports a commit from Git to a CVS checkout, making it easier to merge patches from a Git repository into a CVS repository.

Specify the name of a CVS checkout using the -w switch or execute it from the root of the CVS working copy. In the latter case GIT_DIR must be defined. See examples below.

It does its best to do the safe thing, it will check that the files are unchanged and up to date in the CVS checkout, and it will not autocommit by default.

Supports file additions, removals, and commits that affect binary files.

If the commit is a merge commit, you must tell git cvsexportcommit what parent the changeset should be done against.

OPTIONS

-c
Commit automatically if the patch applied cleanly. It will not commit if any hunks fail to apply or there were other problems.
-p
Be pedantic (paranoid) when applying patches. Invokes patch with --fuzz=0
-a
Add authorship information. Adds Author line, and Committer (if different from Author) to the message.
-d
Set an alternative CVSROOT to use. This corresponds to the CVS -d parameter. Usually users will not want to set this, except if using CVS in an asymmetric fashion.
-f
Force the merge even if the files are not up to date.
-P
Force the parent commit, even if it is not a direct parent.
-m
Prepend the commit message with the provided prefix. Useful for patch series and the like.
-u
Update affected files from CVS repository before attempting export.
-k
Reverse CVS keyword expansion (e.g. $Revision: 1.2.3.4$ becomes $Revision$) in working CVS checkout before applying patch.
-w
Specify the location of the CVS checkout to use for the export. This option does not require GIT_DIR to be set before execution if the current directory is within a Git repository. The default is the value of cvsexportcommit.cvsdir.
-W
Tell cvsexportcommit that the current working directory is not only a Git checkout, but also the CVS checkout. Therefore, Git will reset the working directory to the parent commit before proceeding.
-v
Verbose.

CONFIGURATION

cvsexportcommit.cvsdir
The default location of the CVS checkout to use for the export.

EXAMPLES

Merge one patch into CVS
$ export GIT_DIR=~/project/.git
$ cd ~/project_cvs_checkout
$ git cvsexportcommit -v <commit-sha1>
$ cvs commit -F .msg <files>
Merge one patch into CVS (-c and -w options). The working directory is within the Git Repo
        $ git cvsexportcommit -v -c -w ~/project_cvs_checkout <commit-sha1>
Merge pending patches into CVS automatically -- only if you really know what you are doing
$ export GIT_DIR=~/project/.git
$ cd ~/project_cvs_checkout
$ git cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git cvsexportcommit -c -p -v

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.34. git-cvsimport(1)

NAME

git-cvsimport - Salvage your data out of another SCM people love to hate

SYNOPSIS

git cvsimport [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>]
              [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>]
              [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>]
              [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>]
              [-r <remote>] [-R] [<CVS_module>]

DESCRIPTION

WARNING: git cvsimport uses cvsps version 2, which is considered deprecated; it does not work with cvsps version 3 and later. If you are performing a one-shot import of a CVS repository consider using http://cvs2svn.tigris.org/cvs2git.html[cvs2git] or https://github.com/BartMassey/parsecvs[parsecvs].

Imports a CVS repository into Git. It will either create a new repository, or incrementally import into an existing one.

Splitting the CVS log into patch sets is done by cvsps. At least version 2.1 is required.

WARNING: for certain situations the import leads to incorrect results. Please see the section ISSUES for further reference.

You should never do any work of your own on the branches that are created by git cvsimport. By default initial import will create and populate a "master" branch from the CVS repository's main branch which you're free to work with; after that, you need to git merge incremental imports, or any CVS branches, yourself. It is advisable to specify a named remote via -r to separate and protect the incoming branches.

If you intend to set up a shared public repository that all developers can read/write, or if you want to use Section G.3.35, “git-cvsserver(1)”, then you probably want to make a bare clone of the imported repository, and use the clone as the shared repository. See Section G.2.4, “gitcvs-migration(7)”.

OPTIONS

-v
Verbosity: let cvsimport report what it is doing.
-d <CVSROOT>
The root of the CVS archive. May be local (a simple path) or remote; currently, only the :local:, :ext: and :pserver: access methods are supported. If not given, git cvsimport will try to read it from CVS/Root. If no such file exists, it checks for the CVSROOT environment variable.
<CVS_module>
The CVS module you want to import. Relative to <CVSROOT>. If not given, git cvsimport tries to read it from CVS/Repository.
-C <target-dir>
The Git repository to import to. If the directory doesn't exist, it will be created. Default is the current directory.
-r <remote>
The Git remote to import this CVS repository into. Moves all CVS branches into remotes/<remote>/<branch> akin to the way git clone uses origin by default.
-o <branch-for-HEAD>

When no remote is specified (via -r) the HEAD branch from CVS is imported to the origin branch within the Git repository, as HEAD already has a special meaning for Git. When a remote is specified the HEAD branch is named remotes/<remote>/master mirroring git clone behaviour. Use this option if you want to import into a different branch.

Use -o master for continuing an import that was initially done by the old cvs2git tool.

-i
Import-only: don't perform a checkout after importing. This option ensures the working directory and index remain untouched and will not create them if they do not exist.
-k
Kill keywords: will extract files with -kk from the CVS archive to avoid noisy changesets. Highly recommended, but off by default to preserve compatibility with early imported trees.
-u
Convert underscores in tag and branch names to dots.
-s <subst>
Substitute the character "/" in branch names with <subst>
-p <options-for-cvsps>

Additional options for cvsps. The options -u and -A are implicit and should not be used here.

If you need to pass multiple options, separate them with a comma.

-z <fuzz>
Pass the timestamp fuzz factor to cvsps, in seconds. If unset, cvsps defaults to 300s.
-P <cvsps-output-file>
Instead of calling cvsps, read the provided cvsps output file. Useful for debugging or when cvsps is being handled outside cvsimport.
-m
Attempt to detect merges based on the commit message. This option will enable default regexes that try to capture the source branch name from the commit message.
-M <regex>

Attempt to detect merges based on the commit message with a custom regex. It can be used with -m to enable the default regexes as well. You must escape forward slashes.

The regex must capture the source branch name in $1.

This option can be used several times to provide several detection regexes.

-S <regex>
Skip paths matching the regex.
-a
Import all commits, including recent ones. cvsimport by default skips commits that have a timestamp less than 10 minutes ago.
-L <limit>
Limit the number of commits imported. Workaround for cases where cvsimport leaks memory.
-A <author-conv-file>

CVS by default uses the Unix username when writing its commit logs. Using this option and an author-conv-file maps the name recorded in CVS to author name, e-mail and optional time zone:

        exon=Andreas Ericsson <[email protected]>
        spawn=Simon Pawn <[email protected]> America/Chicago

git cvsimport will make it appear as those authors had their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly all along. If a time zone is specified, GIT_AUTHOR_DATE will have the corresponding offset applied.

For convenience, this data is saved to $GIT_DIR/cvs-authors each time the -A option is provided and read from that same file each time git cvsimport is run.

It is not recommended to use this feature if you intend to export changes back to CVS again later with git cvsexportcommit.

-R

Generate a $GIT_DIR/cvs-revisions file containing a mapping from CVS revision numbers to newly-created Git commit IDs. The generated file will contain one line for each (filename, revision) pair imported; each line will look like

src/widget.c 1.1 1d862f173cdc7325b6fa6d2ae1cfd61fd1b512b7

The revision data is appended to the file if it already exists, for use when doing incremental imports.

This option may be useful if you have CVS revision numbers stored in commit messages, bug-tracking systems, email archives, and the like.

-h
Print a short usage message and exit.

OUTPUT

If -v is specified, the script reports what it is doing.

Otherwise, success is indicated the Unix way, i.e. by simply exiting with a zero exit status.

ISSUES

Problems related to timestamps:

  • If timestamps of commits in the CVS repository are not stable enough to be used for ordering commits changes may show up in the wrong order.
  • If any files were ever "cvs import"ed more than once (e.g., import of more than one vendor release) the HEAD contains the wrong content.
  • If the timestamp order of different files cross the revision order within the commit matching time window the order of commits may be wrong.

Problems related to branches:

  • Branches on which no commits have been made are not imported.
  • All files from the branching point are added to a branch even if never added in CVS.
  • This applies to files added to the source branch after a daughter branch was created: if previously no commit was made on the daughter branch they will erroneously be added to the daughter branch in git.

Problems related to tags:

  • Multiple tags on the same revision are not imported.

If you suspect that any of these issues may apply to the repository you want to import, consider using cvs2git:

  • cvs2git (part of cvs2svn), http://subversion.apache.org/

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.35. git-cvsserver(1)

NAME

git-cvsserver - A CVS server emulator for Git

SYNOPSIS

SSH:

export CVS_SERVER="git cvsserver"
cvs -d :ext:[email protected]/path/repo.git co <HEAD_name>

pserver (/etc/inetd.conf):

cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver

Usage:

git-cvsserver [options] [pserver|server] [<directory> …]

OPTIONS

All these options obviously only make sense if enforced by the server side. They have been implemented to resemble the Section G.3.36, “git-daemon(1)” options as closely as possible.

--base-path <path>
Prepend path to requested CVSROOT
--strict-paths
Don't allow recursing into subdirectories
--export-all
Don't check for gitcvs.enabled in config. You also have to specify a list of allowed directories (see below) if you want to use this option.
-V , --version
Print version information and exit
-h , -H , --help
Print usage information and exit
<directory>
You can specify a list of allowed directories. If no directories are given, all are allowed. This is an additional restriction, gitcvs access still needs to be enabled by the gitcvs.enabled config option unless --export-all was given, too.

DESCRIPTION

This application is a CVS emulation layer for Git.

It is highly functional. However, not all methods are implemented, and for those methods that are implemented, not all switches are implemented.

Testing has been done using both the CLI CVS client, and the Eclipse CVS plugin. Most functionality works fine with both of these clients.

LIMITATIONS

CVS clients cannot tag, branch or perform Git merges.

git-cvsserver maps Git branches to CVS modules. This is very different from what most CVS users would expect since in CVS modules usually represent one or more directories.

INSTALLATION

  1. If you are going to offer CVS access via pserver, add a line in /etc/inetd.conf like

       cvspserver stream tcp nowait nobody git-cvsserver pserver

    Note: Some inetd servers let you specify the name of the executable independently of the value of argv[0] (i.e. the name the program assumes it was executed with). In this case the correct line in /etc/inetd.conf looks like

       cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver

    Only anonymous access is provided by pserve by default. To commit you will have to create pserver accounts, simply add a gitcvs.authdb setting in the config file of the repositories you want the cvsserver to allow writes to, for example:

       [gitcvs]
            authdb = /etc/cvsserver/passwd

    The format of these files is username followed by the encrypted password, for example:

       myuser:$1Oyx5r9mdGZ2
       myuser:$1$BA)@$vbnMJMDym7tA32AamXrm./

    You can use the htpasswd facility that comes with Apache to make these files, but Apache's MD5 crypt method differs from the one used by most C library's crypt() function, so don't use the -m option.

    Alternatively you can produce the password with perl's crypt() operator:

       perl -e 'my ($user, $pass) = @ARGV; printf "%s:%s\n", $user, crypt($user, $pass)' $USER password

    Then provide your password via the pserver method, for example:

       cvs -d:pserver:someuser:somepassword <at> server/path/repo.git co <HEAD_name>

    No special setup is needed for SSH access, other than having Git tools in the PATH. If you have clients that do not accept the CVS_SERVER environment variable, you can rename git-cvsserver to cvs.

    Note: Newer CVS versions (>= 1.12.11) also support specifying CVS_SERVER directly in CVSROOT like

    cvs -d ":ext;CVS_SERVER=git cvsserver:[email protected]/path/repo.git" co <HEAD_name>

    This has the advantage that it will be saved in your CVS/Root files and you don't need to worry about always setting the correct environment variable. SSH users restricted to git-shell don't need to override the default with CVS_SERVER (and shouldn't) as git-shell understands cvs to mean git-cvsserver and pretends that the other end runs the real cvs better.

  2. For each repo that you want accessible from CVS you need to edit config in the repo and add the following section.

       [gitcvs]
            enabled=1
            # optional for debugging
            logFile=/path/to/logfile

    Note: you need to ensure each user that is going to invoke git-cvsserver has write access to the log file and to the database (see Database Backend. If you want to offer write access over SSH, the users of course also need write access to the Git repository itself.

    You also need to ensure that each repository is "bare" (without a Git index file) for cvs commit to work. See Section G.2.4, “gitcvs-migration(7)”.

    All configuration variables can also be overridden for a specific method of access. Valid method names are "ext" (for SSH access) and "pserver". The following example configuration would disable pserver access while still allowing access over SSH.

       [gitcvs]
            enabled=0
    
       [gitcvs "ext"]
            enabled=1
  3. If you didn't specify the CVSROOT/CVS_SERVER directly in the checkout command, automatically saving it in your CVS/Root files, then you need to set them explicitly in your environment. CVSROOT should be set as per normal, but the directory should point at the appropriate Git repo. As above, for SSH clients not restricted to git-shell, CVS_SERVER should be set to git-cvsserver.

         export CVSROOT=:ext:[email protected]:/var/git/project.git
         export CVS_SERVER="git cvsserver"
  4. For SSH clients that will make commits, make sure their server-side .ssh/environment files (or .bashrc, etc., according to their specific shell) export appropriate values for GIT_AUTHOR_NAME, GIT_AUTHOR_EMAIL, GIT_COMMITTER_NAME, and GIT_COMMITTER_EMAIL. For SSH clients whose login shell is bash, .bashrc may be a reasonable alternative.
  5. Clients should now be able to check out the project. Use the CVS module name to indicate what Git head you want to check out. This also sets the name of your newly checked-out directory, unless you tell it otherwise with -d <dir_name>. For example, this checks out master branch to the project-master directory:

         cvs co -d project-master master

Database Backend

git-cvsserver uses one database per Git head (i.e. CVS module) to store information about the repository to maintain consistent CVS revision numbers. The database needs to be updated (i.e. written to) after every commit.

If the commit is done directly by using git (as opposed to using git-cvsserver) the update will need to happen on the next repository access by git-cvsserver, independent of access method and requested operation.

That means that even if you offer only read access (e.g. by using the pserver method), git-cvsserver should have write access to the database to work reliably (otherwise you need to make sure that the database is up-to-date any time git-cvsserver is executed).

By default it uses SQLite databases in the Git directory, named gitcvs.<module_name>.sqlite. Note that the SQLite backend creates temporary files in the same directory as the database file on write so it might not be enough to grant the users using git-cvsserver write access to the database file without granting them write access to the directory, too.

The database can not be reliably regenerated in a consistent form after the branch it is tracking has changed. Example: For merged branches, git-cvsserver only tracks one branch of development, and after a git merge an incrementally updated database may track a different branch than a database regenerated from scratch, causing inconsistent CVS revision numbers. git-cvsserver has no way of knowing which branch it would have picked if it had been run incrementally pre-merge. So if you have to fully or partially (from old backup) regenerate the database, you should be suspicious of pre-existing CVS sandboxes.

You can configure the database backend with the following configuration variables:

1. Configuring database backend

git-cvsserver uses the Perl DBI module. Please also read its documentation if changing these variables, especially about DBI->connect().

gitcvs.dbName
Database name. The exact meaning depends on the selected database driver, for SQLite this is a filename. Supports variable substitution (see below). May not contain semicolons (;). Default: %Ggitcvs.%m.sqlite
gitcvs.dbDriver
Used DBI driver. You can specify any available driver for this here, but it might not work. cvsserver is tested with DBD::SQLite, reported to work with DBD::Pg, and reported not to work with DBD::mysql. Please regard this as an experimental feature. May not contain colons (:). Default: SQLite
gitcvs.dbuser
Database user. Only useful if setting dbDriver, since SQLite has no concept of database users. Supports variable substitution (see below).
gitcvs.dbPass
Database password. Only useful if setting dbDriver, since SQLite has no concept of database passwords.
gitcvs.dbTableNamePrefix
Database table name prefix. Supports variable substitution (see below). Any non-alphabetic characters will be replaced with underscores.

All variables can also be set per access method, see above.

1.1. Variable substitution

In dbDriver and dbUser you can use the following variables:

%G
Git directory name
%g
Git directory name, where all characters except for alpha-numeric ones, ., and - are replaced with _ (this should make it easier to use the directory name in a filename if wanted)
%m
CVS module/Git head name
%a
access method (one of "ext" or "pserver")
%u
Name of the user running git-cvsserver. If no name can be determined, the numeric uid is used.

ENVIRONMENT

These variables obviate the need for command-line options in some circumstances, allowing easier restricted usage through git-shell.

GIT_CVSSERVER_BASE_PATH takes the place of the argument to --base-path.

GIT_CVSSERVER_ROOT specifies a single-directory whitelist. The repository must still be configured to allow access through git-cvsserver, as described above.

When these environment variables are set, the corresponding command-line arguments may not be used.

Eclipse CVS Client Notes

To get a checkout with the Eclipse CVS client:

  1. Select "Create a new project → From CVS checkout"
  2. Create a new location. See the notes below for details on how to choose the right protocol.
  3. Browse the modules available. It will give you a list of the heads in the repository. You will not be able to browse the tree from there. Only the heads.
  4. Pick HEAD when it asks what branch/tag to check out. Untick the "launch commit wizard" to avoid committing the .project file.

Protocol notes: If you are using anonymous access via pserver, just select that. Those using SSH access should choose the ext protocol, and configure ext access on the Preferences→Team→CVS→ExtConnection pane. Set CVS_SERVER to "git cvsserver". Note that password support is not good when using ext, you will definitely want to have SSH keys setup.

Alternatively, you can just use the non-standard extssh protocol that Eclipse offer. In that case CVS_SERVER is ignored, and you will have to replace the cvs utility on the server with git-cvsserver or manipulate your .bashrc so that calling cvs effectively calls git-cvsserver.

Clients known to work

  • CVS 1.12.9 on Debian
  • CVS 1.11.17 on MacOSX (from Fink package)
  • Eclipse 3.0, 3.1.2 on MacOSX (see Eclipse CVS Client Notes)
  • TortoiseCVS

Operations supported

All the operations required for normal use are supported, including checkout, diff, status, update, log, add, remove, commit.

Most CVS command arguments that read CVS tags or revision numbers (typically -r) work, and also support any git refspec (tag, branch, commit ID, etc). However, CVS revision numbers for non-default branches are not well emulated, and cvs log does not show tags or branches at all. (Non-main-branch CVS revision numbers superficially resemble CVS revision numbers, but they actually encode a git commit ID directly, rather than represent the number of revisions since the branch point.)

Note that there are two ways to checkout a particular branch. As described elsewhere on this page, the "module" parameter of cvs checkout is interpreted as a branch name, and it becomes the main branch. It remains the main branch for a given sandbox even if you temporarily make another branch sticky with cvs update -r. Alternatively, the -r argument can indicate some other branch to actually checkout, even though the module is still the "main" branch. Tradeoffs (as currently implemented): Each new "module" creates a new database on disk with a history for the given module, and after the database is created, operations against that main branch are fast. Or alternatively, -r doesn't take any extra disk space, but may be significantly slower for many operations, like cvs update.

If you want to refer to a git refspec that has characters that are not allowed by CVS, you have two options. First, it may just work to supply the git refspec directly to the appropriate CVS -r argument; some CVS clients don't seem to do much sanity checking of the argument. Second, if that fails, you can use a special character escape mechanism that only uses characters that are valid in CVS tags. A sequence of 4 or 5 characters of the form (underscore ("_"), dash ("-"), one or two characters, and dash ("-")) can encode various characters based on the one or two letters: "s" for slash ("/"), "p" for period ("."), "u" for underscore ("_"), or two hexadecimal digits for any byte value at all (typically an ASCII number, or perhaps a part of a UTF-8 encoded character).

Legacy monitoring operations are not supported (edit, watch and related). Exports and tagging (tags and branches) are not supported at this stage.

1. CRLF Line Ending Conversions

By default the server leaves the -k mode blank for all files, which causes the CVS client to treat them as a text files, subject to end-of-line conversion on some platforms.

You can make the server use the end-of-line conversion attributes to set the -k modes for files by setting the gitcvs.usecrlfattr config variable. See Section G.4.2, “gitattributes(5)” for more information about end-of-line conversion.

Alternatively, if gitcvs.usecrlfattr config is not enabled or the attributes do not allow automatic detection for a filename, then the server uses the gitcvs.allBinary config for the default setting. If gitcvs.allBinary is set, then file not otherwise specified will default to -kb mode. Otherwise the -k mode is left blank. But if gitcvs.allBinary is set to "guess", then the correct -k mode will be guessed based on the contents of the file.

For best consistency with cvs, it is probably best to override the defaults by setting gitcvs.usecrlfattr to true, and gitcvs.allBinary to "guess".

Dependencies

git-cvsserver depends on DBD::SQLite.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.36. git-daemon(1)

NAME

git-daemon - A really simple server for Git repositories

SYNOPSIS

git daemon [--verbose] [--syslog] [--export-all]
             [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>]
             [--strict-paths] [--base-path=<path>] [--base-path-relaxed]
             [--user-path | --user-path=<path>]
             [--interpolated-path=<pathtemplate>]
             [--reuseaddr] [--detach] [--pid-file=<file>]
             [--enable=<service>] [--disable=<service>]
             [--allow-override=<service>] [--forbid-override=<service>]
             [--access-hook=<path>] [--[no-]informative-errors]
             [--inetd |
              [--listen=<host_or_ipaddr>] [--port=<n>]
              [--user=<user> [--group=<group>]]]
             [<directory>…]

DESCRIPTION

A really simple TCP Git daemon that normally listens on port "DEFAULT_GIT_PORT" aka 9418. It waits for a connection asking for a service, and will serve that service if it is enabled.

It verifies that the directory has the magic file "git-daemon-export-ok", and it will refuse to export any Git directory that hasn't explicitly been marked for export this way (unless the --export-all parameter is specified). If you pass some directory paths as git daemon arguments, you can further restrict the offers to a whitelist comprising of those.

By default, only upload-pack service is enabled, which serves git fetch-pack and git ls-remote clients, which are invoked from git fetch, git pull, and git clone.

This is ideally suited for read-only updates, i.e., pulling from Git repositories.

An upload-archive also exists to serve git archive.

OPTIONS

--strict-paths
Match paths exactly (i.e. don't allow "/foo/repo" when the real path is "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. git daemon will refuse to start when this option is enabled and no whitelist is specified.
--base-path=<path>
Remap all the path requests as relative to the given path. This is sort of "Git root" - if you run git daemon with --base-path=/srv/git on example.com, then if you later try to pull git://example.com/hello.git, git daemon will interpret the path as /srv/git/hello.git.
--base-path-relaxed
If --base-path is enabled and repo lookup fails, with this option git daemon will attempt to lookup without prefixing the base path. This is useful for switching to --base-path usage, while still allowing the old paths.
--interpolated-path=<pathtemplate>
To support virtual hosting, an interpolated path template can be used to dynamically construct alternate paths. The template supports %H for the target hostname as supplied by the client but converted to all lowercase, %CH for the canonical hostname, %IP for the server's IP address, %P for the port number, and %D for the absolute path of the named repository. After interpolation, the path is validated against the directory whitelist.
--export-all
Allow pulling from all directories that look like Git repositories (have the objects and refs subdirectories), even if they do not have the git-daemon-export-ok file.
--inetd
Have the server run as an inetd service. Implies --syslog. Incompatible with --detach, --port, --listen, --user and --group options.
--listen=<host_or_ipaddr>
Listen on a specific IP address or hostname. IP addresses can be either an IPv4 address or an IPv6 address if supported. If IPv6 is not supported, then --listen=hostname is also not supported and --listen must be given an IPv4 address. Can be given more than once. Incompatible with --inetd option.
--port=<n>
Listen on an alternative port. Incompatible with --inetd option.
--init-timeout=<n>
Timeout (in seconds) between the moment the connection is established and the client request is received (typically a rather low value, since that should be basically immediate).
--timeout=<n>
Timeout (in seconds) for specific client sub-requests. This includes the time it takes for the server to process the sub-request and the time spent waiting for the next client's request.
--max-connections=<n>
Maximum number of concurrent clients, defaults to 32. Set it to zero for no limit.
--syslog
Log to syslog instead of stderr. Note that this option does not imply --verbose, thus by default only error conditions will be logged.
--user-path , --user-path=<path>
Allow ~user notation to be used in requests. When specified with no parameter, requests to git://host/~alice/foo is taken as a request to access foo repository in the home directory of user alice. If --user-path=path is specified, the same request is taken as a request to access path/foo repository in the home directory of user alice.
--verbose
Log details about the incoming connections and requested files.
--reuseaddr
Use SO_REUSEADDR when binding the listening socket. This allows the server to restart without waiting for old connections to time out.
--detach
Detach from the shell. Implies --syslog.
--pid-file=<file>
Save the process id in file. Ignored when the daemon is run under --inetd.
--user=<user> , --group=<group>

Change daemon's uid and gid before entering the service loop. When only --user is given without --group, the primary group ID for the user is used. The values of the option are given to getpwnam(3) and getgrnam(3) and numeric IDs are not supported.

Giving these options is an error when used with --inetd; use the facility of inet daemon to achieve the same before spawning git daemon if needed.

Like many programs that switch user id, the daemon does not reset environment variables such as $HOME when it runs git programs, e.g. upload-pack and receive-pack. When using this option, you may also want to set and export HOME to point at the home directory of <user> before starting the daemon, and make sure any Git configuration files in that directory are readable by <user>.

--enable=<service> , --disable=<service>
Enable/disable the service site-wide per default. Note that a service disabled site-wide can still be enabled per repository if it is marked overridable and the repository enables the service with a configuration item.
--allow-override=<service> , --forbid-override=<service>
Allow/forbid overriding the site-wide default with per repository configuration. By default, all the services may be overridden.
--[no-]informative-errors
When informative errors are turned on, git-daemon will report more verbose errors to the client, differentiating conditions like "no such repository" from "repository not exported". This is more convenient for clients, but may leak information about the existence of unexported repositories. When informative errors are not enabled, all errors report "access denied" to the client. The default is --no-informative-errors.
--access-hook=<path>

Every time a client connects, first run an external command specified by the <path> with service name (e.g. "upload-pack"), path to the repository, hostname (%H), canonical hostname (%CH), IP address (%IP), and TCP port (%P) as its command-line arguments. The external command can decide to decline the service by exiting with a non-zero status (or to allow it by exiting with a zero status). It can also look at the $REMOTE_ADDR and $REMOTE_PORT environment variables to learn about the requestor when making this decision.

The external command can optionally write a single line to its standard output to be sent to the requestor as an error message when it declines the service.

<directory>
A directory to add to the whitelist of allowed directories. Unless --strict-paths is specified this will also include subdirectories of each named directory.

SERVICES

These services can be globally enabled/disabled using the command-line options of this command. If finer-grained control is desired (e.g. to allow git archive to be run against only in a few selected repositories the daemon serves), the per-repository configuration file can be used to enable or disable them.

upload-pack
This serves git fetch-pack and git ls-remote clients. It is enabled by default, but a repository can disable it by setting daemon.uploadpack configuration item to false.
upload-archive
This serves git archive --remote. It is disabled by default, but a repository can enable it by setting daemon.uploadarch configuration item to true.
receive-pack
This serves git send-pack clients, allowing anonymous push. It is disabled by default, as there is no authentication in the protocol (in other words, anybody can push anything into the repository, including removal of refs). This is solely meant for a closed LAN setting where everybody is friendly. This service can be enabled by setting daemon.receivepack configuration item to true.

EXAMPLES

We assume the following in /etc/services
$ grep 9418 /etc/services
git             9418/tcp                # Git Version Control System
git daemon as inetd server

To set up git daemon as an inetd service that handles any repository under the whitelisted set of directories, /pub/foo and /pub/bar, place an entry like the following into /etc/inetd all on one line:

        git stream tcp nowait nobody  /usr/bin/git
                git daemon --inetd --verbose --export-all
                /pub/foo /pub/bar
git daemon as inetd server for virtual hosts

To set up git daemon as an inetd service that handles repositories for different virtual hosts, www.example.com and www.example.org, place an entry like the following into /etc/inetd all on one line:

        git stream tcp nowait nobody /usr/bin/git
                git daemon --inetd --verbose --export-all
                --interpolated-path=/pub/%H%D
                /pub/www.example.org/software
                /pub/www.example.com/software
                /software

In this example, the root-level directory /pub will contain a subdirectory for each virtual host name supported. Further, both hosts advertise repositories simply as git://www.example.com/software/repo.git. For pre-1.4.0 clients, a symlink from /software into the appropriate default repository could be made as well.

git daemon as regular daemon for virtual hosts

To set up git daemon as a regular, non-inetd service that handles repositories for multiple virtual hosts based on their IP addresses, start the daemon like this:

        git daemon --verbose --export-all
                --interpolated-path=/pub/%IP/%D
                /pub/192.168.1.200/software
                /pub/10.10.220.23/software

In this example, the root-level directory /pub will contain a subdirectory for each virtual host IP address supported. Repositories can still be accessed by hostname though, assuming they correspond to these IP addresses.

selectively enable/disable services per repository

To enable git archive --remote and disable git fetch against a repository, have the following in the configuration file in the repository (that is the file config next to HEAD, refs and objects).

        [daemon]
                uploadpack = false
                uploadarch = true

ENVIRONMENT

git daemon will set REMOTE_ADDR to the IP address of the client that connected to it, if the IP address is available. REMOTE_ADDR will be available in the environment of hooks called when services are performed.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.37. git-describe(1)

NAME

git-describe - Describe a commit using the most recent tag reachable from it

SYNOPSIS

git describe [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>…]
git describe [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]

DESCRIPTION

The command finds the most recent tag that is reachable from a commit. If the tag points to the commit, then only the tag is shown. Otherwise, it suffixes the tag name with the number of additional commits on top of the tagged object and the abbreviated object name of the most recent commit.

By default (without --all or --tags) git describe only shows annotated tags. For more information about creating annotated tags see the -a and -s options to Section G.3.134, “git-tag(1)”.

OPTIONS

<commit-ish>…
Commit-ish object names to describe. Defaults to HEAD if omitted.
--dirty[=<mark>]
Describe the working tree. It means describe HEAD and appends <mark> (-dirty by default) if the working tree is dirty.
--all
Instead of using only the annotated tags, use any ref found in refs/ namespace. This option enables matching any known branch, remote-tracking branch, or lightweight tag.
--tags
Instead of using only the annotated tags, use any tag found in refs/tags namespace. This option enables matching a lightweight (non-annotated) tag.
--contains
Instead of finding the tag that predates the commit, find the tag that comes after the commit, and thus contains it. Automatically implies --tags.
--abbrev=<n>
Instead of using the default 7 hexadecimal digits as the abbreviated object name, use <n> digits, or as many digits as needed to form a unique object name. An <n> of 0 will suppress long format, only showing the closest tag.
--candidates=<n>
Instead of considering only the 10 most recent tags as candidates to describe the input commit-ish consider up to <n> candidates. Increasing <n> above 10 will take slightly longer but may produce a more accurate result. An <n> of 0 will cause only exact matches to be output.
--exact-match
Only output exact matches (a tag directly references the supplied commit). This is a synonym for --candidates=0.
--debug
Verbosely display information about the searching strategy being employed to standard error. The tag name will still be printed to standard out.
--long
Always output the long format (the tag, the number of commits and the abbreviated commit name) even when it matches a tag. This is useful when you want to see parts of the commit object name in "describe" output, even when the commit in question happens to be a tagged version. Instead of just emitting the tag name, it will describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2 that points at object deadbee….).
--match <pattern>
Only consider tags matching the given glob(7) pattern, excluding the "refs/tags/" prefix. This can be used to avoid leaking private tags from the repository.
--always
Show uniquely abbreviated commit object as fallback.
--first-parent
Follow only the first parent commit upon seeing a merge commit. This is useful when you wish to not match tags on branches merged in the history of the target commit.

EXAMPLES

With something like git.git current tree, I get:

[[email protected] git]$ git describe parent
v1.0.4-14-g2414721

i.e. the current head of my "parent" branch is based on v1.0.4, but since it has a few commits on top of that, describe has added the number of additional commits ("14") and an abbreviated object name for the commit itself ("2414721") at the end.

The number of additional commits is the number of commits which would be displayed by "git log v1.0.4..parent". The hash suffix is "-g" + 7-char abbreviation for the tip commit of parent (which was 2414721b194453f058079d897d13c4e377f92dc6). The "g" prefix stands for "git" and is used to allow describing the version of a software depending on the SCM the software is managed with. This is useful in an environment where people may use different SCMs.

Doing a git describe on a tag-name will just show the tag name:

[[email protected] git]$ git describe v1.0.4
v1.0.4

With --all, the command can use branch heads as references, so the output shows the reference path as well:

[[email protected] git]$ git describe --all --abbrev=4 v1.0.5^2
tags/v1.0.0-21-g975b
[[email protected] git]$ git describe --all --abbrev=4 HEAD^
heads/lt/describe-7-g975b

With --abbrev set to 0, the command can be used to find the closest tagname without any suffix:

[[email protected] git]$ git describe --abbrev=0 v1.0.5^2
tags/v1.0.0

Note that the suffix you get if you type these commands today may be longer than what Linus saw above when he ran these commands, as your Git repository may have new commits whose object names begin with 975b that did not exist back then, and "-g975b" suffix alone may not be sufficient to disambiguate these commits.

SEARCH STRATEGY

For each commit-ish supplied, git describe will first look for a tag which tags exactly that commit. Annotated tags will always be preferred over lightweight tags, and tags with newer dates will always be preferred over tags with older dates. If an exact match is found, its name will be output and searching will stop.

If an exact match was not found, git describe will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an abbreviation of the input commit-ish's SHA-1. If --first-parent was specified then the walk will only consider the first parent of each commit.

If multiple tags were found during the walk then the tag which has the fewest commits different from the input commit-ish will be selected and output. Here fewest commits different is defined as the number of commits which would be shown by git log tag..input will be the smallest number of commits possible.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.38. git-diff-files(1)

NAME

git-diff-files - Compares files in the working tree and the index

SYNOPSIS

git diff-files [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>…]

DESCRIPTION

Compares the files in the working tree and the index. When paths are specified, compares only those named paths. Otherwise all entries in the index are compared. The output format is the same as for git diff-index and git diff-tree.

OPTIONS

-p , -u , --patch
Generate patch (see section on generating patches).
-s , --no-patch
Suppress diff output. Useful for commands like git show that show the patch by default, or to cancel the effect of --patch.
-U<n> , --unified=<n>
Generate diffs with <n> lines of context instead of the usual three. Implies -p.
--raw
Generate the diff in raw format. This is the default.
--patch-with-raw
Synonym for -p --raw.
--minimal
Spend extra time to make sure the smallest possible diff is produced.
--patience
Generate a diff using the "patience diff" algorithm.
--histogram
Generate a diff using the "histogram diff" algorithm.
--diff-algorithm={patience|minimal|histogram|myers}

Choose a diff algorithm. The variants are as follows:

default, myers
The basic greedy diff algorithm. Currently, this is the default.
minimal
Spend extra time to make sure the smallest possible diff is produced.
patience
Use "patience diff" algorithm when generating patches.
histogram
This algorithm extends the patience algorithm to "support low-occurrence common elements".

For instance, if you configured diff.algorithm variable to a non-default value and want to use the default one, then you have to use --diff-algorithm=default option.

--stat[=<width>[,<name-width>[,<count>]]]

Generate a diffstat. By default, as much space as necessary will be used for the filename part, and the rest for the graph part. Maximum width defaults to terminal width, or 80 columns if not connected to a terminal, and can be overridden by <width>. The width of the filename part can be limited by giving another width <name-width> after a comma. The width of the graph part can be limited by using --stat-graph-width=<width> (affects all commands generating a stat graph) or by setting diff.statGraphWidth=<width> (does not affect git format-patch). By giving a third parameter <count>, you can limit the output to the first <count> lines, followed by ... if there are more.

These parameters can also be set individually with --stat-width=<width>, --stat-name-width=<name-width> and --stat-count=<count>.

--numstat
Similar to --stat, but shows number of added and deleted lines in decimal notation and pathname without abbreviation, to make it more machine friendly. For binary files, outputs two - instead of saying 0 0.
--shortstat
Output only the last line of the --stat format containing total number of modified files, as well as number of added and deleted lines.
--dirstat[=<param1,param2,…>]

Output the distribution of relative amount of changes for each sub-directory. The behavior of --dirstat can be customized by passing it a comma separated list of parameters. The defaults are controlled by the diff.dirstat configuration variable (see Section G.3.27, “git-config(1)”). The following parameters are available:

changes
Compute the dirstat numbers by counting the lines that have been removed from the source, or added to the destination. This ignores the amount of pure code movements within a file. In other words, rearranging lines in a file is not counted as much as other changes. This is the default behavior when no parameter is given.
lines
Compute the dirstat numbers by doing the regular line-based diff analysis, and summing the removed/added line counts. (For binary files, count 64-byte chunks instead, since binary files have no natural concept of lines). This is a more expensive --dirstat behavior than the changes behavior, but it does count rearranged lines within a file as much as other changes. The resulting output is consistent with what you get from the other --*stat options.
files
Compute the dirstat numbers by counting the number of files changed. Each changed file counts equally in the dirstat analysis. This is the computationally cheapest --dirstat behavior, since it does not have to look at the file contents at all.
cumulative
Count changes in a child directory for the parent directory as well. Note that when using cumulative, the sum of the percentages reported may exceed 100%. The default (non-cumulative) behavior can be specified with the noncumulative parameter.
<limit>
An integer parameter specifies a cut-off percent (3% by default). Directories contributing less than this percentage of the changes are not shown in the output.

Example: The following will count changed files, while ignoring directories with less than 10% of the total amount of changed files, and accumulating child directory counts in the parent directories: --dirstat=files,10,cumulative.

--summary
Output a condensed summary of extended header information such as creations, renames and mode changes.
--patch-with-stat
Synonym for -p --stat.
-z

When --raw, --numstat, --name-only or --name-status has been given, do not munge pathnames and use NULs as output field terminators.

Without this option, each pathname output will have TAB, LF, double quotes, and backslash characters replaced with \t, \n, \", and \\, respectively, and the pathname will be enclosed in double quotes if any of those replacements occurred.

--name-only
Show only names of changed files.
--name-status
Show only names and status of changed files. See the description of the --diff-filter option on what the status letters mean.
--submodule[=<format>]
Specify how differences in submodules are shown. When --submodule or --submodule=log is given, the log format is used. This format lists the commits in the range like Section G.3.131, “git-submodule(1)” summary does. Omitting the --submodule option or specifying --submodule=short, uses the short format. This format just shows the names of the commits at the beginning and end of the range. Can be tweaked via the diff.submodule configuration variable.
--color[=<when>]
Show colored diff. --color (i.e. without =<when>) is the same as --color=always. <when> can be one of always, never, or auto.
--no-color
Turn off colored diff. It is the same as --color=never.
--word-diff[=<mode>]

Show a word diff, using the <mode> to delimit changed words. By default, words are delimited by whitespace; see --word-diff-regex below. The <mode> defaults to plain, and must be one of:

color
Highlight changed words using only colors. Implies --color.
plain
Show words as [-removed-] and {+added+}. Makes no attempts to escape the delimiters if they appear in the input, so the output may be ambiguous.
porcelain
Use a special line-based format intended for script consumption. Added/removed/unchanged runs are printed in the usual unified diff format, starting with a +/-/` ` character at the beginning of the line and extending to the end of the line. Newlines in the input are represented by a tilde ~ on a line of its own.
none
Disable word diff again.

Note that despite the name of the first mode, color is used to highlight the changed parts in all modes if enabled.

--word-diff-regex=<regex>

Use <regex> to decide what a word is, instead of considering runs of non-whitespace to be a word. Also implies --word-diff unless it was already enabled.

Every non-overlapping match of the <regex> is considered a word. Anything between these matches is considered whitespace and ignored(!) for the purposes of finding differences. You may want to append |[^[:space:]] to your regular expression to make sure that it matches all non-whitespace characters. A match that contains a newline is silently truncated(!) at the newline.

For example, --word-diff-regex=. will treat each character as a word and, correspondingly, show differences character by character.

The regex can also be set via a diff driver or configuration option, see ??? or Section G.3.27, “git-config(1)”. Giving it explicitly overrides any diff driver or configuration setting. Diff drivers override configuration settings.

--color-words[=<regex>]
Equivalent to --word-diff=color plus (if a regex was specified) --word-diff-regex=<regex>.
--no-renames
Turn off rename detection, even when the configuration file gives the default to do so.
--check
Warn if changes introduce conflict markers or whitespace errors. What are considered whitespace errors is controlled by core.whitespace configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the initial indent of the line are considered whitespace errors. Exits with non-zero status if problems are found. Not compatible with --exit-code.
--ws-error-highlight=<kind>
Highlight whitespace errors on lines specified by <kind> in the color specified by color.diff.whitespace. <kind> is a comma separated list of old, new, context. When this option is not given, only whitespace errors in new lines are highlighted. E.g. --ws-error-highlight=new,old highlights whitespace errors on both deleted and added lines. all can be used as a short-hand for old,new,context.
--full-index
Instead of the first handful of characters, show the full pre- and post-image blob object names on the "index" line when generating patch format output.
--binary
In addition to --full-index, output a binary diff that can be applied with git-apply.
--abbrev[=<n>]
Instead of showing the full 40-byte hexadecimal object name in diff-raw format output and diff-tree header lines, show only a partial prefix. This is independent of the --full-index option above, which controls the diff-patch output format. Non default number of digits can be specified with --abbrev=<n>.
-B[<n>][/<m>] , --break-rewrites[=[<n>][/<m>]]

Break complete rewrite changes into pairs of delete and create. This serves two purposes:

It affects the way a change that amounts to a total rewrite of a file not as a series of deletion and insertion mixed together with a very few lines that happen to match textually as the context, but as a single deletion of everything old followed by a single insertion of everything new, and the number m controls this aspect of the -B option (defaults to 60%). -B/70% specifies that less than 30% of the original should remain in the result for Git to consider it a total rewrite (i.e. otherwise the resulting patch will be a series of deletion and insertion mixed together with context lines).

When used with -M, a totally-rewritten file is also considered as the source of a rename (usually -M only considers a file that disappeared as the source of a rename), and the number n controls this aspect of the -B option (defaults to 50%). -B20% specifies that a change with addition and deletion compared to 20% or more of the file's size are eligible for being picked up as a possible source of a rename to another file.

-M[<n>] , --find-renames[=<n>]
Detect renames. If n is specified, it is a threshold on the similarity index (i.e. amount of addition/deletions compared to the file's size). For example, -M90% means Git should consider a delete/add pair to be a rename if more than 90% of the file hasn't changed. Without a % sign, the number is to be read as a fraction, with a decimal point before it. I.e., -M5 becomes 0.5, and is thus the same as -M50%. Similarly, -M05 is the same as -M5%. To limit detection to exact renames, use -M100%. The default similarity index is 50%.
-C[<n>] , --find-copies[=<n>]
Detect copies as well as renames. See also --find-copies-harder. If n is specified, it has the same meaning as for -M<n>.
--find-copies-harder
For performance reasons, by default, -C option finds copies only if the original file of the copy was modified in the same changeset. This flag makes the command inspect unmodified files as candidates for the source of copy. This is a very expensive operation for large projects, so use it with caution. Giving more than one -C option has the same effect.
-D , --irreversible-delete

Omit the preimage for deletes, i.e. print only the header but not the diff between the preimage and /dev/null. The resulting patch is not meant to be applied with patch or git apply; this is solely for people who want to just concentrate on reviewing the text after the change. In addition, the output obviously lack enough information to apply such a patch in reverse, even manually, hence the name of the option.

When used together with -B, omit also the preimage in the deletion part of a delete/create pair.

-l<num>
The -M and -C options require O(n^2) processing time where n is the number of potential rename/copy targets. This option prevents rename/copy detection from running if the number of rename/copy targets exceeds the specified number.
--diff-filter=[(A|C|D|M|R|T|U|X|B)…[*]]
Select only files that are Added (A), Copied (C), Deleted (D), Modified (M), Renamed (R), have their type (i.e. regular file, symlink, submodule, …) changed (T), are Unmerged (U), are Unknown (X), or have had their pairing Broken (B). Any combination of the filter characters (including none) can be used. When * (All-or-none) is added to the combination, all paths are selected if there is any file that matches other criteria in the comparison; if there is no file that matches other criteria, nothing is selected.
-S<string>

Look for differences that change the number of occurrences of the specified string (i.e. addition/deletion) in a file. Intended for the scripter's use.

It is useful when you're looking for an exact block of code (like a struct), and want to know the history of that block since it first came into being: use the feature iteratively to feed the interesting block in the preimage back into -S, and keep going until you get the very first version of the block.

-G<regex>

Look for differences whose patch text contains added/removed lines that match <regex>.

To illustrate the difference between -S<regex> --pickaxe-regex and -G<regex>, consider a commit with the following diff in the same file:

+    return !regexec(regexp, two->ptr, 1, &regmatch, 0);
...
-    hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0);

While git log -G"regexec\(regexp" will show this commit, git log -S"regexec\(regexp" --pickaxe-regex will not (because the number of occurrences of that string did not change).

See the pickaxe entry in Section G.4.4, “gitdiffcore(7)” for more information.

--pickaxe-all
When -S or -G finds a change, show all the changes in that changeset, not just the files that contain the change in <string>.
--pickaxe-regex
Treat the <string> given to -S as an extended POSIX regular expression to match.
-O<orderfile>
Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line. This overrides the diff.orderFile configuration variable (see Section G.3.27, “git-config(1)”). To cancel diff.orderFile, use -O/dev/null.
-R
Swap two inputs; that is, show differences from index or on-disk file to tree contents.
--relative[=<path>]
When run from a subdirectory of the project, it can be told to exclude changes outside the directory and show pathnames relative to it with this option. When you are not in a subdirectory (e.g. in a bare repository), you can name which subdirectory to make the output relative to by giving a <path> as an argument.
-a , --text
Treat all files as text.
--ignore-space-at-eol
Ignore changes in whitespace at EOL.
-b , --ignore-space-change
Ignore changes in amount of whitespace. This ignores whitespace at line end, and considers all other sequences of one or more whitespace characters to be equivalent.
-w , --ignore-all-space
Ignore whitespace when comparing lines. This ignores differences even if one line has whitespace where the other line has none.
--ignore-blank-lines
Ignore changes whose lines are all blank.
--inter-hunk-context=<lines>
Show the context between diff hunks, up to the specified number of lines, thereby fusing hunks that are close to each other.
-W , --function-context
Show whole surrounding functions of changes.
--exit-code
Make the program exit with codes similar to diff(1). That is, it exits with 1 if there were differences and 0 means no differences.
--quiet
Disable all output of the program. Implies --exit-code.
--ext-diff
Allow an external diff helper to be executed. If you set an external diff driver with Section G.4.2, “gitattributes(5)”, you need to use this option with Section G.3.68, “git-log(1)” and friends.
--no-ext-diff
Disallow external diff drivers.
--textconv , --no-textconv
Allow (or disallow) external text conversion filters to be run when comparing binary files. See Section G.4.2, “gitattributes(5)” for details. Because textconv filters are typically a one-way conversion, the resulting diff is suitable for human consumption, but cannot be applied. For this reason, textconv filters are enabled by default only for Section G.3.41, “git-diff(1)” and Section G.3.68, “git-log(1)”, but not for Section G.3.50, “git-format-patch(1)” or diff plumbing commands.
--ignore-submodules[=<when>]
Ignore changes to submodules in the diff generation. <when> can be either "none", "untracked", "dirty" or "all", which is the default. Using "none" will consider the submodule modified when it either contains untracked or modified files or its HEAD differs from the commit recorded in the superproject and can be used to override any settings of the ignore option in Section G.3.27, “git-config(1)” or Section G.4.8, “gitmodules(5)”. When "untracked" is used submodules are not considered dirty when they only contain untracked content (but they are still scanned for modified content). Using "dirty" ignores all changes to the work tree of submodules, only changes to the commits stored in the superproject are shown (this was the behavior until 1.7.0). Using "all" hides all changes to submodules.
--src-prefix=<prefix>
Show the given source prefix instead of "a/".
--dst-prefix=<prefix>
Show the given destination prefix instead of "b/".
--no-prefix
Do not show any source or destination prefix.

For more detailed explanation on these common options, see also Section G.4.4, “gitdiffcore(7)”.

-1 --base , -2 --ours , -3 --theirs , -0

Diff against the "base" version, "our branch" or "their branch" respectively. With these options, diffs for merged entries are not shown.

The default is to diff against our branch (-2) and the cleanly resolved paths. The option -0 can be given to omit diff output for unmerged entries and just show "Unmerged".

-c , --cc
This compares stage 2 (our branch), stage 3 (their branch) and the working tree file and outputs a combined diff, similar to the way diff-tree shows a merge commit with these flags.
-q
Remain silent even on nonexistent files

Raw output format

The raw output format from "git-diff-index", "git-diff-tree", "git-diff-files" and "git diff --raw" are very similar.

These commands all compare two sets of things; what is compared differs:

git-diff-index <tree-ish>
compares the <tree-ish> and the files on the filesystem.
git-diff-index --cached <tree-ish>
compares the <tree-ish> and the index.
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>…]
compares the trees named by the two arguments.
git-diff-files [<pattern>…]
compares the index and the files on the filesystem.

The "git-diff-tree" command begins its output by printing the hash of what is being compared. After that, all the commands print one output line per changed file.

An output line is formatted this way:

in-place edit  :100644 100644 bcd1234... 0123456... M file0
copy-edit      :100644 100644 abcd123... 1234567... C68 file1 file2
rename-edit    :100644 100644 abcd123... 1234567... R86 file1 file3
create         :000000 100644 0000000... 1234567... A file4
delete         :100644 000000 1234567... 0000000... D file5
unmerged       :000000 000000 0000000... 0000000... U file6

That is, from the left to the right:

  1. a colon.
  2. mode for "src"; 000000 if creation or unmerged.
  3. a space.
  4. mode for "dst"; 000000 if deletion or unmerged.
  5. a space.
  6. sha1 for "src"; 0{40} if creation or unmerged.
  7. a space.
  8. sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree".
  9. a space.
  10. status, followed by optional "score" number.
  11. a tab or a NUL when -z option is used.
  12. path for "src"
  13. a tab or a NUL when -z option is used; only exists for C or R.
  14. path for "dst"; only exists for C or R.
  15. an LF or a NUL when -z option is used, to terminate the record.

Possible status letters are:

  • A: addition of a file
  • C: copy of a file into a new one
  • D: deletion of a file
  • M: modification of the contents or mode of a file
  • R: renaming of a file
  • T: change in the type of the file
  • U: file is unmerged (you must complete the merge before it can be committed)
  • X: "unknown" change type (most probably a bug, please report it)

Status letters C and R are always followed by a score (denoting the percentage of similarity between the source and target of the move or copy). Status letter M may be followed by a score (denoting the percentage of dissimilarity) for file rewrites.

<sha1> is shown as all 0's if a file is new on the filesystem and it is out of sync with the index.

Example:

:100644 100644 5be4a4...... 000000...... M file.c

When -z option is not used, TAB, LF, and backslash characters in pathnames are represented as \t, \n, and \\, respectively.

diff format for merges

"git-diff-tree", "git-diff-files" and "git-diff --raw" can take -c or --cc option to generate diff output also for merge commits. The output differs from the format described above in the following way:

  1. there is a colon for each parent
  2. there are more "src" modes and "src" sha1
  3. status is concatenated status characters for each parent
  4. no optional "score" number
  5. single path, only for "dst"

Example:

::100644 100644 100644 fabadb8... cc95eb0... 4866510... MM      describe.c

Note that combined diff lists only files which were modified from all parents.

Generating patches with -p

When "git-diff-index", "git-diff-tree", or "git-diff-files" are run with a -p option, "git diff" without the --raw option, or "git log" with the "-p" option, they do not produce the output described above; instead they produce a patch file. You can customize the creation of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables.

What the -p option produces is slightly different from the traditional diff format:

  1. It is preceded with a "git diff" header that looks like this:

    diff --git a/file1 b/file2

    The a/ and b/ filenames are the same unless rename/copy is involved. Especially, even for a creation or a deletion, /dev/null is not used in place of the a/ or b/ filenames.

    When rename/copy is involved, file1 and file2 show the name of the source file of the rename/copy and the name of the file that rename/copy produces, respectively.

  2. It is followed by one or more extended header lines:

    old mode <mode>
    new mode <mode>
    deleted file mode <mode>
    new file mode <mode>
    copy from <path>
    copy to <path>
    rename from <path>
    rename to <path>
    similarity index <number>
    dissimilarity index <number>
    index <hash>..<hash> <mode>

    File modes are printed as 6-digit octal numbers including the file type and file permission bits.

    Path names in extended headers do not include the a/ and b/ prefixes.

    The similarity index is the percentage of unchanged lines, and the dissimilarity index is the percentage of changed lines. It is a rounded down integer, followed by a percent sign. The similarity index value of 100% is thus reserved for two equal files, while 100% dissimilarity means that no line from the old file made it into the new one.

    The index line includes the SHA-1 checksum before and after the change. The <mode> is included if the file mode does not change; otherwise, separate lines indicate the old and the new mode.

  3. TAB, LF, double quote and backslash characters in pathnames are represented as \t, \n, \" and \\, respectively. If there is need for such substitution then the whole pathname is put in double quotes.
  4. All the file1 files in the output refer to files before the commit, and all the file2 files refer to files after the commit. It is incorrect to apply each change to each file sequentially. For example, this patch will swap a and b:

    diff --git a/a b/b
    rename from a
    rename to b
    diff --git a/b b/a
    rename from b
    rename to a

combined diff format

Any diff-generating command can take the -c or --cc option to produce a combined diff when showing a merge. This is the default format when showing merges with Section G.3.41, “git-diff(1)” or Section G.3.126, “git-show(1)”. Note also that you can give the -m option to any of these commands to force generation of diffs with individual parents of a merge.

A combined diff format looks like this:

diff --combined describe.c
index fabadb8,cc95eb0..4866510
--- a/describe.c
+++ b/describe.c
@@@ -98,20 -98,12 +98,20 @@@
        return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
  }

- static void describe(char *arg)
 -static void describe(struct commit *cmit, int last_one)
++static void describe(char *arg, int last_one)
  {
 +      unsigned char sha1[20];
 +      struct commit *cmit;
        struct commit_list *list;
        static int initialized = 0;
        struct commit_name *n;

 +      if (get_sha1(arg, sha1) < 0)
 +              usage(describe_usage);
 +      cmit = lookup_commit_reference(sha1);
 +      if (!cmit)
 +              usage(describe_usage);
 +
        if (!initialized) {
                initialized = 1;
                for_each_ref(get_name);
  1. It is preceded with a "git diff" header, that looks like this (when -c option is used):

    diff --combined file

    or like this (when --cc option is used):

    diff --cc file
  2. It is followed by one or more extended header lines (this example shows a merge with two parents):

    index <hash>,<hash>..<hash>
    mode <mode>,<mode>..<mode>
    new file mode <mode>
    deleted file mode <mode>,<mode>

    The mode <mode>,<mode>..<mode> line appears only if at least one of the <mode> is different from the rest. Extended headers with information about detected contents movement (renames and copying detection) are designed to work with diff of two <tree-ish> and are not used by combined diff format.

  3. It is followed by two-line from-file/to-file header

    --- a/file
    +++ b/file

    Similar to two-line header for traditional unified diff format, /dev/null is used to signal created or deleted files.

  4. Chunk header format is modified to prevent people from accidentally feeding it to patch -p1. Combined diff format was created for review of merge commit changes, and was not meant for apply. The change is similar to the change in the extended index header:

    @@@ <from-file-range> <from-file-range> <to-file-range> @@@

    There are (number of parents + 1) @ characters in the chunk header for combined diff format.

Unlike the traditional unified diff format, which shows two files A and B with a single column that has - (minus -- appears in A but removed in B), + (plus -- missing in A but added to B), or " " (space -- unchanged) prefix, this format compares two or more files file1, file2,… with one file X, and shows how X differs from each of fileN. One column for each of fileN is prepended to the output line to note how X's line is different from it.

A - character in the column N means that the line appears in fileN but it does not appear in the result. A + character in the column N means that the line appears in the result, and fileN does not have that line (in other words, the line was added, from the point of view of that parent).

In the above example output, the function signature was changed from both files (hence two - removals from both file1 and file2, plus ++ to mean one line that was added does not appear in either file1 or file2). Also eight other lines are the same from file1 but do not appear in file2 (hence prefixed with +).

When shown by git diff-tree -c, it compares the parents of a merge commit with the merge result (i.e. file1..fileN are the parents). When shown by git diff-files -c, it compares the two unresolved merge parents with the working tree file (i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka "their version").

other diff formats

The --summary option describes newly added, deleted, renamed and copied files. The --stat option adds diffstat(1) graph to the output. These options can be combined with other options, such as -p, and are meant for human consumption.

When showing a change that involves a rename or a copy, --stat output formats the pathnames compactly by combining common prefix and suffix of the pathnames. For example, a change that moves arch/i386/Makefile to arch/x86/Makefile while modifying 4 lines will be shown like this:

arch/{i386 => x86}/Makefile    |   4 +--

The --numstat option gives the diffstat(1) information but is designed for easier machine consumption. An entry in --numstat output looks like this:

1       2       README
3       1       arch/{i386 => x86}/Makefile

That is, from left to right:

  1. the number of added lines;
  2. a tab;
  3. the number of deleted lines;
  4. a tab;
  5. pathname (possibly with rename/copy information);
  6. a newline.

When -z output option is in effect, the output is formatted this way:

1       2       README NUL
3       1       NUL arch/i386/Makefile NUL arch/x86/Makefile NUL

That is:

  1. the number of added lines;
  2. a tab;
  3. the number of deleted lines;
  4. a tab;
  5. a NUL (only exists if renamed/copied);
  6. pathname in preimage;
  7. a NUL (only exists if renamed/copied);
  8. pathname in postimage (only exists if renamed/copied);
  9. a NUL.

The extra NUL before the preimage path in renamed case is to allow scripts that read the output to tell if the current record being read is a single-path record or a rename/copy record without reading ahead. After reading added and deleted lines, reading up to NUL would yield the pathname, but if that is NUL, the record will show two paths.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.39. git-diff-index(1)

NAME

git-diff-index - Compare a tree to the working tree or index

SYNOPSIS

git diff-index [-m] [--cached] [<common diff options>] <tree-ish> [<path>…]

DESCRIPTION

Compares the content and mode of the blobs found in a tree object with the corresponding tracked files in the working tree, or with the corresponding paths in the index. When <path> arguments are present, compares only paths matching those patterns. Otherwise all tracked files are compared.

OPTIONS

-p , -u , --patch
Generate patch (see section on generating patches).
-s , --no-patch
Suppress diff output. Useful for commands like git show that show the patch by default, or to cancel the effect of --patch.
-U<n> , --unified=<n>
Generate diffs with <n> lines of context instead of the usual three. Implies -p.
--raw
Generate the diff in raw format. This is the default.
--patch-with-raw
Synonym for -p --raw.
--minimal
Spend extra time to make sure the smallest possible diff is produced.
--patience
Generate a diff using the "patience diff" algorithm.
--histogram
Generate a diff using the "histogram diff" algorithm.
--diff-algorithm={patience|minimal|histogram|myers}

Choose a diff algorithm. The variants are as follows:

default, myers
The basic greedy diff algorithm. Currently, this is the default.
minimal
Spend extra time to make sure the smallest possible diff is produced.
patience
Use "patience diff" algorithm when generating patches.
histogram
This algorithm extends the patience algorithm to "support low-occurrence common elements".

For instance, if you configured diff.algorithm variable to a non-default value and want to use the default one, then you have to use --diff-algorithm=default option.

--stat[=<width>[,<name-width>[,<count>]]]

Generate a diffstat. By default, as much space as necessary will be used for the filename part, and the rest for the graph part. Maximum width defaults to terminal width, or 80 columns if not connected to a terminal, and can be overridden by <width>. The width of the filename part can be limited by giving another width <name-width> after a comma. The width of the graph part can be limited by using --stat-graph-width=<width> (affects all commands generating a stat graph) or by setting diff.statGraphWidth=<width> (does not affect git format-patch). By giving a third parameter <count>, you can limit the output to the first <count> lines, followed by ... if there are more.

These parameters can also be set individually with --stat-width=<width>, --stat-name-width=<name-width> and --stat-count=<count>.

--numstat
Similar to --stat, but shows number of added and deleted lines in decimal notation and pathname without abbreviation, to make it more machine friendly. For binary files, outputs two - instead of saying 0 0.
--shortstat
Output only the last line of the --stat format containing total number of modified files, as well as number of added and deleted lines.
--dirstat[=<param1,param2,…>]

Output the distribution of relative amount of changes for each sub-directory. The behavior of --dirstat can be customized by passing it a comma separated list of parameters. The defaults are controlled by the diff.dirstat configuration variable (see Section G.3.27, “git-config(1)”). The following parameters are available:

changes
Compute the dirstat numbers by counting the lines that have been removed from the source, or added to the destination. This ignores the amount of pure code movements within a file. In other words, rearranging lines in a file is not counted as much as other changes. This is the default behavior when no parameter is given.
lines
Compute the dirstat numbers by doing the regular line-based diff analysis, and summing the removed/added line counts. (For binary files, count 64-byte chunks instead, since binary files have no natural concept of lines). This is a more expensive --dirstat behavior than the changes behavior, but it does count rearranged lines within a file as much as other changes. The resulting output is consistent with what you get from the other --*stat options.
files
Compute the dirstat numbers by counting the number of files changed. Each changed file counts equally in the dirstat analysis. This is the computationally cheapest --dirstat behavior, since it does not have to look at the file contents at all.
cumulative
Count changes in a child directory for the parent directory as well. Note that when using cumulative, the sum of the percentages reported may exceed 100%. The default (non-cumulative) behavior can be specified with the noncumulative parameter.
<limit>
An integer parameter specifies a cut-off percent (3% by default). Directories contributing less than this percentage of the changes are not shown in the output.

Example: The following will count changed files, while ignoring directories with less than 10% of the total amount of changed files, and accumulating child directory counts in the parent directories: --dirstat=files,10,cumulative.

--summary
Output a condensed summary of extended header information such as creations, renames and mode changes.
--patch-with-stat
Synonym for -p --stat.
-z

When --raw, --numstat, --name-only or --name-status has been given, do not munge pathnames and use NULs as output field terminators.

Without this option, each pathname output will have TAB, LF, double quotes, and backslash characters replaced with \t, \n, \", and \\, respectively, and the pathname will be enclosed in double quotes if any of those replacements occurred.

--name-only
Show only names of changed files.
--name-status
Show only names and status of changed files. See the description of the --diff-filter option on what the status letters mean.
--submodule[=<format>]
Specify how differences in submodules are shown. When --submodule or --submodule=log is given, the log format is used. This format lists the commits in the range like Section G.3.131, “git-submodule(1)” summary does. Omitting the --submodule option or specifying --submodule=short, uses the short format. This format just shows the names of the commits at the beginning and end of the range. Can be tweaked via the diff.submodule configuration variable.
--color[=<when>]
Show colored diff. --color (i.e. without =<when>) is the same as --color=always. <when> can be one of always, never, or auto.
--no-color
Turn off colored diff. It is the same as --color=never.
--word-diff[=<mode>]

Show a word diff, using the <mode> to delimit changed words. By default, words are delimited by whitespace; see --word-diff-regex below. The <mode> defaults to plain, and must be one of:

color
Highlight changed words using only colors. Implies --color.
plain
Show words as [-removed-] and {+added+}. Makes no attempts to escape the delimiters if they appear in the input, so the output may be ambiguous.
porcelain
Use a special line-based format intended for script consumption. Added/removed/unchanged runs are printed in the usual unified diff format, starting with a +/-/` ` character at the beginning of the line and extending to the end of the line. Newlines in the input are represented by a tilde ~ on a line of its own.
none
Disable word diff again.

Note that despite the name of the first mode, color is used to highlight the changed parts in all modes if enabled.

--word-diff-regex=<regex>

Use <regex> to decide what a word is, instead of considering runs of non-whitespace to be a word. Also implies --word-diff unless it was already enabled.

Every non-overlapping match of the <regex> is considered a word. Anything between these matches is considered whitespace and ignored(!) for the purposes of finding differences. You may want to append |[^[:space:]] to your regular expression to make sure that it matches all non-whitespace characters. A match that contains a newline is silently truncated(!) at the newline.

For example, --word-diff-regex=. will treat each character as a word and, correspondingly, show differences character by character.

The regex can also be set via a diff driver or configuration option, see ??? or Section G.3.27, “git-config(1)”. Giving it explicitly overrides any diff driver or configuration setting. Diff drivers override configuration settings.

--color-words[=<regex>]
Equivalent to --word-diff=color plus (if a regex was specified) --word-diff-regex=<regex>.
--no-renames
Turn off rename detection, even when the configuration file gives the default to do so.
--check
Warn if changes introduce conflict markers or whitespace errors. What are considered whitespace errors is controlled by core.whitespace configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the initial indent of the line are considered whitespace errors. Exits with non-zero status if problems are found. Not compatible with --exit-code.
--ws-error-highlight=<kind>
Highlight whitespace errors on lines specified by <kind> in the color specified by color.diff.whitespace. <kind> is a comma separated list of old, new, context. When this option is not given, only whitespace errors in new lines are highlighted. E.g. --ws-error-highlight=new,old highlights whitespace errors on both deleted and added lines. all can be used as a short-hand for old,new,context.
--full-index
Instead of the first handful of characters, show the full pre- and post-image blob object names on the "index" line when generating patch format output.
--binary
In addition to --full-index, output a binary diff that can be applied with git-apply.
--abbrev[=<n>]
Instead of showing the full 40-byte hexadecimal object name in diff-raw format output and diff-tree header lines, show only a partial prefix. This is independent of the --full-index option above, which controls the diff-patch output format. Non default number of digits can be specified with --abbrev=<n>.
-B[<n>][/<m>] , --break-rewrites[=[<n>][/<m>]]

Break complete rewrite changes into pairs of delete and create. This serves two purposes:

It affects the way a change that amounts to a total rewrite of a file not as a series of deletion and insertion mixed together with a very few lines that happen to match textually as the context, but as a single deletion of everything old followed by a single insertion of everything new, and the number m controls this aspect of the -B option (defaults to 60%). -B/70% specifies that less than 30% of the original should remain in the result for Git to consider it a total rewrite (i.e. otherwise the resulting patch will be a series of deletion and insertion mixed together with context lines).

When used with -M, a totally-rewritten file is also considered as the source of a rename (usually -M only considers a file that disappeared as the source of a rename), and the number n controls this aspect of the -B option (defaults to 50%). -B20% specifies that a change with addition and deletion compared to 20% or more of the file's size are eligible for being picked up as a possible source of a rename to another file.

-M[<n>] , --find-renames[=<n>]
Detect renames. If n is specified, it is a threshold on the similarity index (i.e. amount of addition/deletions compared to the file's size). For example, -M90% means Git should consider a delete/add pair to be a rename if more than 90% of the file hasn't changed. Without a % sign, the number is to be read as a fraction, with a decimal point before it. I.e., -M5 becomes 0.5, and is thus the same as -M50%. Similarly, -M05 is the same as -M5%. To limit detection to exact renames, use -M100%. The default similarity index is 50%.
-C[<n>] , --find-copies[=<n>]
Detect copies as well as renames. See also --find-copies-harder. If n is specified, it has the same meaning as for -M<n>.
--find-copies-harder
For performance reasons, by default, -C option finds copies only if the original file of the copy was modified in the same changeset. This flag makes the command inspect unmodified files as candidates for the source of copy. This is a very expensive operation for large projects, so use it with caution. Giving more than one -C option has the same effect.
-D , --irreversible-delete

Omit the preimage for deletes, i.e. print only the header but not the diff between the preimage and /dev/null. The resulting patch is not meant to be applied with patch or git apply; this is solely for people who want to just concentrate on reviewing the text after the change. In addition, the output obviously lack enough information to apply such a patch in reverse, even manually, hence the name of the option.

When used together with -B, omit also the preimage in the deletion part of a delete/create pair.

-l<num>
The -M and -C options require O(n^2) processing time where n is the number of potential rename/copy targets. This option prevents rename/copy detection from running if the number of rename/copy targets exceeds the specified number.
--diff-filter=[(A|C|D|M|R|T|U|X|B)…[*]]
Select only files that are Added (A), Copied (C), Deleted (D), Modified (M), Renamed (R), have their type (i.e. regular file, symlink, submodule, …) changed (T), are Unmerged (U), are Unknown (X), or have had their pairing Broken (B). Any combination of the filter characters (including none) can be used. When * (All-or-none) is added to the combination, all paths are selected if there is any file that matches other criteria in the comparison; if there is no file that matches other criteria, nothing is selected.
-S<string>

Look for differences that change the number of occurrences of the specified string (i.e. addition/deletion) in a file. Intended for the scripter's use.

It is useful when you're looking for an exact block of code (like a struct), and want to know the history of that block since it first came into being: use the feature iteratively to feed the interesting block in the preimage back into -S, and keep going until you get the very first version of the block.

-G<regex>

Look for differences whose patch text contains added/removed lines that match <regex>.

To illustrate the difference between -S<regex> --pickaxe-regex and -G<regex>, consider a commit with the following diff in the same file:

+    return !regexec(regexp, two->ptr, 1, &regmatch, 0);
...
-    hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0);

While git log -G"regexec\(regexp" will show this commit, git log -S"regexec\(regexp" --pickaxe-regex will not (because the number of occurrences of that string did not change).

See the pickaxe entry in Section G.4.4, “gitdiffcore(7)” for more information.

--pickaxe-all
When -S or -G finds a change, show all the changes in that changeset, not just the files that contain the change in <string>.
--pickaxe-regex
Treat the <string> given to -S as an extended POSIX regular expression to match.
-O<orderfile>
Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line. This overrides the diff.orderFile configuration variable (see Section G.3.27, “git-config(1)”). To cancel diff.orderFile, use -O/dev/null.
-R
Swap two inputs; that is, show differences from index or on-disk file to tree contents.
--relative[=<path>]
When run from a subdirectory of the project, it can be told to exclude changes outside the directory and show pathnames relative to it with this option. When you are not in a subdirectory (e.g. in a bare repository), you can name which subdirectory to make the output relative to by giving a <path> as an argument.
-a , --text
Treat all files as text.
--ignore-space-at-eol
Ignore changes in whitespace at EOL.
-b , --ignore-space-change
Ignore changes in amount of whitespace. This ignores whitespace at line end, and considers all other sequences of one or more whitespace characters to be equivalent.
-w , --ignore-all-space
Ignore whitespace when comparing lines. This ignores differences even if one line has whitespace where the other line has none.
--ignore-blank-lines
Ignore changes whose lines are all blank.
--inter-hunk-context=<lines>
Show the context between diff hunks, up to the specified number of lines, thereby fusing hunks that are close to each other.
-W , --function-context
Show whole surrounding functions of changes.
--exit-code
Make the program exit with codes similar to diff(1). That is, it exits with 1 if there were differences and 0 means no differences.
--quiet
Disable all output of the program. Implies --exit-code.
--ext-diff
Allow an external diff helper to be executed. If you set an external diff driver with Section G.4.2, “gitattributes(5)”, you need to use this option with Section G.3.68, “git-log(1)” and friends.
--no-ext-diff
Disallow external diff drivers.
--textconv , --no-textconv
Allow (or disallow) external text conversion filters to be run when comparing binary files. See Section G.4.2, “gitattributes(5)” for details. Because textconv filters are typically a one-way conversion, the resulting diff is suitable for human consumption, but cannot be applied. For this reason, textconv filters are enabled by default only for Section G.3.41, “git-diff(1)” and Section G.3.68, “git-log(1)”, but not for Section G.3.50, “git-format-patch(1)” or diff plumbing commands.
--ignore-submodules[=<when>]
Ignore changes to submodules in the diff generation. <when> can be either "none", "untracked", "dirty" or "all", which is the default. Using "none" will consider the submodule modified when it either contains untracked or modified files or its HEAD differs from the commit recorded in the superproject and can be used to override any settings of the ignore option in Section G.3.27, “git-config(1)” or Section G.4.8, “gitmodules(5)”. When "untracked" is used submodules are not considered dirty when they only contain untracked content (but they are still scanned for modified content). Using "dirty" ignores all changes to the work tree of submodules, only changes to the commits stored in the superproject are shown (this was the behavior until 1.7.0). Using "all" hides all changes to submodules.
--src-prefix=<prefix>
Show the given source prefix instead of "a/".
--dst-prefix=<prefix>
Show the given destination prefix instead of "b/".
--no-prefix
Do not show any source or destination prefix.

For more detailed explanation on these common options, see also Section G.4.4, “gitdiffcore(7)”.

<tree-ish>
The id of a tree object to diff against.
--cached
do not consider the on-disk file at all
-m
By default, files recorded in the index but not checked out are reported as deleted. This flag makes git diff-index say that all non-checked-out files are up to date.

Raw output format

The raw output format from "git-diff-index", "git-diff-tree", "git-diff-files" and "git diff --raw" are very similar.

These commands all compare two sets of things; what is compared differs:

git-diff-index <tree-ish>
compares the <tree-ish> and the files on the filesystem.
git-diff-index --cached <tree-ish>
compares the <tree-ish> and the index.
git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>…]
compares the trees named by the two arguments.
git-diff-files [<pattern>…]
compares the index and the files on the filesystem.

The "git-diff-tree" command begins its output by printing the hash of what is being compared. After that, all the commands print one output line per changed file.

An output line is formatted this way:

in-place edit  :100644 100644 bcd1234... 0123456... M file0
copy-edit      :100644 100644 abcd123... 1234567... C68 file1 file2
rename-edit    :100644 100644 abcd123... 1234567... R86 file1 file3
create         :000000 100644 0000000... 1234567... A file4
delete         :100644 000000 1234567... 0000000... D file5
unmerged       :000000 000000 0000000... 0000000... U file6

That is, from the left to the right:

  1. a colon.
  2. mode for "src"; 000000 if creation or unmerged.
  3. a space.
  4. mode for "dst"; 000000 if deletion or unmerged.
  5. a space.
  6. sha1 for "src"; 0{40} if creation or unmerged.
  7. a space.
  8. sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree".
  9. a space.
  10. status, followed by optional "score" number.
  11. a tab or a NUL when -z option is used.
  12. path for "src"
  13. a tab or a NUL when -z option is used; only exists for C or R.
  14. path for "dst"; only exists for C or R.
  15. an LF or a NUL when -z option is used, to terminate the record.

Possible status letters are:

  • A: addition of a file
  • C: copy of a file into a new one
  • D: deletion of a file
  • M: modification of the contents or mode of a file
  • R: renaming of a file
  • T: change in the type of the file
  • U: file is unmerged (you must complete the merge before it can be committed)
  • X: "unknown" change type (most probably a bug, please report it)

Status letters C and R are always followed by a score (denoting the percentage of similarity between the source and target of the move or copy). Status letter M may be followed by a score (denoting the percentage of dissimilarity) for file rewrites.

<sha1> is shown as all 0's if a file is new on the filesystem and it is out of sync with the index.

Example:

:100644 100644 5be4a4...... 000000...... M file.c

When -z option is not used, TAB, LF, and backslash characters in pathnames are represented as \t, \n, and \\, respectively.

diff format for merges

"git-diff-tree", "git-diff-files" and "git-diff --raw" can take -c or --cc option to generate diff output also for merge commits. The output differs from the format described above in the following way:

  1. there is a colon for each parent
  2. there are more "src" modes and "src" sha1
  3. status is concatenated status characters for each parent
  4. no optional "score" number
  5. single path, only for "dst"

Example:

::100644 100644 100644 fabadb8... cc95eb0... 4866510... MM      describe.c

Note that combined diff lists only files which were modified from all parents.

Generating patches with -p

When "git-diff-index", "git-diff-tree", or "git-diff-files" are run with a -p option, "git diff" without the --raw option, or "git log" with the "-p" option, they do not produce the output described above; instead they produce a patch file. You can customize the creation of such patches via the GIT_EXTERNAL_DIFF and the GIT_DIFF_OPTS environment variables.

What the -p option produces is slightly different from the traditional diff format:

  1. It is preceded with a "git diff" header that looks like this:

    diff --git a/file1 b/file2

    The a/ and b/ filenames are the same unless rename/copy is involved. Especially, even for a creation or a deletion, /dev/null is not used in place of the a/ or b/ filenames.

    When rename/copy is involved, file1 and file2 show the name of the source file of the rename/copy and the name of the file that rename/copy produces, respectively.

  2. It is followed by one or more extended header lines:

    old mode <mode>
    new mode <mode>
    deleted file mode <mode>
    new file mode <mode>
    copy from <path>
    copy to <path>
    rename from <path>
    rename to <path>
    similarity index <number>
    dissimilarity index <number>
    index <hash>..<hash> <mode>

    File modes are printed as 6-digit octal numbers including the file type and file permission bits.

    Path names in extended headers do not include the a/ and b/ prefixes.

    The similarity index is the percentage of unchanged lines, and the dissimilarity index is the percentage of changed lines. It is a rounded down integer, followed by a percent sign. The similarity index value of 100% is thus reserved for two equal files, while 100% dissimilarity means that no line from the old file made it into the new one.

    The index line includes the SHA-1 checksum before and after the change. The <mode> is included if the file mode does not change; otherwise, separate lines indicate the old and the new mode.

  3. TAB, LF, double quote and backslash characters in pathnames are represented as \t, \n, \" and \\, respectively. If there is need for such substitution then the whole pathname is put in double quotes.
  4. All the file1 files in the output refer to files before the commit, and all the file2 files refer to files after the commit. It is incorrect to apply each change to each file sequentially. For example, this patch will swap a and b:

    diff --git a/a b/b
    rename from a
    rename to b
    diff --git a/b b/a
    rename from b
    rename to a

combined diff format

Any diff-generating command can take the -c or --cc option to produce a combined diff when showing a merge. This is the default format when showing merges with Section G.3.41, “git-diff(1)” or Section G.3.126, “git-show(1)”. Note also that you can give the -m option to any of these commands to force generation of diffs with individual parents of a merge.

A combined diff format looks like this:

diff --combined describe.c
index fabadb8,cc95eb0..4866510
--- a/describe.c
+++ b/describe.c
@@@ -98,20 -98,12 +98,20 @@@
        return (a_date > b_date) ? -1 : (a_date == b_date) ? 0 : 1;
  }

- static void describe(char *arg)
 -static void describe(struct commit *cmit, int last_one)
++static void describe(char *arg, int last_one)
  {
 +      unsigned char sha1[20];
 +      struct commit *cmit;
        struct commit_list *list;
        static int initialized = 0;
        struct commit_name *n;

 +      if (get_sha1(arg, sha1) < 0)
 +              usage(describe_usage);
 +      cmit = lookup_commit_reference(sha1);
 +      if (!cmit)
 +              usage(describe_usage);
 +
        if (!initialized) {
                initialized = 1;
                for_each_ref(get_name);
  1. It is preceded with a "git diff" header, that looks like this (when -c option is used):

    diff --combined file

    or like this (when --cc option is used):

    diff --cc file
  2. It is followed by one or more extended header lines (this example shows a merge with two parents):

    index <hash>,<hash>..<hash>
    mode <mode>,<mode>..<mode>
    new file mode <mode>
    deleted file mode <mode>,<mode>

    The mode <mode>,<mode>..<mode> line appears only if at least one of the <mode> is different from the rest. Extended headers with information about detected contents movement (renames and copying detection) are designed to work with diff of two <tree-ish> and are not used by combined diff format.

  3. It is followed by two-line from-file/to-file header

    --- a/file
    +++ b/file

    Similar to two-line header for traditional unified diff format, /dev/null is used to signal created or deleted files.

  4. Chunk header format is modified to prevent people from accidentally feeding it to patch -p1. Combined diff format was created for review of merge commit changes, and was not meant for apply. The change is similar to the change in the extended index header:

    @@@ <from-file-range> <from-file-range> <to-file-range> @@@

    There are (number of parents + 1) @ characters in the chunk header for combined diff format.

Unlike the traditional unified diff format, which shows two files A and B with a single column that has - (minus -- appears in A but removed in B), + (plus -- missing in A but added to B), or " " (space -- unchanged) prefix, this format compares two or more files file1, file2,… with one file X, and shows how X differs from each of fileN. One column for each of fileN is prepended to the output line to note how X's line is different from it.

A - character in the column N means that the line appears in fileN but it does not appear in the result. A + character in the column N means that the line appears in the result, and fileN does not have that line (in other words, the line was added, from the point of view of that parent).

In the above example output, the function signature was changed from both files (hence two - removals from both file1 and file2, plus ++ to mean one line that was added does not appear in either file1 or file2). Also eight other lines are the same from file1 but do not appear in file2 (hence prefixed with +).

When shown by git diff-tree -c, it compares the parents of a merge commit with the merge result (i.e. file1..fileN are the parents). When shown by git diff-files -c, it compares the two unresolved merge parents with the working tree file (i.e. file1 is stage 2 aka "our version", file2 is stage 3 aka "their version").

other diff formats

The --summary option describes newly added, deleted, renamed and copied files. The --stat option adds diffstat(1) graph to the output. These options can be combined with other options, such as -p, and are meant for human consumption.

When showing a change that involves a rename or a copy, --stat output formats the pathnames compactly by combining common prefix and suffix of the pathnames. For example, a change that moves arch/i386/Makefile to arch/x86/Makefile while modifying 4 lines will be shown like this:

arch/{i386 => x86}/Makefile    |   4 +--

The --numstat option gives the diffstat(1) information but is designed for easier machine consumption. An entry in --numstat output looks like this:

1       2       README
3       1       arch/{i386 => x86}/Makefile

That is, from left to right:

  1. the number of added lines;
  2. a tab;
  3. the number of deleted lines;
  4. a tab;
  5. pathname (possibly with rename/copy information);
  6. a newline.

When -z output option is in effect, the output is formatted this way:

1       2       README NUL
3       1       NUL arch/i386/Makefile NUL arch/x86/Makefile NUL

That is:

  1. the number of added lines;
  2. a tab;
  3. the number of deleted lines;
  4. a tab;
  5. a NUL (only exists if renamed/copied);
  6. pathname in preimage;
  7. a NUL (only exists if renamed/copied);
  8. pathname in postimage (only exists if renamed/copied);
  9. a NUL.

The extra NUL before the preimage path in renamed case is to allow scripts that read the output to tell if the current record being read is a single-path record or a rename/copy record without reading ahead. After reading added and deleted lines, reading up to NUL would yield the pathname, but if that is NUL, the record will show two paths.

Operating Modes

You can choose whether you want to trust the index file entirely (using the --cached flag) or ask the diff logic to show any files that don't match the stat state as being "tentatively changed". Both of these operations are very useful indeed.

Cached Mode

If --cached is specified, it allows you to ask:

show me the differences between HEAD and the current index
contents (the ones I'd write using 'git write-tree')

For example, let's say that you have worked on your working directory, updated some files in the index and are ready to commit. You want to see exactly what you are going to commit, without having to write a new tree object and compare it that way, and to do that, you just do

git diff-index --cached HEAD

Example: let's say I had renamed commit.c to git-commit.c, and I had done an update-index to make that effective in the index file. git diff-files wouldn't show anything at all, since the index file matches my working directory. But doing a git diff-index does:

[email protected]:~/git> git diff-index --cached HEAD
-100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        commit.c
+100644 blob    4161aecc6700a2eb579e842af0b7f22b98443f74        git-commit.c

You can see easily that the above is a rename.

In fact, git diff-index --cached should always be entirely equivalent to actually doing a git write-tree and comparing that. Except this one is much nicer for the case where you just want to check where you are.

So doing a git diff-index --cached is basically very useful when you are asking yourself "what have I already marked for being committed, and what's the difference to a previous tree".

Non-cached Mode

The "non-cached" mode takes a different approach, and is potentially the more useful of the two in that what it does can't be emulated with a git write-tree + git diff-tree. Thus that's the default mode. The non-cached version asks the question:

show me the differences between HEAD and the currently checked out
tree - index contents _and_ files that aren't up-to-date

which is obviously a very useful question too, since that tells you what you could commit. Again, the output matches the git diff-tree -r output to a tee, but with a twist.

The twist is that if some file doesn't match the index, we don't have a backing store thing for it, and we use the magic "all-zero" sha1 to show that. So let's say that you have edited kernel/sched.c, but have not actually done a git update-index on it yet - there is no "object" associated with the new state, and you get:

[email protected]:~/v2.6/linux> git diff-index --abbrev HEAD
:100644 100664 7476bb... 000000...      kernel/sched.c

i.e., it shows that the tree has changed, and that kernel/sched.c has is not up-to-date and may contain new stuff. The all-zero sha1 means that to get the real diff, you need to look at the object in the working directory directly rather than do an object-to-object diff.

[Note] Note

As with other commands of this type, git diff-index does not actually look at the contents of the file at all. So maybe kernel/sched.c hasn't actually changed, and it's just that you touched it. In either case, it's a note that you need to git update-index it to make the index be in sync.

[Note] Note

You can have a mixture of files show up as "has been updated" and "is still dirty in the working directory" together. You can always tell which file is in which state, since the "has been updated" ones show a valid sha1, and the "not in sync with the index" ones will always have the special all-zero sha1.

GIT

Part of the Section G.3.1, “git(1)” suite

G.3.40. git-diff-tree(1)

NAME

git-diff-tree - Compares the content and mode of blobs found via two tree objects

SYNOPSIS

git diff-tree [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty]
              [-t] [-r] [-c | --cc] [--root] [<common diff options>]
              <tree-ish> [<tree-ish>] [<path>…]

DESCRIPTION

Compares the content and mode of the blobs found via two tree objects.

If there is only one <tree-ish> given, the commit is compared with its parents (see --stdin below).

Note that git diff-tree can use the tree encapsulated in a commit object.

OPTIONS

-p , -u , --patch
Generate patch (see section on generating patches).
-s , --no-patch
Suppress diff output. Useful for commands like git show that show the patch by default, or to cancel the effect of --patch.
-U<n> , --unified=<n>
Generate diffs with <n> lines of context instead of the usual three. Implies -p.
--raw
Generate the diff in raw format. This is the default.
--patch-with-raw
Synonym for -p --raw.
--minimal
Spend extra time to make sure the smallest possible diff is produced.
--patience
Generate a diff using the "patience diff" algorithm.
--histogram
Generate a diff using the "histogram diff" algorithm.
--diff-algorithm={patience|minimal|histogram|myers}

Choose a diff algorithm. The variants are as follows:

default, myers
The basic greedy diff algorithm. Currently, this is the default.
minimal
Spend extra time to make sure the smallest possible diff is produced.
patience
Use "patience diff" algorithm when generating patches.
histogram
This algorithm extends the patience algorithm to "support low-occurrence common elements".

For instance, if you configured diff.algorithm variable to a non-default value and want to use the default one, then you have to use --diff-algorithm=default option.

--stat[=<width>[,<name-width>[,<count>]]]

Generate a diffstat. By default, as much space as necessary will be used for the filename part, and the rest for the graph part. Maximum width defaults to terminal width, or 80 columns if not connected to a terminal, and can be overridden by <width>. The width of the filename part can be limited by giving another width <name-width> after a comma. The width of the graph part can be limited by using --stat-graph-width=<width> (affects all commands generating a stat graph) or by setting diff.statGraphWidth=<width> (does not affect git format-patch). By giving a third parameter <count>, you can limit the output to the first <count> lines, followed by ... if there are more.

These parameters can also be set individually with --stat-width=<width>, --stat-name-width=<name-width> and --stat-count=<count>.

--numstat
Similar to --stat, but shows number of added and deleted lines in decimal notation and pathname without abbreviation, to make it more machine friendly. For binary files, outputs two - instead of saying 0 0.
--shortstat
Output only the last line of the --stat format containing total number of modified files, as well as number of added and deleted lines.
--dirstat[=<param1,param2,…>]

Output the distribution of relative amount of changes for each sub-directory. The behavior of --dirstat can be customized by passing it a comma separated list of parameters. The defaults are controlled by the diff.dirstat configuration variable (see Section G.3.27, “git-config(1)”). The following parameters are available:

changes
Compute the dirstat numbers by counting the lines that have been removed from the source, or added to the destination. This ignores the amount of pure code movements within a file. In other words, rearranging lines in a file is not counted as much as other changes. This is the default behavior when no parameter is given.
lines
Compute the dirstat numbers by doing the regular line-based diff analysis, and summing the removed/added line counts. (For binary files, count 64-byte chunks instead, since binary files have no natural concept of lines). This is a more expensive --dirstat behavior than the changes behavior, but it does count rearranged lines within a file as much as other changes. The resulting output is consistent with what you get from the other --*stat options.
files
Compute the dirstat numbers by counting the number of files changed. Each changed file counts equally in the dirstat analysis. This is the computationally cheapest --dirstat behavior, since it does not have to look at the file contents at all.
cumulative
Count changes in a child directory for the parent directory as well. Note that when using cumulative, the sum of the percentages reported may exceed 100%. The default (non-cumulative) behavior can be specified with the noncumulative parameter.
<limit>
An integer parameter specifies a cut-off percent (3% by default). Directories contributing less than this percentage of the changes are not shown in the output.

Example: The following will count changed files, while ignoring directories with less than 10% of the total amount of changed files, and accumulating child directory counts in the parent directories: --dirstat=files,10,cumulative.

--summary
Output a condensed summary of extended header information such as creations, renames and mode changes.
--patch-with-stat
Synonym for -p --stat.
-z

When --raw, --numstat, --name-only or --name-status has been given, do not munge pathnames and use NULs as output field terminators.

Without this option, each pathname output will have TAB, LF, double quotes, and backslash characters replaced with \t, \n, \", and \\, respectively, and the pathname will be enclosed in double quotes if any of those replacements occurred.

--name-only
Show only names of changed files.
--name-status
Show only names and status of changed files. See the description of the --diff-filter option on what the status letters mean.
--submodule[=<format>]
Specify how differences in submodules are shown. When --submodule or --submodule=log is given, the log format is used. This format lists the commits in the range like Section G.3.131, “git-submodule(1)” summary does. Omitting the --submodule option or specifying --submodule=short, uses the short format. This format just shows the names of the commits at the beginning and end of the range. Can be tweaked via the diff.submodule configuration variable.
--color[=<when>]
Show colored diff. --color (i.e. without =<when>) is the same as --color=always. <when> can be one of always, never, or auto.
--no-color
Turn off colored diff. It is the same as --color=never.
--word-diff[=<mode>]

Show a word diff, using the <mode> to delimit changed words. By default, words are delimited by whitespace; see --word-diff-regex below. The <mode> defaults to plain, and must be one of:

color
Highlight changed words using only colors. Implies --color.
plain
Show words as [-removed-] and {+added+}. Makes no attempts to escape the delimiters if they appear in the input, so the output may be ambiguous.
porcelain
Use a special line-based format intended for script consumption. Added/removed/unchanged runs are printed in the usual unified diff format, starting with a +/-/` ` character at the beginning of the line and extending to the end of the line. Newlines in the input are represented by a tilde ~ on a line of its own.
none
Disable word diff again.

Note that despite the name of the first mode, color is used to highlight the changed parts in all modes if enabled.

--word-diff-regex=<regex>

Use <regex> to decide what a word is, instead of considering runs of non-whitespace to be a word. Also implies --word-diff unless it was already enabled.

Every non-overlapping match of the <regex> is considered a word. Anything between these matches is considered whitespace and ignored(!) for the purposes of finding differences. You may want to append |[^[:space:]] to your regular expression to make sure that it matches all non-whitespace characters. A match that contains a newline is silently truncated(!) at the newline.

For example, --word-diff-regex=. will treat each character as a word and, correspondingly, show differences character by character.

The regex can also be set via a diff driver or configuration option, see ??? or Section G.3.27, “git-config(1)”. Giving it explicitly overrides any diff driver or configuration setting. Diff drivers override configuration settings.

--color-words[=<regex>]
Equivalent to --word-diff=color plus (if a regex was specified) --word-diff-regex=<regex>.
--no-renames
Turn off rename detection, even when the configuration file gives the default to do so.
--check
Warn if changes introduce conflict markers or whitespace errors. What are considered whitespace errors is controlled by core.whitespace configuration. By default, trailing whitespaces (including lines that solely consist of whitespaces) and a space character that is immediately followed by a tab character inside the initial indent of the line are considered whitespace errors. Exits with non-zero status if problems are found. Not compatible with --exit-code.
--ws-error-highlight=<kind>
Highlight whitespace errors on lines specified by <kind> in the color specified by color.diff.whitespace. <kind> is a comma separated list of old, new, context. When this option is not given, only whitespace errors in new lines are highlighted. E.g. --ws-error-highlight=new,old highlights whitespace errors on both deleted and added lines. all can be used as a short-hand for old,new,context.
--full-index
Instead of the first handful of characters, show the full pre- and post-image blob object names on the "index" line when generating patch format output.
--binary
In addition to --full-index, output a binary diff that can be applied with git-apply.
--abbrev[=<n>]
Instead of showing the full 40-byte hexadecimal object name in diff-raw format output and diff-tree header lines, show only a partial prefix. This is independent of the --full-index option above, which controls the diff-patch output format. Non default number of digits can be specified with --abbrev=<n>.
-B[<n>][/<m>] , --break-rewrites[=[<n>][/<m>]]

Break complete rewrite changes into pairs of delete and create. This serves two purposes:

It affects the way a change that amounts to a total rewrite of a file not as a series of deletion and insertion mixed together with a very few lines that happen to match textually as the context, but as a single deletion of everything old followed by a single insertion of everything new, and the number m controls this aspect of the -B option (defaults to 60%). -B/70% specifies that less than 30% of the original should remain in the result for Git to consider it a total rewrite (i.e. otherwise the resulting patch will be a series of deletion and insertion mixed together with context lines).

When used with -M, a totally-rewritten file is also considered as the source of a rename (usually -M only considers a file that disappeared as the source of a rename), and the number n controls this aspect of the -B option (defaults to 50%). -B20% specifies that a change with addition and deletion compared to 20% or more of the file's size are eligible for being picked up as a possible source of a rename to another file.

-M[<n>] , --find-renames[=<n>]
Detect renames. If n is specified, it is a threshold on the similarity index (i.e. amount of addition/deletions compared to the file's size). For example, -M90% means Git should consider a delete/add pair to be a rename if more than 90% of the file hasn't changed. Without a % sign, the number is to be read as a fraction, with a decimal point before it. I.e., -M5 becomes 0.5, and is thus the same as -M50%. Similarly, -M05 is the same as -M5%. To limit detection to exact renames, use -M100%. The default similarity index is 50%.
-C[<n>] , --find-copies[=<n>]
Detect copies as well as renames. See also --find-copies-harder. If n is specified, it has the same meaning as for -M<n>.
--find-copies-harder
For performance reasons, by default, -C option finds copies only if the original file of the copy was modified in the same changeset. This flag makes the command inspect unmodified files as candidates for the source of copy. This is a very expensive operation for large projects, so use it with caution. Giving more than one -C option has the same effect.
-D , --irreversible-delete

Omit the preimage for deletes, i.e. print only the header but not the diff between the preimage and /dev/null. The resulting patch is not meant to be applied with patch or git apply; this is solely for people who want to just concentrate on reviewing the text after the change. In addition, the output obviously lack enough information to apply such a patch in reverse, even manually, hence the name of the option.

When used together with -B, omit also the preimage in the deletion part of a delete/create pair.

-l<num>
The -M and -C options require O(n^2) processing time where n is the number of potential rename/copy targets. This option prevents rename/copy detection from running if the number of rename/copy targets exceeds the specified number.
--diff-filter=[(A|C|D|M|R|T|U|X|B)…[*]]
Select only files that are Added (A), Copied (C), Deleted (D), Modified (M), Renamed (R), have their type (i.e. regular file, symlink, submodule, …) changed (T), are Unmerged (U), are Unknown (X), or have had their pairing Broken (B). Any combination of the filter characters (including none) can be used. When * (All-or-none) is added to the combination, all paths are selected if there is any file that matches other criteria in the comparison; if there is no file that matches other criteria, nothing is selected.
-S<string>

Look for differences that change the number of occurrences of the specified string (i.e. addition/deletion) in a file. Intended for the scripter's use.

It is useful when you're looking for an exact block of code (like a struct), and want to know the history of that block since it first came into being: use the feature iteratively to feed the interesting block in the preimage back into -S, and keep going until you get the very first version of the block.

-G<regex>

Look for differences whose patch text contains added/removed lines that match <regex>.

To illustrate the difference between -S<regex> --pickaxe-regex and -G<regex>, consider a commit with the following diff in the same file:

+    return !regexec(regexp, two->ptr, 1, &regmatch, 0);
...
-    hit = !regexec(regexp, mf2.ptr, 1, &regmatch, 0);

While git log -G"regexec\(regexp" will show this commit, git log -S"regexec\(regexp" --pickaxe-regex will not (because the number of occurrences of that string did not change).

See the pickaxe entry in Section G.4.4, “gitdiffcore(7)” for more information.

--pickaxe-all
When -S or -G finds a change, show all the changes in that changeset, not just the files that contain the change in <string>.
--pickaxe-regex
Treat the <string> given to -S as an extended POSIX regular expression to match.
-O<orderfile>
Output the patch in the order specified in the <orderfile>, which has one shell glob pattern per line. This overrides the diff.orderFile configuration variable (see Section G.3.27, “git-config(1)”). To cancel diff.orderFile, use -O/dev/null.
-R
Swap two inputs; that is, show differences from index or on-disk file to tree contents.
--relative[=<path>]
When run from a subdirectory of the project, it can be told to exclude changes outside the directory and show pathnames relative to it with this option. When you are not in a subdirectory (e.g. in a bare repository), you can name which subdirectory to make the output relative to by giving a <path> as an argument.
-a , --text
Treat all files as text.
--ignore-space-at-eol
Ignore changes in whitespace at EOL.
-b , --ignore-space-change
Ignore changes in amount of whitespace. This ignores whitespace at line end, and considers all other sequences of one or more whitespace characters to be equivalent.
-w , --ignore-all-space
Ignore whitespace when comparing lines. This ignores differences even if one line has whitespace where the other line has none.
--ignore-blank-lines
Ignore changes whose lines are all blank.
--inter-hunk-context=<lines>
Show the context between diff hunks, up to the specified number of lines, thereby fusing hunks that are close to each other.
-W , --function-context
Show whole surrounding functions of changes.
--exit-code
Make the program exit with codes similar to diff(1). That is, it exits with 1 if there were differences and 0 means no differences.
--quiet
Disable all output of the program. Implies --exit-code.
--ext-diff
Allow an external diff helper to be executed. If you set an external diff driver with Section G.4.2, “gitattributes(5)”, you need to use this option with Section G.3.68, “git-log(1)” and friends.
--no-ext-diff
Disallow external diff drivers.
--textconv , --no-textconv
Allow (or disallow) external text conversion filters to be run when comparing binary files. See Section G.4.2, “gitattributes(5)” for details. Because textconv filters are typically a one-way conversion, the resulting diff is suitable for human consumption, but cannot be applied. For this reason, textconv filters are enabled by default only for Section G.3.41, “git-diff(1)” and Section G.3.68, “git-log(1)”, but not for Section G.3.50, “git-format-patch(1)” or diff plumbing commands.
--ignore-submodules[=<when>]
Ignore changes to submodules in the diff generation. <when> can be either "none", "untracked", "dirty" or "all", which is the default. Using "none" will consider the submodule modified when it either contains untracked or modified files or its HEAD differs from the commit recorded in the superproject and can be used to override any settings of the ignore option in Section G.3.27, “git-config(1)” or Section G.4.8, “gitmodules(5)”. When "untracked" is used submodules are not considered dirty when they only contain untracked content (but they are still scanned for modified content). Using "dirty" ignores all changes to the work tree of submodules, only changes to the commits stored in the superproject are shown (this was the behavior until 1.7.0). Using "all" hides all changes to submodules.
--src-prefix=<prefix>
Show the given source prefix instead of "a/".
--dst-prefix=<prefix>
Show the given destination prefix instead of "b/".
--no-prefix
Do not show any source or destination prefix.

For more detailed explanation on these common options, see also Section G.4.4, “gitdiffcore(7)”.

<tree-ish>
The id of a tree object.
<path>…
If provided, the results are limited to a subset of files matching one of these prefix strings. i.e., file matches /^<pattern1>|<pattern2>|.../ Note that this parameter does not provide any wildcard or regexp features.
-r
recurse into sub-trees
-t
show tree entry itself as well as subtrees. Implies -r.
--root
When --root is specified the initial commit will be shown as a big creation event. This is equivalent to a diff against the NULL tree.
--stdin

When --stdin is specified, the command does not take <tree-ish> arguments from the command line. Instead, it reads lines containing either two <tree>, one <commit>, or a list of <commit> from its standard input. (Use a single space as separator.)

When two trees are given, it compares the first tree with the second. When a single commit is given, it compares the commit with its parents. The remaining commits, when given, are used as if they are parents of the first commit.

When comparing two trees, the ID of both trees (separated by a space and terminated by a newline) is printed before the difference. When comparing commits, the ID of the first (or only) commit, followed by a newline, is printed.

The following flags further affect the behavior when comparing commits (but not trees).

-m
By default, git diff-tree --stdin does not show differences for merge commits. With this flag, it shows differences to that commit from all of its parents. See also -c.
-s
By default, git diff-tree --stdin shows differences, either in machine-readable form (without -p) or in patch form (with -p). This output can be suppressed. It is only useful with -v flag.
-v
This flag causes git diff-tree --stdin to also show the commit message before the differences.
--pretty[=<format>] , --format=<format>

Pretty-print the contents of the commit logs in a given format, where <format> can be one of oneline, short, medium, full, fuller, email, raw, format:<string> and tformat:<string>. When <format> is none of the above, and has %placeholder in it, it acts as if --pretty=tformat:<format> were given.

See the "PRETTY FORMATS" section for some additional details for each format. When =<format> part is omitted, it defaults to medium.

Note: you can specify the default pretty format in the repository configuration (see Section G.3.27, “git-config(1)”).

--abbrev-commit

Instead of showing the full 40-byte hexadecimal commit object name, show only a partial prefix. Non default number of digits can be specified with "--abbrev=<n>" (which also modifies diff output, if it is displayed).

This should make "--pretty=oneline" a whole lot more readable for people using 80-column terminals.

--no-abbrev-commit
Show the full 40-byte hexadecimal commit object name. This negates --abbrev-commit and those options which imply it such as "--oneline". It also overrides the log.abbrevCommit variable.
--oneline
This is a shorthand for "--pretty=oneline --abbrev-commit" used together.
--encoding=<encoding>
The commit objects record the encoding used for the log message in their encoding header; this option can be used to tell the command to re-code the commit log message in the encoding preferred by the user. For non plumbing commands this defaults to UTF-8. Note that if an object claims to be encoded in X and we are outputting in X, we will output the object verbatim; this means that invalid sequences in the original commit may be copied to the output.
--expand-tabs=<n> , --expand-tabs , --no-expand-tabs

Perform a tab expansion (replace each tab with enough spaces to fill to the next display column that is multiple of <n>) in the log message before showing it in the output. --expand-tabs is a short-hand for --expand-tabs=8, and --no-expand-tabs is a short-hand for --expand-tabs=0, which disables tab expansion.

By default, tabs are expanded in pretty formats that indent the log message by 4 spaces (i.e. medium, which is the default, full, and fuller).

--notes[=<treeish>]

Show the notes (see Section G.3.86, “git-notes(1)”) that annotate the commit, when showing the commit log message. This is the default for git log, git show and git whatchanged commands when there is no --pretty, --format, or --oneline option given on the command line.

By default, the notes shown are from the notes refs listed in the core.notesRef and notes.displayRef variables (or corresponding environment overrides). See Section G.3.27, “git-config(1)” for more details.

With an optional <treeish> argument, use the treeish to find the notes to display. The treeish can specify the full refname when it begins with refs/notes/; when it begins with notes/, refs/ and otherwise refs/notes/ is prefixed to form a full name of the ref.

Multiple --notes options can be combined to control which notes are being displayed. Examples: "--notes=foo" will show only notes from "refs/notes/foo"; "--notes=foo --notes" will show both notes from "refs/notes/foo" and from the default notes ref(s).

--no-notes
Do not show notes. This negates the above --notes option, by resetting the list of notes refs from which notes are shown. Options are parsed in the order given on the command line, so e.g. "--notes --notes=foo --no-notes --notes=bar" will only show notes from "refs/notes/bar".
--show-notes[=<treeish>] , --[no-]standard-notes
These options are deprecated. Use the above --notes/--no-notes options instead.
--show-signature
Check the validity of a signed commit object by passing the signature to gpg --verify and show the output.
--no-commit-id
git diff-tree outputs a line with the commit ID when applicable. This flag suppressed the commit ID output.
-c
This flag changes the way a merge commit is displayed (which means it is useful only when the command is given one <tree-ish>, or --stdin). It shows the differences from each of the parents to the merge result simultaneously instead of showing pairwise diff between a parent and the result one at a time (which is what the -m option does). Furthermore, it lists only files which were modified from all parents.
--cc
This flag changes the way a merge commit patch is displayed, in a similar way to the -c option. It implies the -c and -p options and further compresses the patch output by omitting uninteresting hunks whose the contents in the parents have only two variants and the merge result picks one of them without modification. When all hunks are uninteresting, the commit itself and the commit log message is not shown, just like in any other "empty diff" case.
--always
Show the commit itself and the commit log message even if the diff itself is empty.

PRETTY FORMATS

If the commit is a merge, and if the pretty-format is not oneline, email or raw, an additional line is inserted before the Author: line. This line begins with "Merge: " and the sha1s of ancestral commits are printed, separated by spaces. Note that the listed commits may not necessarily be the list of the direct parent commits if you have limited your view of history: for example, if you are only interested in changes related to a certain directory or file.

There are several built-in formats, and you can define additional formats by setting a pretty.<name> config option to either another format name, or a format: string, as described below (see Section G.3.27, “git-config(1)”). Here are the details of the built-in formats:

  • oneline

    <sha1> <title line>

    This is designed to be as compact as possible.

  • short

    commit <sha1>
    Author: <author>
    <title line>
  • medium

    commit <sha1>
    Author: <author>
    Date:   <author date>
    <title line>
    <full commit message>
  • full

    commit <sha1>
    Author: <author>
    Commit: <committer>
    <title line>
    <full commit message>
  • fuller

    commit <sha1>
    Author:     <author>
    AuthorDate: <author date>
    Commit:     <committer>
    CommitDate: <committer date>
    <title line>
    <full commit message>
  • email

    From <sha1> <date>
    From: <author>
    Date: <author date>
    Subject: [PATCH] <title line>
    <full commit message>
  • raw

    The raw format shows the entire commit exactly as stored in the commit object. Notably, the SHA-1s are displayed in full, regardless of whether --abbrev or --no-abbrev are used, and parents information show the true parent commits, without taking grafts or history simplification into account. Note that this format affects the way commits are displayed, but not the way the diff is shown e.g. with git log --raw. To get full object names in a raw diff format, use --no-abbrev.

  • format:<string>

    The format:<string> format allows you to specify which information you want to show. It works a little bit like printf format, with the notable exception that you get a newline with %n instead of \n.

    E.g, format:"The author of %h was %an, %ar%nThe title was >>%s<<%n" would show something like this:

    The author of fe6e0ee was Junio C Hamano, 23 hours ago
    The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<

    The placeholders are:

    • %H: commit hash
    • %h: abbreviated commit hash
    • %T: tree hash
    • %t: abbreviated tree hash
    • %P: parent hashes
    • %p: abbreviated parent hashes
    • %an: author name
    • %aN: author name (respecting .mailmap, see Section G.3.122, “git-shortlog(1)” or Section G.3.9, “git-blame(1)”)
    • %ae: author email
    • %aE: author email (respecting .mailmap, see Section G.3.122, “git-shortlog(1)” or Section G.3.9, “git-blame(1)”)
    • %ad: author date (format respects --date= option)
    • %aD: author date, RFC2822 style
    • %ar: author date, relative
    • %at: author date, UNIX timestamp
    • %ai: author date, ISO 8601-like format
    • %aI: author date, strict ISO 8601 format
    • %cn: committer name
    • %cN: committer name (respecting .mailmap, see Section G.3.122, “git-shortlog(1)” or Section G.3.9, “git-blame(1)”)
    • %ce: committer email
    • %cE: committer email (respecting .mailmap, see Section G.3.122, “git-shortlog(1)” or Section G.3.9, “git-blame(1)”)
    • %cd: committer date (format respects --date= option)
    • %cD: committer date, RFC2822 style
    • %cr: committer date, relative
    • %ct: committer date, UNIX timestamp
    • %ci: committer date, ISO 8601-like format
    • %cI: committer date, strict ISO 8601 format
    • %d: ref names, like the --decorate option of Section G.3.68, “git-log(1)”
    • %D: ref names without the " (", ")" wrapping.
    • %e: encoding
    • %s: subject
    • %f: sanitized subject line, suitable for a filename
    • %b: body
    • %B: raw body (unwrapped subject and body)
    • %N: commit notes
    • %GG: raw verification message from GPG for a signed commit
    • %G?: show "G" for a Good signature, "B" for a Bad signature, "U" for a good, untrusted signature and "N" for no signature
    • %GS: show the name of the signer for a signed commit
    • %GK: show the key used to sign a signed commit
    • %gD: reflog selector, e.g., refs/[email protected]{1}
    • %gd: shortened reflog selector, e.g., [email protected]{1}
    • %gn: reflog identity name
    • %gN: reflog identity name (respecting .mailmap, see Section G.3.122, “git-shortlog(1)” or Section G.3.9, “git-blame(1)”)
    • %ge: reflog identity email
    • %gE: reflog identity email (respecting .mailmap, see Section G.3.122, “git-shortlog(1)” or Section G.3.9, “git-blame(1)”)
    • %gs: reflog subject
    • %Cred: switch color to red
    • %Cgreen: switch color to green
    • %Cblue: switch color to blue
    • %Creset: reset color
    • %C(…): color specification, as described in color.branch.* config option; adding auto, at the beginning will emit color only when colors are enabled for log output (by color.diff, color.ui, or --color, and respecting the auto settings of the former if we are going to a terminal). auto alone (i.e. %C(auto)) will turn on auto coloring on the next placeholders until the color is switched again.
    • %m: left, right or boundary mark
    • %n: newline
    • %%: a raw %
    • %x00: print a byte from a hex code
    • %w([<w>[,<i1>[,<i2>]]]): switch line wrapping, like the -w option of Section G.3.122, “git-shortlog(1)”.
    • %<(<N>[,trunc|ltrunc|mtrunc]): make the next placeholder take at least N columns, padding spaces on the right if necessary. Optionally truncate at the beginning (ltrunc), the middle (mtrunc) or the end (trunc) if the output is longer than N columns. Note that truncating only works correctly with N >= 2.
    • %<|(<N>): make the next placeholder take at least until Nth columns, padding spaces on the right if necessary
    • %>(<N>), %>|(<N>): similar to %<(<N>), %<|(<N>) respectively, but padding spaces on the left
    • %>>(<N>), %>>|(<N>): similar to %>(<N>), %>|(<N>) respectively, except that if the next placeholder takes more spaces than given and there are spaces on its left, use those spaces
    • %><(<N>), %><|(<N>): similar to % <(<N>), %<|(<N>) respectively, but padding both sides (i.e. the text is centered)
[Note] Note

Some placeholders may depend on other options given to the revision traversal engine. For example, the %g* reflog options will insert an empty string unless we are traversing reflog entries (e.g., by git log -g). The %d and %D placeholders will use the "short" decoration format if --decorate was not already provided on the command line.

If you add a + (plus sign) after % of a placeholder, a line-feed is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string.

If you add a - (minus sign) after % of a placeholder, line-feeds that immediately precede the expansion are deleted if and only if the placeholder expands to an empty string.

If you add a ` ` (space) after % of a placeholder, a space is inserted immediately before the expansion if and only if the placeholder expands to a non-empty string.

  • tformat:

    The tformat: format works exactly like format:, except that it provides "terminator" semantics instead of "separator" semantics. In other words, each commit has the message terminator character (usually a newline) appended, rather than a separator placed between entries. This means that the final entry of a single-line format will be properly terminated with a new line, just as the "oneline" format does. For example:

    $ git log -2 --pretty=format:%h 4da45bef \
      | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
    4da45be
    7134973 -- NO NEWLINE
    
    $ git log -2 --pretty=tformat:%h 4da45bef \
      | perl -pe '$_ .= " -- NO NEWLINE\n" unless /\n/'
    4da45be
    7134973

    In addition, any unrecognized string that has a % in it is interpreted as if it has tformat: in front of it. For example, these two are equivalent:

    $ git log -2 --pretty=tformat:%h 4da45bef
    $ git log -2 --pretty=%h 4da45bef

Limiting Output

If you're only interested in differences in a subset of files, for example some architecture-specific files, you might do:

git diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64

and it will only show you what changed in those two directories.

Or if you are searching for what changed in just kernel/sched.c, just do

git diff-tree -r <tree-ish> <tree-ish> kernel/sched.c

and it will ignore all differences to other files.

The pattern is always the prefix, and is matched exactly. There are no wildcards. Even stricter, it has to match a complete path component. I.e. "foo" does not pick up foobar.h. "foo" does match foo/bar.h so it can be used to name subdirectories.

An example of normal usage is:

[email protected]:~/git> git diff-tree --abbrev 5319e4
:100664 100664 ac348b... a01513...    git-fsck-objects.c

which tells you that the last commit changed just one file (it's from this one:

commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
tree 5319e4d609cdd282069cc4dce33c1db559539b03
parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
author Linus Torvalds <[email protected]> Sat Apr 9 12:02:30 2005
committer Linus Torvalds <[email protected]> Sat Apr 9 12:02:30 2005

Make "git-fsck-objects" print out all the root commits it finds.

Once I do the reference tracking, I'll also make it print out all the
HEAD commits it finds, which is even more interesting.

in case you care).

Raw output format

The raw output format from "git-diff-index", "git-diff-tree", "git-diff-files" and "git diff --raw" are very similar.

These commands all compare two sets of things; what is compared differs:

git-diff-index <tree-ish>
compares the <tree-ish> and the files on the filesystem.
git-diff-index --cached <tree-ish>
compares the <tree-ish> and the index.
git-diff-tree [-r] <tree-ish-1