Documentation/git.txt

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