SYNOPSIS
--------
[verse]
-'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [-p|--paginate]
- [--bare] [--git-dir=GIT_DIR] [--help] COMMAND [ARGS]
+'git' [--version] [--exec-path[=GIT_EXEC_PATH]]
+ [-p|--paginate|--no-pager]
+ [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]
+ [--help] COMMAND [ARGS]
DESCRIPTION
-----------
See this link:tutorial.html[tutorial] to get started, then see
link:everyday.html[Everyday Git] for a useful minimum set of commands, and
"man git-commandname" for documentation of each command. CVS users may
-also want to read link:cvs-migration.html[CVS migration].
+also want to read link:cvs-migration.html[CVS migration]. See
+link:user-manual.html[Git User's Manual] for a more in-depth
+introduction.
The COMMAND is either a name of a Git command (see below) or an alias
-as defined in the configuration file (see gitlink:git-repo-config[1]).
+as defined in the configuration file (see gitlink:git-config[1]).
+
+Formatted and hyperlinked version of the latest git
+documentation can be viewed at
+`http://www.kernel.org/pub/software/scm/git/docs/`.
+
+ifdef::stalenotes[]
+[NOTE]
+============
+
+You are reading the documentation for the latest (possibly
+unreleased) version of git, that is available from 'master'
+branch of the `git.git` repository.
+Documentation for older releases are available here:
+
+* link:v1.5.3/git.html[documentation for release 1.5.3]
+
+* release notes for
+ link:RelNotes-1.5.3.1.txt[1.5.3.1].
+
+* release notes for
+ link:RelNotes-1.5.2.5.txt[1.5.2.5],
+ link:RelNotes-1.5.2.4.txt[1.5.2.4],
+ link:RelNotes-1.5.2.3.txt[1.5.2.3],
+ link:RelNotes-1.5.2.2.txt[1.5.2.2],
+ link:RelNotes-1.5.2.1.txt[1.5.2.1],
+ link:RelNotes-1.5.2.txt[1.5.2].
+
+* link:v1.5.1.6/git.html[documentation for release 1.5.1.6]
+
+* release notes for
+ link:RelNotes-1.5.1.6.txt[1.5.1.6],
+ link:RelNotes-1.5.1.5.txt[1.5.1.5],
+ link:RelNotes-1.5.1.4.txt[1.5.1.4],
+ link:RelNotes-1.5.1.3.txt[1.5.1.3],
+ link:RelNotes-1.5.1.2.txt[1.5.1.2],
+ link:RelNotes-1.5.1.1.txt[1.5.1.1],
+ link:RelNotes-1.5.1.txt[1.5.1].
+
+* link:v1.5.0.7/git.html[documentation for release 1.5.0.7]
+
+* release notes for
+ link:RelNotes-1.5.0.7.txt[1.5.0.7],
+ link:RelNotes-1.5.0.6.txt[1.5.0.6],
+ link:RelNotes-1.5.0.5.txt[1.5.0.5],
+ link:RelNotes-1.5.0.3.txt[1.5.0.3],
+ link:RelNotes-1.5.0.2.txt[1.5.0.2],
+ link:RelNotes-1.5.0.1.txt[1.5.0.1],
+ link:RelNotes-1.5.0.txt[1.5.0].
+
+* documentation for release link:v1.4.4.4/git.html[1.4.4.4],
+ link:v1.3.3/git.html[1.3.3],
+ link:v1.2.6/git.html[1.2.6],
+ link:v1.0.13/git.html[1.0.13].
+
+============
+
+endif::stalenotes[]
OPTIONS
-------
-p|--paginate::
Pipe all output into 'less' (or if set, $PAGER).
+--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.
+--work-tree=<path>::
+ Set the path to the working tree. The value will not be
+ used in combination with repositories found automatically in
+ a .git directory (i.e. $GIT_DIR is not set).
+ This can also be controlled by setting the GIT_WORK_TREE
+ environment variable and the core.worktree configuration
+ variable.
+
--bare::
- Same as --git-dir=`pwd`.
+ Treat the repository as a bare repository. If GIT_DIR
+ environment is not set, it is set to the current working
+ directory.
+
FURTHER DOCUMENTATION
---------------------
See the references above to get started using git. The following is
probably more detail than necessary for a first-time user.
-The <<Discussion,Discussion>> section below and the
-link:core-tutorial.html[Core tutorial] both provide introductions to the
-underlying git architecture.
+The link:user-manual.html#git-concepts[git concepts chapter of the
+user-manual] and the link:core-tutorial.html[Core tutorial] both provide
+introductions to the underlying git architecture.
See also the link:howto-index.html[howto] documents for some useful
examples.
Main porcelain commands
~~~~~~~~~~~~~~~~~~~~~~~
-gitlink:git-add[1]::
- Add paths to the index.
-
-gitlink:git-am[1]::
- Apply patches from a mailbox, but cooler.
-
-gitlink:git-applymbox[1]::
- Apply patches from a mailbox, original version by Linus.
-
-gitlink:git-archive[1]::
- Creates an archive of files from a named tree.
-
-gitlink:git-bisect[1]::
- Find the change that introduced a bug by binary search.
-
-gitlink:git-branch[1]::
- Create and Show branches.
-
-gitlink:git-checkout[1]::
- Checkout and switch to a branch.
-
-gitlink:git-cherry-pick[1]::
- Cherry-pick the effect of an existing commit.
-
-gitlink:git-clean[1]::
- Remove untracked files from the working tree.
-
-gitlink:git-clone[1]::
- Clones a repository into a new directory.
-
-gitlink:git-commit[1]::
- Record changes to the repository.
-
-gitlink:git-diff[1]::
- Show changes between commits, commit and working tree, etc.
-
-gitlink:git-fetch[1]::
- Download from a remote repository via various protocols.
-
-gitlink:git-format-patch[1]::
- Prepare patches for e-mail submission.
-
-gitlink:git-grep[1]::
- Print lines matching a pattern.
-
-gitlink:gitk[1]::
- The git repository browser.
-
-gitlink:git-log[1]::
- Shows commit logs.
-
-gitlink:git-ls-remote[1]::
- Shows references in a remote or local repository.
-
-gitlink:git-merge[1]::
- Grand unified merge driver.
-
-gitlink:git-mv[1]::
- Move or rename a file, a directory, or a symlink.
-
-gitlink:git-pack-refs[1]::
- Pack heads and tags for efficient repository access.
-
-gitlink:git-pull[1]::
- Fetch from and merge with a remote repository or a local branch.
-
-gitlink:git-push[1]::
- Update remote refs along with associated objects.
-
-gitlink:git-rebase[1]::
- Rebase local commits to the updated upstream head.
-
-gitlink:git-repack[1]::
- Pack unpacked objects in a repository.
-
-gitlink:git-rerere[1]::
- Reuse recorded resolution of conflicted merges.
-
-gitlink:git-reset[1]::
- Reset current HEAD to the specified state.
-
-gitlink:git-resolve[1]::
- Merge two commits.
-
-gitlink:git-revert[1]::
- Revert an existing commit.
-
-gitlink:git-rm[1]::
- Remove files from the working tree and from the index.
-
-gitlink:git-shortlog[1]::
- Summarizes 'git log' output.
-
-gitlink:git-show[1]::
- Show one commit log and its diff.
-
-gitlink:git-show-branch[1]::
- Show branches and their commits.
-
-gitlink:git-status[1]::
- Shows the working tree status.
-
-gitlink:git-verify-tag[1]::
- Check the GPG signature of tag.
-
-gitlink:git-whatchanged[1]::
- Shows commit logs and differences they introduce.
-
+include::cmds-mainporcelain.txt[]
Ancillary Commands
~~~~~~~~~~~~~~~~~~
Manipulators:
-gitlink:git-applypatch[1]::
- Apply one patch extracted from an e-mail.
-
-gitlink:git-archimport[1]::
- Import an arch repository into git.
-
-gitlink:git-convert-objects[1]::
- Converts old-style git repository.
-
-gitlink:git-cvsimport[1]::
- Salvage your data out of another SCM people love to hate.
-
-gitlink:git-cvsexportcommit[1]::
- Export a single commit to a CVS checkout.
-
-gitlink:git-cvsserver[1]::
- A CVS server emulator for git.
-
-gitlink:git-lost-found[1]::
- Recover lost refs that luckily have not yet been pruned.
-
-gitlink:git-merge-one-file[1]::
- The standard helper program to use with `git-merge-index`.
-
-gitlink:git-prune[1]::
- Prunes all unreachable objects from the object database.
-
-gitlink:git-quiltimport[1]::
- Applies a quilt patchset onto the current branch.
-
-gitlink:git-relink[1]::
- Hardlink common objects in local repositories.
-
-gitlink:git-svn[1]::
- Bidirectional operation between a single Subversion branch and git.
-
-gitlink:git-svnimport[1]::
- Import a SVN repository into git.
-
-gitlink:git-sh-setup[1]::
- Common git shell script setup code.
-
-gitlink:git-symbolic-ref[1]::
- Read and modify symbolic refs.
-
-gitlink:git-tag[1]::
- An example script to create a tag object signed with GPG.
-
-gitlink:git-update-ref[1]::
- Update the object name stored in a ref safely.
-
+include::cmds-ancillarymanipulators.txt[]
Interrogators:
-gitlink:git-annotate[1]::
- Annotate file lines with commit info.
-
-gitlink:git-blame[1]::
- Find out where each line in a file came from.
-
-gitlink:git-check-ref-format[1]::
- Make sure ref name is well formed.
-
-gitlink:git-cherry[1]::
- Find commits not merged upstream.
-
-gitlink:git-count-objects[1]::
- Count unpacked number of objects and their disk consumption.
-
-gitlink:git-daemon[1]::
- A really simple server for git repositories.
-
-gitlink:git-fmt-merge-msg[1]::
- Produce a merge commit message.
-
-gitlink:git-get-tar-commit-id[1]::
- Extract commit ID from an archive created using git-tar-tree.
-
-gitlink:git-imap-send[1]::
- Dump a mailbox from stdin into an imap folder.
-
-gitlink:git-instaweb[1]::
- Instantly browse your working repository in gitweb.
-
-gitlink:git-mailinfo[1]::
- Extracts patch and authorship information from a single
- e-mail message, optionally transliterating the commit
- message into utf-8.
-
-gitlink:git-mailsplit[1]::
- A stupid program to split UNIX mbox format mailbox into
- individual pieces of e-mail.
-
-gitlink:git-merge-tree[1]::
- Show three-way merge without touching index.
-
-gitlink:git-patch-id[1]::
- Compute unique ID for a patch.
-
-gitlink:git-parse-remote[1]::
- Routines to help parsing `$GIT_DIR/remotes/` files.
+include::cmds-ancillaryinterrogators.txt[]
-gitlink:git-request-pull[1]::
- git-request-pull.
-gitlink:git-rev-parse[1]::
- Pick out and massage parameters.
-
-gitlink:git-send-email[1]::
- Send patch e-mails out of "format-patch --mbox" output.
+Interacting with Others
+~~~~~~~~~~~~~~~~~~~~~~~
-gitlink:git-symbolic-ref[1]::
- Read and modify symbolic refs.
+These commands are to interact with foreign SCM and with other
+people via patch over e-mail.
-gitlink:git-stripspace[1]::
- Filter out empty lines.
+include::cmds-foreignscminterface.txt[]
Low-level commands (plumbing)
might start by reading about gitlink:git-update-index[1] and
gitlink:git-read-tree[1].
-We divide the low-level commands into commands that manipulate objects (in
+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.
+
Manipulation commands
~~~~~~~~~~~~~~~~~~~~~
-gitlink:git-apply[1]::
- Reads a "diff -up1" or git generated patch file and
- applies it to the working tree.
-
-gitlink:git-checkout-index[1]::
- Copy files from the index to the working tree.
-
-gitlink:git-commit-tree[1]::
- Creates a new commit object.
-
-gitlink:git-hash-object[1]::
- Computes the object ID from a file.
-
-gitlink:git-index-pack[1]::
- Build pack idx file for an existing packed archive.
-
-gitlink:git-init-db[1]::
- Creates an empty git object database, or reinitialize an
- existing one.
-
-gitlink:git-merge-index[1]::
- Runs a merge for files needing merging.
-
-gitlink:git-mktag[1]::
- Creates a tag object.
-
-gitlink:git-mktree[1]::
- Build a tree-object from ls-tree formatted text.
-
-gitlink:git-pack-objects[1]::
- Creates a packed archive of objects.
-
-gitlink:git-prune-packed[1]::
- Remove extra objects that are already in pack files.
-
-gitlink:git-read-tree[1]::
- Reads tree information into the index.
-
-gitlink:git-repo-config[1]::
- Get and set options in .git/config.
-gitlink:git-unpack-objects[1]::
- Unpacks objects out of a packed archive.
-
-gitlink:git-update-index[1]::
- Registers files in the working tree to the index.
-
-gitlink:git-write-tree[1]::
- Creates a tree from the index.
+include::cmds-plumbingmanipulators.txt[]
Interrogation commands
~~~~~~~~~~~~~~~~~~~~~~
-gitlink:git-cat-file[1]::
- Provide content or type/size information for repository objects.
-
-gitlink:git-describe[1]::
- Show the most recent tag that is reachable from a commit.
-
-gitlink:git-diff-index[1]::
- Compares content and mode of blobs between the index and repository.
-
-gitlink:git-diff-files[1]::
- Compares files in the working tree and the index.
-
-gitlink:git-diff-stages[1]::
- Compares two "merge stages" in the index.
-
-gitlink:git-diff-tree[1]::
- Compares the content and mode of blobs found via two tree objects.
-
-gitlink:git-for-each-ref[1]::
- Output information on each ref.
-
-gitlink:git-fsck-objects[1]::
- Verifies the connectivity and validity of the objects in the database.
-
-gitlink:git-ls-files[1]::
- Information about files in the index and the working tree.
-
-gitlink:git-ls-tree[1]::
- Displays a tree object in human readable form.
-
-gitlink:git-merge-base[1]::
- Finds as good common ancestors as possible for a merge.
-
-gitlink:git-name-rev[1]::
- Find symbolic names for given revs.
-
-gitlink:git-pack-redundant[1]::
- Find redundant pack files.
-
-gitlink:git-rev-list[1]::
- Lists commit objects in reverse chronological order.
-
-gitlink:git-show-index[1]::
- Displays contents of a pack idx file.
-
-gitlink:git-show-ref[1]::
- List references in a local repository.
-
-gitlink:git-tar-tree[1]::
- Creates a tar archive of the files in the named tree object.
-
-gitlink:git-unpack-file[1]::
- Creates a temporary file with a blob's contents.
-
-gitlink:git-var[1]::
- Displays a git logical variable.
-
-gitlink:git-verify-pack[1]::
- Validates packed git archive files.
+include::cmds-plumbinginterrogators.txt[]
In general, the interrogate commands do not touch the files in
the working tree.
Synching repositories
~~~~~~~~~~~~~~~~~~~~~
-gitlink:git-fetch-pack[1]::
- Updates from a remote repository (engine for ssh and
- local transport).
-
-gitlink:git-http-fetch[1]::
- Downloads a remote git repository via HTTP by walking
- commit chain.
-
-gitlink:git-local-fetch[1]::
- Duplicates another git repository on a local system by
- walking commit chain.
-
-gitlink:git-peek-remote[1]::
- Lists references on a remote repository using
- upload-pack protocol (engine for ssh and local
- transport).
-
-gitlink:git-receive-pack[1]::
- Invoked by 'git-send-pack' to receive what is pushed to it.
+include::cmds-synchingrepositories.txt[]
-gitlink:git-send-pack[1]::
- Pushes to a remote repository, intelligently.
+The following are helper programs used by the above; end users
+typically do not use them directly.
-gitlink:git-http-push[1]::
- Push missing objects using HTTP/DAV.
+include::cmds-synchelpers.txt[]
-gitlink:git-shell[1]::
- Restricted shell for GIT-only SSH access.
-gitlink:git-ssh-fetch[1]::
- Pulls from a remote repository over ssh connection by
- walking commit chain.
+Internal helper commands
+~~~~~~~~~~~~~~~~~~~~~~~~
-gitlink:git-ssh-upload[1]::
- Helper "server-side" program used by git-ssh-fetch.
+These are internal helper commands used by other commands; end
+users typically do not use them directly.
-gitlink:git-update-server-info[1]::
- Updates auxiliary information on a dumb server to help
- clients discover references and packs on it.
-
-gitlink:git-upload-archive[1]::
- Invoked by 'git-archive' to send a generated archive.
-
-gitlink:git-upload-pack[1]::
- Invoked by 'git-fetch-pack' to push
- what are asked for.
+include::cmds-purehelpers.txt[]
Configuration Mechanism
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`.
specifies a path to use instead of the default `.git`
for the base of the repository.
+'GIT_WORK_TREE'::
+ Set the path to the working tree. The value will not be
+ used in combination with repositories found automatically in
+ a .git directory (i.e. $GIT_DIR is not set).
+ This can also be controlled by the '--work-tree' command line
+ option and the core.worktree configuration variable.
+
git Commits
~~~~~~~~~~~
'GIT_AUTHOR_NAME'::
'GIT_AUTHOR_DATE'::
'GIT_COMMITTER_NAME'::
'GIT_COMMITTER_EMAIL'::
+'GIT_COMMITTER_DATE'::
+'EMAIL'::
see gitlink:git-commit-tree[1]
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'::
- see the "generating patches" section in :
- gitlink:git-diff-index[1];
- gitlink:git-diff-files[1];
- gitlink:git-diff-tree[1]
+ 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 SHA1 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>.
other
~~~~~
+'GIT_MERGE_VERBOSITY'::
+ A number controlling the amount of output shown by
+ the recursive merge strategy. Overrides merge.verbosity.
+ See gitlink:git-merge[1]
+
'GIT_PAGER'::
- This environment variable overrides `$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.
+
+'GIT_SSH'::
+ If this environment variable is set then gitlink:git-fetch[1]
+ and gitlink:git-push[1] will use this command instead
+ of `ssh` when they need to connect to a remote system.
+ The 'GIT_SSH' command will be given exactly two arguments:
+ the 'username@host' (or just 'host') from the URL and the
+ shell command to execute on that remote system.
++
+To pass options to the program that you want to list in GIT_SSH
+you will need to wrap the program and options into a shell script,
+then set GIT_SSH to refer to the shell script.
++
+Usually it is easier to configure any desired options through your
+personal `.ssh/config` file. Please consult your ssh documentation
+for further details.
+
+'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-whatchanged, etc., will force a flush of the output stream
+ after each commit-oriented 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'::
If this variable is set to "1", "2" or "true" (comparison
Discussion[[Discussion]]
------------------------
-include::README[]
+
+More detail on the following is available from the
+link:user-manual.html#git-concepts[git concepts chapter of the
+user-manual] and the link:core-tutorial.html[Core tutorial].
+
+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 heirarchies; 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 SHA1 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 SHA1 name of an object or the name of another ref. Refs
+with names beginning `ref/head/` contain the SHA1 name of the most
+recent commit (or "head") of a branch under developement. SHA1 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.
Authors
-------
* git's founding father is Linus Torvalds <torvalds@osdl.org>.
-* The current git nurse is Junio C Hamano <junkio@cox.net>.
+* The current git nurse is Junio C Hamano <gitster@pobox.com>.
* The git potty was written by Andres Ericsson <ae@op5.se>.
* General upbringing is handled by the git-list <git@vger.kernel.org>.
GIT
---
Part of the gitlink:git[7] suite
-