Documentation / git.txton commit Make for-each-ref's grab_date() support per-atom formatting (d392e71)
   1git(7)
   2======
   3
   4NAME
   5----
   6git - the stupid content tracker
   7
   8
   9SYNOPSIS
  10--------
  11[verse]
  12'git' [--version] [--exec-path[=GIT_EXEC_PATH]]
  13    [-p|--paginate|--no-pager]
  14    [--bare] [--git-dir=GIT_DIR] [--work-tree=GIT_WORK_TREE]
  15    [--help] COMMAND [ARGS]
  16
  17DESCRIPTION
  18-----------
  19Git is a fast, scalable, distributed revision control system with an
  20unusually rich command set that provides both high-level operations
  21and full access to internals.
  22
  23See this link:tutorial.html[tutorial] to get started, then see
  24link:everyday.html[Everyday Git] for a useful minimum set of commands, and
  25"man git-commandname" for documentation of each command.  CVS users may
  26also want to read link:cvs-migration.html[CVS migration].  See
  27link:user-manual.html[Git User's Manual] for a more in-depth
  28introduction.
  29
  30The COMMAND is either a name of a Git command (see below) or an alias
  31as defined in the configuration file (see gitlink:git-config[1]).
  32
  33Formatted and hyperlinked version of the latest git
  34documentation can be viewed at
  35`http://www.kernel.org/pub/software/scm/git/docs/`.
  36
  37ifdef::stalenotes[]
  38[NOTE]
  39============
  40
  41You are reading the documentation for the latest (possibly
  42unreleased) version of git, that is available from 'master'
  43branch of the `git.git` repository.
  44Documentation for older releases are available here:
  45
  46* link:v1.5.3/git.html[documentation for release 1.5.3]
  47
  48* release notes for
  49  link:RelNotes-1.5.3.2.txt[1.5.3.2],
  50  link:RelNotes-1.5.3.1.txt[1.5.3.1].
  51
  52* release notes for
  53  link:RelNotes-1.5.2.5.txt[1.5.2.5],
  54  link:RelNotes-1.5.2.4.txt[1.5.2.4],
  55  link:RelNotes-1.5.2.3.txt[1.5.2.3],
  56  link:RelNotes-1.5.2.2.txt[1.5.2.2],
  57  link:RelNotes-1.5.2.1.txt[1.5.2.1],
  58  link:RelNotes-1.5.2.txt[1.5.2].
  59
  60* link:v1.5.1.6/git.html[documentation for release 1.5.1.6]
  61
  62* release notes for
  63  link:RelNotes-1.5.1.6.txt[1.5.1.6],
  64  link:RelNotes-1.5.1.5.txt[1.5.1.5],
  65  link:RelNotes-1.5.1.4.txt[1.5.1.4],
  66  link:RelNotes-1.5.1.3.txt[1.5.1.3],
  67  link:RelNotes-1.5.1.2.txt[1.5.1.2],
  68  link:RelNotes-1.5.1.1.txt[1.5.1.1],
  69  link:RelNotes-1.5.1.txt[1.5.1].
  70
  71* link:v1.5.0.7/git.html[documentation for release 1.5.0.7]
  72
  73* release notes for
  74  link:RelNotes-1.5.0.7.txt[1.5.0.7],
  75  link:RelNotes-1.5.0.6.txt[1.5.0.6],
  76  link:RelNotes-1.5.0.5.txt[1.5.0.5],
  77  link:RelNotes-1.5.0.3.txt[1.5.0.3],
  78  link:RelNotes-1.5.0.2.txt[1.5.0.2],
  79  link:RelNotes-1.5.0.1.txt[1.5.0.1],
  80  link:RelNotes-1.5.0.txt[1.5.0].
  81
  82* documentation for release link:v1.4.4.4/git.html[1.4.4.4],
  83  link:v1.3.3/git.html[1.3.3],
  84  link:v1.2.6/git.html[1.2.6],
  85  link:v1.0.13/git.html[1.0.13].
  86
  87============
  88
  89endif::stalenotes[]
  90
  91OPTIONS
  92-------
  93--version::
  94        Prints the git suite version that the 'git' program came from.
  95
  96--help::
  97        Prints the synopsis and a list of the most commonly used
  98        commands.  If a git command is named this option will bring up
  99        the man-page for that command. If the option '--all' or '-a' is
 100        given then all available commands are printed.
 101
 102--exec-path::
 103        Path to wherever your core git programs are installed.
 104        This can also be controlled by setting the GIT_EXEC_PATH
 105        environment variable. If no path is given 'git' will print
 106        the current setting and then exit.
 107
 108-p|--paginate::
 109        Pipe all output into 'less' (or if set, $PAGER).
 110
 111--no-pager::
 112        Do not pipe git output into a pager.
 113
 114--git-dir=<path>::
 115        Set the path to the repository. This can also be controlled by
 116        setting the GIT_DIR environment variable.
 117
 118--work-tree=<path>::
 119        Set the path to the working tree.  The value will not be
 120        used in combination with repositories found automatically in
 121        a .git directory (i.e. $GIT_DIR is not set).
 122        This can also be controlled by setting the GIT_WORK_TREE
 123        environment variable and the core.worktree configuration
 124        variable.
 125
 126--bare::
 127        Treat the repository as a bare repository.  If GIT_DIR
 128        environment is not set, it is set to the current working
 129        directory.
 130
 131
 132FURTHER DOCUMENTATION
 133---------------------
 134
 135See the references above to get started using git.  The following is
 136probably more detail than necessary for a first-time user.
 137
 138The link:user-manual.html#git-concepts[git concepts chapter of the
 139user-manual] and the link:core-tutorial.html[Core tutorial] both provide
 140introductions to the underlying git architecture.
 141
 142See also the link:howto-index.html[howto] documents for some useful
 143examples.
 144
 145GIT COMMANDS
 146------------
 147
 148We divide git into high level ("porcelain") commands and low level
 149("plumbing") commands.
 150
 151High-level commands (porcelain)
 152-------------------------------
 153
 154We separate the porcelain commands into the main commands and some
 155ancillary user utilities.
 156
 157Main porcelain commands
 158~~~~~~~~~~~~~~~~~~~~~~~
 159
 160include::cmds-mainporcelain.txt[]
 161
 162Ancillary Commands
 163~~~~~~~~~~~~~~~~~~
 164Manipulators:
 165
 166include::cmds-ancillarymanipulators.txt[]
 167
 168Interrogators:
 169
 170include::cmds-ancillaryinterrogators.txt[]
 171
 172
 173Interacting with Others
 174~~~~~~~~~~~~~~~~~~~~~~~
 175
 176These commands are to interact with foreign SCM and with other
 177people via patch over e-mail.
 178
 179include::cmds-foreignscminterface.txt[]
 180
 181
 182Low-level commands (plumbing)
 183-----------------------------
 184
 185Although git includes its
 186own porcelain layer, its low-level commands are sufficient to support
 187development of alternative porcelains.  Developers of such porcelains
 188might start by reading about gitlink:git-update-index[1] and
 189gitlink:git-read-tree[1].
 190
 191The interface (input, output, set of options and the semantics)
 192to these low-level commands are meant to be a lot more stable
 193than Porcelain level commands, because these commands are
 194primarily for scripted use.  The interface to Porcelain commands
 195on the other hand are subject to change in order to improve the
 196end user experience.
 197
 198The following description divides
 199the low-level commands into commands that manipulate objects (in
 200the repository, index, and working tree), commands that interrogate and
 201compare objects, and commands that move objects and references between
 202repositories.
 203
 204
 205Manipulation commands
 206~~~~~~~~~~~~~~~~~~~~~
 207
 208include::cmds-plumbingmanipulators.txt[]
 209
 210
 211Interrogation commands
 212~~~~~~~~~~~~~~~~~~~~~~
 213
 214include::cmds-plumbinginterrogators.txt[]
 215
 216In general, the interrogate commands do not touch the files in
 217the working tree.
 218
 219
 220Synching repositories
 221~~~~~~~~~~~~~~~~~~~~~
 222
 223include::cmds-synchingrepositories.txt[]
 224
 225The following are helper programs used by the above; end users
 226typically do not use them directly.
 227
 228include::cmds-synchelpers.txt[]
 229
 230
 231Internal helper commands
 232~~~~~~~~~~~~~~~~~~~~~~~~
 233
 234These are internal helper commands used by other commands; end
 235users typically do not use them directly.
 236
 237include::cmds-purehelpers.txt[]
 238
 239
 240Configuration Mechanism
 241-----------------------
 242
 243Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
 244is used to hold per-repository configuration options.  It is a
 245simple text file modeled after `.ini` format familiar to some
 246people.  Here is an example:
 247
 248------------
 249#
 250# A '#' or ';' character indicates a comment.
 251#
 252
 253; core variables
 254[core]
 255        ; Don't trust file modes
 256        filemode = false
 257
 258; user identity
 259[user]
 260        name = "Junio C Hamano"
 261        email = "junkio@twinsun.com"
 262
 263------------
 264
 265Various commands read from the configuration file and adjust
 266their operation accordingly.
 267
 268
 269Identifier Terminology
 270----------------------
 271<object>::
 272        Indicates the object name for any type of object.
 273
 274<blob>::
 275        Indicates a blob object name.
 276
 277<tree>::
 278        Indicates a tree object name.
 279
 280<commit>::
 281        Indicates a commit object name.
 282
 283<tree-ish>::
 284        Indicates a tree, commit or tag object name.  A
 285        command that takes a <tree-ish> argument ultimately wants to
 286        operate on a <tree> object but automatically dereferences
 287        <commit> and <tag> objects that point at a <tree>.
 288
 289<commit-ish>::
 290        Indicates a commit or tag object name.  A
 291        command that takes a <commit-ish> argument ultimately wants to
 292        operate on a <commit> object but automatically dereferences
 293        <tag> objects that point at a <commit>.
 294
 295<type>::
 296        Indicates that an object type is required.
 297        Currently one of: `blob`, `tree`, `commit`, or `tag`.
 298
 299<file>::
 300        Indicates a filename - almost always relative to the
 301        root of the tree structure `GIT_INDEX_FILE` describes.
 302
 303Symbolic Identifiers
 304--------------------
 305Any git command accepting any <object> can also use the following
 306symbolic notation:
 307
 308HEAD::
 309        indicates the head of the current branch (i.e. the
 310        contents of `$GIT_DIR/HEAD`).
 311
 312<tag>::
 313        a valid tag 'name'
 314        (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
 315
 316<head>::
 317        a valid head 'name'
 318        (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
 319
 320For a more complete list of ways to spell object names, see
 321"SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1].
 322
 323
 324File/Directory Structure
 325------------------------
 326
 327Please see link:repository-layout.html[repository layout] document.
 328
 329Read link:hooks.html[hooks] for more details about each hook.
 330
 331Higher level SCMs may provide and manage additional information in the
 332`$GIT_DIR`.
 333
 334
 335Terminology
 336-----------
 337Please see link:glossary.html[glossary] document.
 338
 339
 340Environment Variables
 341---------------------
 342Various git commands use the following environment variables:
 343
 344The git Repository
 345~~~~~~~~~~~~~~~~~~
 346These environment variables apply to 'all' core git commands. Nb: it
 347is worth noting that they may be used/overridden by SCMS sitting above
 348git so take care if using Cogito etc.
 349
 350'GIT_INDEX_FILE'::
 351        This environment allows the specification of an alternate
 352        index file. If not specified, the default of `$GIT_DIR/index`
 353        is used.
 354
 355'GIT_OBJECT_DIRECTORY'::
 356        If the object storage directory is specified via this
 357        environment variable then the sha1 directories are created
 358        underneath - otherwise the default `$GIT_DIR/objects`
 359        directory is used.
 360
 361'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 362        Due to the immutable nature of git objects, old objects can be
 363        archived into shared, read-only directories. This variable
 364        specifies a ":" separated list of git object directories which
 365        can be used to search for git objects. New objects will not be
 366        written to these directories.
 367
 368'GIT_DIR'::
 369        If the 'GIT_DIR' environment variable is set then it
 370        specifies a path to use instead of the default `.git`
 371        for the base of the repository.
 372
 373'GIT_WORK_TREE'::
 374        Set the path to the working tree.  The value will not be
 375        used in combination with repositories found automatically in
 376        a .git directory (i.e. $GIT_DIR is not set).
 377        This can also be controlled by the '--work-tree' command line
 378        option and the core.worktree configuration variable.
 379
 380git Commits
 381~~~~~~~~~~~
 382'GIT_AUTHOR_NAME'::
 383'GIT_AUTHOR_EMAIL'::
 384'GIT_AUTHOR_DATE'::
 385'GIT_COMMITTER_NAME'::
 386'GIT_COMMITTER_EMAIL'::
 387'GIT_COMMITTER_DATE'::
 388'EMAIL'::
 389        see gitlink:git-commit-tree[1]
 390
 391git Diffs
 392~~~~~~~~~
 393'GIT_DIFF_OPTS'::
 394        Only valid setting is "--unified=??" or "-u??" to set the
 395        number of context lines shown when a unified diff is created.
 396        This takes precedence over any "-U" or "--unified" option
 397        value passed on the git diff command line.
 398
 399'GIT_EXTERNAL_DIFF'::
 400        When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
 401        program named by it is called, instead of the diff invocation
 402        described above.  For a path that is added, removed, or modified,
 403        'GIT_EXTERNAL_DIFF' is called with 7 parameters:
 404
 405        path old-file old-hex old-mode new-file new-hex new-mode
 406+
 407where:
 408
 409        <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
 410                         contents of <old|new>,
 411        <old|new>-hex:: are the 40-hexdigit SHA1 hashes,
 412        <old|new>-mode:: are the octal representation of the file modes.
 413
 414+
 415The file parameters can point at the user's working file
 416(e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
 417when a new file is added), or a temporary file (e.g. `old-file` in the
 418index).  'GIT_EXTERNAL_DIFF' should not worry about unlinking the
 419temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
 420+
 421For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
 422parameter, <path>.
 423
 424other
 425~~~~~
 426'GIT_MERGE_VERBOSITY'::
 427        A number controlling the amount of output shown by
 428        the recursive merge strategy.  Overrides merge.verbosity.
 429        See gitlink:git-merge[1]
 430
 431'GIT_PAGER'::
 432        This environment variable overrides `$PAGER`. If it is set
 433        to an empty string or to the value "cat", git will not launch
 434        a pager.
 435
 436'GIT_SSH'::
 437        If this environment variable is set then gitlink:git-fetch[1]
 438        and gitlink:git-push[1] will use this command instead
 439        of `ssh` when they need to connect to a remote system.
 440        The 'GIT_SSH' command will be given exactly two arguments:
 441        the 'username@host' (or just 'host') from the URL and the
 442        shell command to execute on that remote system.
 443+
 444To pass options to the program that you want to list in GIT_SSH
 445you will need to wrap the program and options into a shell script,
 446then set GIT_SSH to refer to the shell script.
 447+
 448Usually it is easier to configure any desired options through your
 449personal `.ssh/config` file.  Please consult your ssh documentation
 450for further details.
 451
 452'GIT_FLUSH'::
 453        If this environment variable is set to "1", then commands such
 454        as git-blame (in incremental mode), git-rev-list, git-log,
 455        git-whatchanged, etc., will force a flush of the output stream
 456        after each commit-oriented record have been flushed.   If this
 457        variable is set to "0", the output of these commands will be done
 458        using completely buffered I/O.   If this environment variable is
 459        not set, git will choose buffered or record-oriented flushing
 460        based on whether stdout appears to be redirected to a file or not.
 461
 462'GIT_TRACE'::
 463        If this variable is set to "1", "2" or "true" (comparison
 464        is case insensitive), git will print `trace:` messages on
 465        stderr telling about alias expansion, built-in command
 466        execution and external command execution.
 467        If this variable is set to an integer value greater than 1
 468        and lower than 10 (strictly) then git will interpret this
 469        value as an open file descriptor and will try to write the
 470        trace messages into this file descriptor.
 471        Alternatively, if this variable is set to an absolute path
 472        (starting with a '/' character), git will interpret this
 473        as a file path and will try to write the trace messages
 474        into it.
 475
 476Discussion[[Discussion]]
 477------------------------
 478
 479More detail on the following is available from the
 480link:user-manual.html#git-concepts[git concepts chapter of the
 481user-manual] and the link:core-tutorial.html[Core tutorial].
 482
 483A git project normally consists of a working directory with a ".git"
 484subdirectory at the top level.  The .git directory contains, among other
 485things, a compressed object database representing the complete history
 486of the project, an "index" file which links that history to the current
 487contents of the working tree, and named pointers into that history such
 488as tags and branch heads.
 489
 490The object database contains objects of three main types: blobs, which
 491hold file data; trees, which point to blobs and other trees to build up
 492directory heirarchies; and commits, which each reference a single tree
 493and some number of parent commits.
 494
 495The commit, equivalent to what other systems call a "changeset" or
 496"version", represents a step in the project's history, and each parent
 497represents an immediately preceding step.  Commits with more than one
 498parent represent merges of independent lines of development.
 499
 500All objects are named by the SHA1 hash of their contents, normally
 501written as a string of 40 hex digits.  Such names are globally unique.
 502The entire history leading up to a commit can be vouched for by signing
 503just that commit.  A fourth object type, the tag, is provided for this
 504purpose.
 505
 506When first created, objects are stored in individual files, but for
 507efficiency may later be compressed together into "pack files".
 508
 509Named pointers called refs mark interesting points in history.  A ref
 510may contain the SHA1 name of an object or the name of another ref.  Refs
 511with names beginning `ref/head/` contain the SHA1 name of the most
 512recent commit (or "head") of a branch under developement.  SHA1 names of
 513tags of interest are stored under `ref/tags/`.  A special ref named
 514`HEAD` contains the name of the currently checked-out branch.
 515
 516The index file is initialized with a list of all paths and, for each
 517path, a blob object and a set of attributes.  The blob object represents
 518the contents of the file as of the head of the current branch.  The
 519attributes (last modified time, size, etc.) are taken from the
 520corresponding file in the working tree.  Subsequent changes to the
 521working tree can be found by comparing these attributes.  The index may
 522be updated with new content, and new commits may be created from the
 523content stored in the index.
 524
 525The index is also capable of storing multiple entries (called "stages")
 526for a given pathname.  These stages are used to hold the various
 527unmerged version of a file when a merge is in progress.
 528
 529Authors
 530-------
 531* git's founding father is Linus Torvalds <torvalds@osdl.org>.
 532* The current git nurse is Junio C Hamano <gitster@pobox.com>.
 533* The git potty was written by Andres Ericsson <ae@op5.se>.
 534* General upbringing is handled by the git-list <git@vger.kernel.org>.
 535
 536Documentation
 537--------------
 538The documentation for git suite was started by David Greaves
 539<david@dgreaves.com>, and later enhanced greatly by the
 540contributors on the git-list <git@vger.kernel.org>.
 541
 542GIT
 543---
 544Part of the gitlink:git[7] suite