Documentation/git.txt

   1 git(1)
   2 ======
   3
   4 NAME
   5 ----
   6 git - the stupid content tracker
   7
   8
   9 SYNOPSIS
  10 --------
  11 [verse]
  12 'git' [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
  13     [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
  14     [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
  15     [-c <name>=<value>]
  16     [--help] <command> [<args>]
  17
  18 DESCRIPTION
  19 -----------
  20 Git is a fast, scalable, distributed revision control system with an
  21 unusually rich command set that provides both high-level operations
  22 and full access to internals.
  23
  24 See linkgit:gittutorial[7] to get started, then see
  25 link:everyday.html[Everyday Git] for a useful minimum set of commands, and
  26 "man git-commandname" for documentation of each command.  CVS users may
  27 also want to read linkgit:gitcvs-migration[7].  See
  28 the link:user-manual.html[Git User's Manual] for a more in-depth
  29 introduction.
  30
  31 The '<command>' is either a name of a Git command (see below) or an alias
  32 as defined in the configuration file (see linkgit:git-config[1]).
  33
  34 Formatted and hyperlinked version of the latest git
  35 documentation can be viewed at
  36 `http://www.kernel.org/pub/software/scm/git/docs/`.
  37
  38 ifdef::stalenotes[]
  39 [NOTE]
  40 ============
  41
  42 You are reading the documentation for the latest (possibly
  43 unreleased) version of git, that is available from 'master'
  44 branch of the `git.git` repository.
  45 Documentation for older releases are available here:
  46
  47 * link:v1.7.8.6/git.html[documentation for release 1.7.8.6]
  48
  49 * release notes for
  50   link:RelNotes/1.7.8.6.txt[1.7.8.6],
  51   link:RelNotes/1.7.8.5.txt[1.7.8.5],
  52   link:RelNotes/1.7.8.4.txt[1.7.8.4],
  53   link:RelNotes/1.7.8.3.txt[1.7.8.3],
  54   link:RelNotes/1.7.8.2.txt[1.7.8.2],
  55   link:RelNotes/1.7.8.1.txt[1.7.8.1],
  56   link:RelNotes/1.7.8.txt[1.7.8].
  57
  58 * link:v1.7.7.7/git.html[documentation for release 1.7.7.7]
  59
  60 * release notes for
  61   link:RelNotes/1.7.7.7.txt[1.7.7.7],
  62   link:RelNotes/1.7.7.6.txt[1.7.7.6],
  63   link:RelNotes/1.7.7.5.txt[1.7.7.5],
  64   link:RelNotes/1.7.7.4.txt[1.7.7.4],
  65   link:RelNotes/1.7.7.3.txt[1.7.7.3],
  66   link:RelNotes/1.7.7.2.txt[1.7.7.2],
  67   link:RelNotes/1.7.7.1.txt[1.7.7.1],
  68   link:RelNotes/1.7.7.txt[1.7.7].
  69
  70 * link:v1.7.6.6/git.html[documentation for release 1.7.6.6]
  71
  72 * release notes for
  73   link:RelNotes/1.7.6.6.txt[1.7.6.6],
  74   link:RelNotes/1.7.6.5.txt[1.7.6.5],
  75   link:RelNotes/1.7.6.4.txt[1.7.6.4],
  76   link:RelNotes/1.7.6.3.txt[1.7.6.3],
  77   link:RelNotes/1.7.6.2.txt[1.7.6.2],
  78   link:RelNotes/1.7.6.1.txt[1.7.6.1],
  79   link:RelNotes/1.7.6.txt[1.7.6].
  80
  81 * link:v1.7.5.4/git.html[documentation for release 1.7.5.4]
  82
  83 * release notes for
  84   link:RelNotes/1.7.5.4.txt[1.7.5.4],
  85   link:RelNotes/1.7.5.3.txt[1.7.5.3],
  86   link:RelNotes/1.7.5.2.txt[1.7.5.2],
  87   link:RelNotes/1.7.5.1.txt[1.7.5.1],
  88   link:RelNotes/1.7.5.txt[1.7.5].
  89
  90 * link:v1.7.4.5/git.html[documentation for release 1.7.4.5]
  91
  92 * release notes for
  93   link:RelNotes/1.7.4.5.txt[1.7.4.5],
  94   link:RelNotes/1.7.4.4.txt[1.7.4.4],
  95   link:RelNotes/1.7.4.3.txt[1.7.4.3],
  96   link:RelNotes/1.7.4.2.txt[1.7.4.2],
  97   link:RelNotes/1.7.4.1.txt[1.7.4.1],
  98   link:RelNotes/1.7.4.txt[1.7.4].
  99
 100 * link:v1.7.3.5/git.html[documentation for release 1.7.3.5]
 101
 102 * release notes for
 103   link:RelNotes/1.7.3.5.txt[1.7.3.5],
 104   link:RelNotes/1.7.3.4.txt[1.7.3.4],
 105   link:RelNotes/1.7.3.3.txt[1.7.3.3],
 106   link:RelNotes/1.7.3.2.txt[1.7.3.2],
 107   link:RelNotes/1.7.3.1.txt[1.7.3.1],
 108   link:RelNotes/1.7.3.txt[1.7.3].
 109
 110 * link:v1.7.2.5/git.html[documentation for release 1.7.2.5]
 111
 112 * release notes for
 113   link:RelNotes/1.7.2.5.txt[1.7.2.5],
 114   link:RelNotes/1.7.2.4.txt[1.7.2.4],
 115   link:RelNotes/1.7.2.3.txt[1.7.2.3],
 116   link:RelNotes/1.7.2.2.txt[1.7.2.2],
 117   link:RelNotes/1.7.2.1.txt[1.7.2.1],
 118   link:RelNotes/1.7.2.txt[1.7.2].
 119
 120 * link:v1.7.1.4/git.html[documentation for release 1.7.1.4]
 121
 122 * release notes for
 123   link:RelNotes/1.7.1.4.txt[1.7.1.4],
 124   link:RelNotes/1.7.1.3.txt[1.7.1.3],
 125   link:RelNotes/1.7.1.2.txt[1.7.1.2],
 126   link:RelNotes/1.7.1.1.txt[1.7.1.1],
 127   link:RelNotes/1.7.1.txt[1.7.1].
 128
 129 * link:v1.7.0.9/git.html[documentation for release 1.7.0.9]
 130
 131 * release notes for
 132   link:RelNotes/1.7.0.9.txt[1.7.0.9],
 133   link:RelNotes/1.7.0.8.txt[1.7.0.8],
 134   link:RelNotes/1.7.0.7.txt[1.7.0.7],
 135   link:RelNotes/1.7.0.6.txt[1.7.0.6],
 136   link:RelNotes/1.7.0.5.txt[1.7.0.5],
 137   link:RelNotes/1.7.0.4.txt[1.7.0.4],
 138   link:RelNotes/1.7.0.3.txt[1.7.0.3],
 139   link:RelNotes/1.7.0.2.txt[1.7.0.2],
 140   link:RelNotes/1.7.0.1.txt[1.7.0.1],
 141   link:RelNotes/1.7.0.txt[1.7.0].
 142
 143 * link:v1.6.6.3/git.html[documentation for release 1.6.6.3]
 144
 145 * release notes for
 146   link:RelNotes/1.6.6.3.txt[1.6.6.3],
 147   link:RelNotes/1.6.6.2.txt[1.6.6.2],
 148   link:RelNotes/1.6.6.1.txt[1.6.6.1],
 149   link:RelNotes/1.6.6.txt[1.6.6].
 150
 151 * link:v1.6.5.9/git.html[documentation for release 1.6.5.9]
 152
 153 * release notes for
 154   link:RelNotes/1.6.5.9.txt[1.6.5.9],
 155   link:RelNotes/1.6.5.8.txt[1.6.5.8],
 156   link:RelNotes/1.6.5.7.txt[1.6.5.7],
 157   link:RelNotes/1.6.5.6.txt[1.6.5.6],
 158   link:RelNotes/1.6.5.5.txt[1.6.5.5],
 159   link:RelNotes/1.6.5.4.txt[1.6.5.4],
 160   link:RelNotes/1.6.5.3.txt[1.6.5.3],
 161   link:RelNotes/1.6.5.2.txt[1.6.5.2],
 162   link:RelNotes/1.6.5.1.txt[1.6.5.1],
 163   link:RelNotes/1.6.5.txt[1.6.5].
 164
 165 * link:v1.6.4.5/git.html[documentation for release 1.6.4.5]
 166
 167 * release notes for
 168   link:RelNotes/1.6.4.5.txt[1.6.4.5],
 169   link:RelNotes/1.6.4.4.txt[1.6.4.4],
 170   link:RelNotes/1.6.4.3.txt[1.6.4.3],
 171   link:RelNotes/1.6.4.2.txt[1.6.4.2],
 172   link:RelNotes/1.6.4.1.txt[1.6.4.1],
 173   link:RelNotes/1.6.4.txt[1.6.4].
 174
 175 * link:v1.6.3.4/git.html[documentation for release 1.6.3.4]
 176
 177 * release notes for
 178   link:RelNotes/1.6.3.4.txt[1.6.3.4],
 179   link:RelNotes/1.6.3.3.txt[1.6.3.3],
 180   link:RelNotes/1.6.3.2.txt[1.6.3.2],
 181   link:RelNotes/1.6.3.1.txt[1.6.3.1],
 182   link:RelNotes/1.6.3.txt[1.6.3].
 183
 184 * release notes for
 185   link:RelNotes/1.6.2.5.txt[1.6.2.5],
 186   link:RelNotes/1.6.2.4.txt[1.6.2.4],
 187   link:RelNotes/1.6.2.3.txt[1.6.2.3],
 188   link:RelNotes/1.6.2.2.txt[1.6.2.2],
 189   link:RelNotes/1.6.2.1.txt[1.6.2.1],
 190   link:RelNotes/1.6.2.txt[1.6.2].
 191
 192 * link:v1.6.1.3/git.html[documentation for release 1.6.1.3]
 193
 194 * release notes for
 195   link:RelNotes/1.6.1.3.txt[1.6.1.3],
 196   link:RelNotes/1.6.1.2.txt[1.6.1.2],
 197   link:RelNotes/1.6.1.1.txt[1.6.1.1],
 198   link:RelNotes/1.6.1.txt[1.6.1].
 199
 200 * link:v1.6.0.6/git.html[documentation for release 1.6.0.6]
 201
 202 * release notes for
 203   link:RelNotes/1.6.0.6.txt[1.6.0.6],
 204   link:RelNotes/1.6.0.5.txt[1.6.0.5],
 205   link:RelNotes/1.6.0.4.txt[1.6.0.4],
 206   link:RelNotes/1.6.0.3.txt[1.6.0.3],
 207   link:RelNotes/1.6.0.2.txt[1.6.0.2],
 208   link:RelNotes/1.6.0.1.txt[1.6.0.1],
 209   link:RelNotes/1.6.0.txt[1.6.0].
 210
 211 * link:v1.5.6.6/git.html[documentation for release 1.5.6.6]
 212
 213 * release notes for
 214   link:RelNotes/1.5.6.6.txt[1.5.6.6],
 215   link:RelNotes/1.5.6.5.txt[1.5.6.5],
 216   link:RelNotes/1.5.6.4.txt[1.5.6.4],
 217   link:RelNotes/1.5.6.3.txt[1.5.6.3],
 218   link:RelNotes/1.5.6.2.txt[1.5.6.2],
 219   link:RelNotes/1.5.6.1.txt[1.5.6.1],
 220   link:RelNotes/1.5.6.txt[1.5.6].
 221
 222 * link:v1.5.5.6/git.html[documentation for release 1.5.5.6]
 223
 224 * release notes for
 225   link:RelNotes/1.5.5.6.txt[1.5.5.6],
 226   link:RelNotes/1.5.5.5.txt[1.5.5.5],
 227   link:RelNotes/1.5.5.4.txt[1.5.5.4],
 228   link:RelNotes/1.5.5.3.txt[1.5.5.3],
 229   link:RelNotes/1.5.5.2.txt[1.5.5.2],
 230   link:RelNotes/1.5.5.1.txt[1.5.5.1],
 231   link:RelNotes/1.5.5.txt[1.5.5].
 232
 233 * link:v1.5.4.7/git.html[documentation for release 1.5.4.7]
 234
 235 * release notes for
 236   link:RelNotes/1.5.4.7.txt[1.5.4.7],
 237   link:RelNotes/1.5.4.6.txt[1.5.4.6],
 238   link:RelNotes/1.5.4.5.txt[1.5.4.5],
 239   link:RelNotes/1.5.4.4.txt[1.5.4.4],
 240   link:RelNotes/1.5.4.3.txt[1.5.4.3],
 241   link:RelNotes/1.5.4.2.txt[1.5.4.2],
 242   link:RelNotes/1.5.4.1.txt[1.5.4.1],
 243   link:RelNotes/1.5.4.txt[1.5.4].
 244
 245 * link:v1.5.3.8/git.html[documentation for release 1.5.3.8]
 246
 247 * release notes for
 248   link:RelNotes/1.5.3.8.txt[1.5.3.8],
 249   link:RelNotes/1.5.3.7.txt[1.5.3.7],
 250   link:RelNotes/1.5.3.6.txt[1.5.3.6],
 251   link:RelNotes/1.5.3.5.txt[1.5.3.5],
 252   link:RelNotes/1.5.3.4.txt[1.5.3.4],
 253   link:RelNotes/1.5.3.3.txt[1.5.3.3],
 254   link:RelNotes/1.5.3.2.txt[1.5.3.2],
 255   link:RelNotes/1.5.3.1.txt[1.5.3.1],
 256   link:RelNotes/1.5.3.txt[1.5.3].
 257
 258 * link:v1.5.2.5/git.html[documentation for release 1.5.2.5]
 259
 260 * release notes for
 261   link:RelNotes/1.5.2.5.txt[1.5.2.5],
 262   link:RelNotes/1.5.2.4.txt[1.5.2.4],
 263   link:RelNotes/1.5.2.3.txt[1.5.2.3],
 264   link:RelNotes/1.5.2.2.txt[1.5.2.2],
 265   link:RelNotes/1.5.2.1.txt[1.5.2.1],
 266   link:RelNotes/1.5.2.txt[1.5.2].
 267
 268 * link:v1.5.1.6/git.html[documentation for release 1.5.1.6]
 269
 270 * release notes for
 271   link:RelNotes/1.5.1.6.txt[1.5.1.6],
 272   link:RelNotes/1.5.1.5.txt[1.5.1.5],
 273   link:RelNotes/1.5.1.4.txt[1.5.1.4],
 274   link:RelNotes/1.5.1.3.txt[1.5.1.3],
 275   link:RelNotes/1.5.1.2.txt[1.5.1.2],
 276   link:RelNotes/1.5.1.1.txt[1.5.1.1],
 277   link:RelNotes/1.5.1.txt[1.5.1].
 278
 279 * link:v1.5.0.7/git.html[documentation for release 1.5.0.7]
 280
 281 * release notes for
 282   link:RelNotes/1.5.0.7.txt[1.5.0.7],
 283   link:RelNotes/1.5.0.6.txt[1.5.0.6],
 284   link:RelNotes/1.5.0.5.txt[1.5.0.5],
 285   link:RelNotes/1.5.0.3.txt[1.5.0.3],
 286   link:RelNotes/1.5.0.2.txt[1.5.0.2],
 287   link:RelNotes/1.5.0.1.txt[1.5.0.1],
 288   link:RelNotes/1.5.0.txt[1.5.0].
 289
 290 * documentation for release link:v1.4.4.4/git.html[1.4.4.4],
 291   link:v1.3.3/git.html[1.3.3],
 292   link:v1.2.6/git.html[1.2.6],
 293   link:v1.0.13/git.html[1.0.13].
 294
 295 ============
 296
 297 endif::stalenotes[]
 298
 299 OPTIONS
 300 -------
 301 --version::
 302         Prints the git suite version that the 'git' program came from.
 303
 304 --help::
 305         Prints the synopsis and a list of the most commonly used
 306         commands. If the option '--all' or '-a' is given then all
 307         available commands are printed. If a git command is named this
 308         option will bring up the manual page for that command.
 309 +
 310 Other options are available to control how the manual page is
 311 displayed. See linkgit:git-help[1] for more information,
 312 because `git --help ...` is converted internally into `git
 313 help ...`.
 314
 315 -c <name>=<value>::
 316         Pass a configuration parameter to the command. The value
 317         given will override values from configuration files.
 318         The <name> is expected in the same format as listed by
 319         'git config' (subkeys separated by dots).
 320
 321 --exec-path[=<path>]::
 322         Path to wherever your core git programs are installed.
 323         This can also be controlled by setting the GIT_EXEC_PATH
 324         environment variable. If no path is given, 'git' will print
 325         the current setting and then exit.
 326
 327 --html-path::
 328         Print the path, without trailing slash, where git's HTML
 329         documentation is installed and exit.
 330
 331 --man-path::
 332         Print the manpath (see `man(1)`) for the man pages for
 333         this version of git and exit.
 334
 335 --info-path::
 336         Print the path where the Info files documenting this
 337         version of git are installed and exit.
 338
 339 -p::
 340 --paginate::
 341         Pipe all output into 'less' (or if set, $PAGER) if standard
 342         output is a terminal.  This overrides the `pager.<cmd>`
 343         configuration options (see the "Configuration Mechanism" section
 344         below).
 345
 346 --no-pager::
 347         Do not pipe git output into a pager.
 348
 349 --git-dir=<path>::
 350         Set the path to the repository. This can also be controlled by
 351         setting the GIT_DIR environment variable. It can be an absolute
 352         path or relative path to current working directory.
 353
 354 --work-tree=<path>::
 355         Set the path to the working tree. It can be an absolute path
 356         or a path relative to the current working directory.
 357         This can also be controlled by setting the GIT_WORK_TREE
 358         environment variable and the core.worktree configuration
 359         variable (see core.worktree in linkgit:git-config[1] for a
 360         more detailed discussion).
 361
 362 --namespace=<path>::
 363         Set the git namespace.  See linkgit:gitnamespaces[7] for more
 364         details.  Equivalent to setting the `GIT_NAMESPACE` environment
 365         variable.
 366
 367 --bare::
 368         Treat the repository as a bare repository.  If GIT_DIR
 369         environment is not set, it is set to the current working
 370         directory.
 371
 372 --no-replace-objects::
 373         Do not use replacement refs to replace git objects. See
 374         linkgit:git-replace[1] for more information.
 375
 376
 377 FURTHER DOCUMENTATION
 378 ---------------------
 379
 380 See the references above to get started using git.  The following is
 381 probably more detail than necessary for a first-time user.
 382
 383 The link:user-manual.html#git-concepts[git concepts chapter of the
 384 user-manual] and linkgit:gitcore-tutorial[7] both provide
 385 introductions to the underlying git architecture.
 386
 387 See linkgit:gitworkflows[7] for an overview of recommended workflows.
 388
 389 See also the link:howto-index.html[howto] documents for some useful
 390 examples.
 391
 392 The internals are documented in the
 393 link:technical/api-index.html[GIT API documentation].
 394
 395 GIT COMMANDS
 396 ------------
 397
 398 We divide git into high level ("porcelain") commands and low level
 399 ("plumbing") commands.
 400
 401 High-level commands (porcelain)
 402 -------------------------------
 403
 404 We separate the porcelain commands into the main commands and some
 405 ancillary user utilities.
 406
 407 Main porcelain commands
 408 ~~~~~~~~~~~~~~~~~~~~~~~
 409
 410 include::cmds-mainporcelain.txt[]
 411
 412 Ancillary Commands
 413 ~~~~~~~~~~~~~~~~~~
 414 Manipulators:
 415
 416 include::cmds-ancillarymanipulators.txt[]
 417
 418 Interrogators:
 419
 420 include::cmds-ancillaryinterrogators.txt[]
 421
 422
 423 Interacting with Others
 424 ~~~~~~~~~~~~~~~~~~~~~~~
 425
 426 These commands are to interact with foreign SCM and with other
 427 people via patch over e-mail.
 428
 429 include::cmds-foreignscminterface.txt[]
 430
 431
 432 Low-level commands (plumbing)
 433 -----------------------------
 434
 435 Although git includes its
 436 own porcelain layer, its low-level commands are sufficient to support
 437 development of alternative porcelains.  Developers of such porcelains
 438 might start by reading about linkgit:git-update-index[1] and
 439 linkgit:git-read-tree[1].
 440
 441 The interface (input, output, set of options and the semantics)
 442 to these low-level commands are meant to be a lot more stable
 443 than Porcelain level commands, because these commands are
 444 primarily for scripted use.  The interface to Porcelain commands
 445 on the other hand are subject to change in order to improve the
 446 end user experience.
 447
 448 The following description divides
 449 the low-level commands into commands that manipulate objects (in
 450 the repository, index, and working tree), commands that interrogate and
 451 compare objects, and commands that move objects and references between
 452 repositories.
 453
 454
 455 Manipulation commands
 456 ~~~~~~~~~~~~~~~~~~~~~
 457
 458 include::cmds-plumbingmanipulators.txt[]
 459
 460
 461 Interrogation commands
 462 ~~~~~~~~~~~~~~~~~~~~~~
 463
 464 include::cmds-plumbinginterrogators.txt[]
 465
 466 In general, the interrogate commands do not touch the files in
 467 the working tree.
 468
 469
 470 Synching repositories
 471 ~~~~~~~~~~~~~~~~~~~~~
 472
 473 include::cmds-synchingrepositories.txt[]
 474
 475 The following are helper commands used by the above; end users
 476 typically do not use them directly.
 477
 478 include::cmds-synchelpers.txt[]
 479
 480
 481 Internal helper commands
 482 ~~~~~~~~~~~~~~~~~~~~~~~~
 483
 484 These are internal helper commands used by other commands; end
 485 users typically do not use them directly.
 486
 487 include::cmds-purehelpers.txt[]
 488
 489
 490 Configuration Mechanism
 491 -----------------------
 492
 493 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
 494 is used to hold per-repository configuration options.  It is a
 495 simple text file modeled after `.ini` format familiar to some
 496 people.  Here is an example:
 497
 498 ------------
 499 #
 500 # A '#' or ';' character indicates a comment.
 501 #
 502
 503 ; core variables
 504 [core]
 505         ; Don't trust file modes
 506         filemode = false
 507
 508 ; user identity
 509 [user]
 510         name = "Junio C Hamano"
 511         email = "junkio@twinsun.com"
 512
 513 ------------
 514
 515 Various commands read from the configuration file and adjust
 516 their operation accordingly.  See linkgit:git-config[1] for a
 517 list.
 518
 519
 520 Identifier Terminology
 521 ----------------------
 522 <object>::
 523         Indicates the object name for any type of object.
 524
 525 <blob>::
 526         Indicates a blob object name.
 527
 528 <tree>::
 529         Indicates a tree object name.
 530
 531 <commit>::
 532         Indicates a commit object name.
 533
 534 <tree-ish>::
 535         Indicates a tree, commit or tag object name.  A
 536         command that takes a <tree-ish> argument ultimately wants to
 537         operate on a <tree> object but automatically dereferences
 538         <commit> and <tag> objects that point at a <tree>.
 539
 540 <commit-ish>::
 541         Indicates a commit or tag object name.  A
 542         command that takes a <commit-ish> argument ultimately wants to
 543         operate on a <commit> object but automatically dereferences
 544         <tag> objects that point at a <commit>.
 545
 546 <type>::
 547         Indicates that an object type is required.
 548         Currently one of: `blob`, `tree`, `commit`, or `tag`.
 549
 550 <file>::
 551         Indicates a filename - almost always relative to the
 552         root of the tree structure `GIT_INDEX_FILE` describes.
 553
 554 Symbolic Identifiers
 555 --------------------
 556 Any git command accepting any <object> can also use the following
 557 symbolic notation:
 558
 559 HEAD::
 560         indicates the head of the current branch.
 561
 562 <tag>::
 563         a valid tag 'name'
 564         (i.e. a `refs/tags/<tag>` reference).
 565
 566 <head>::
 567         a valid head 'name'
 568         (i.e. a `refs/heads/<head>` reference).
 569
 570 For a more complete list of ways to spell object names, see
 571 "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
 572
 573
 574 File/Directory Structure
 575 ------------------------
 576
 577 Please see the linkgit:gitrepository-layout[5] document.
 578
 579 Read linkgit:githooks[5] for more details about each hook.
 580
 581 Higher level SCMs may provide and manage additional information in the
 582 `$GIT_DIR`.
 583
 584
 585 Terminology
 586 -----------
 587 Please see linkgit:gitglossary[7].
 588
 589
 590 Environment Variables
 591 ---------------------
 592 Various git commands use the following environment variables:
 593
 594 The git Repository
 595 ~~~~~~~~~~~~~~~~~~
 596 These environment variables apply to 'all' core git commands. Nb: it
 597 is worth noting that they may be used/overridden by SCMS sitting above
 598 git so take care if using Cogito etc.
 599
 600 'GIT_INDEX_FILE'::
 601         This environment allows the specification of an alternate
 602         index file. If not specified, the default of `$GIT_DIR/index`
 603         is used.
 604
 605 'GIT_OBJECT_DIRECTORY'::
 606         If the object storage directory is specified via this
 607         environment variable then the sha1 directories are created
 608         underneath - otherwise the default `$GIT_DIR/objects`
 609         directory is used.
 610
 611 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 612         Due to the immutable nature of git objects, old objects can be
 613         archived into shared, read-only directories. This variable
 614         specifies a ":" separated (on Windows ";" separated) list
 615         of git object directories which can be used to search for git
 616         objects. New objects will not be written to these directories.
 617
 618 'GIT_DIR'::
 619         If the 'GIT_DIR' environment variable is set then it
 620         specifies a path to use instead of the default `.git`
 621         for the base of the repository.
 622
 623 'GIT_WORK_TREE'::
 624         Set the path to the working tree.  The value will not be
 625         used in combination with repositories found automatically in
 626         a .git directory (i.e. $GIT_DIR is not set).
 627         This can also be controlled by the '--work-tree' command line
 628         option and the core.worktree configuration variable.
 629
 630 'GIT_NAMESPACE'::
 631         Set the git namespace; see linkgit:gitnamespaces[7] for details.
 632         The '--namespace' command-line option also sets this value.
 633
 634 'GIT_CEILING_DIRECTORIES'::
 635         This should be a colon-separated list of absolute paths.
 636         If set, it is a list of directories that git should not chdir
 637         up into while looking for a repository directory.
 638         It will not exclude the current working directory or
 639         a GIT_DIR set on the command line or in the environment.
 640         (Useful for excluding slow-loading network directories.)
 641
 642 'GIT_DISCOVERY_ACROSS_FILESYSTEM'::
 643         When run in a directory that does not have ".git" repository
 644         directory, git tries to find such a directory in the parent
 645         directories to find the top of the working tree, but by default it
 646         does not cross filesystem boundaries.  This environment variable
 647         can be set to true to tell git not to stop at filesystem
 648         boundaries.  Like 'GIT_CEILING_DIRECTORIES', this will not affect
 649         an explicit repository directory set via 'GIT_DIR' or on the
 650         command line.
 651
 652 git Commits
 653 ~~~~~~~~~~~
 654 'GIT_AUTHOR_NAME'::
 655 'GIT_AUTHOR_EMAIL'::
 656 'GIT_AUTHOR_DATE'::
 657 'GIT_COMMITTER_NAME'::
 658 'GIT_COMMITTER_EMAIL'::
 659 'GIT_COMMITTER_DATE'::
 660 'EMAIL'::
 661         see linkgit:git-commit-tree[1]
 662
 663 git Diffs
 664 ~~~~~~~~~
 665 'GIT_DIFF_OPTS'::
 666         Only valid setting is "--unified=??" or "-u??" to set the
 667         number of context lines shown when a unified diff is created.
 668         This takes precedence over any "-U" or "--unified" option
 669         value passed on the git diff command line.
 670
 671 'GIT_EXTERNAL_DIFF'::
 672         When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
 673         program named by it is called, instead of the diff invocation
 674         described above.  For a path that is added, removed, or modified,
 675         'GIT_EXTERNAL_DIFF' is called with 7 parameters:
 676
 677         path old-file old-hex old-mode new-file new-hex new-mode
 678 +
 679 where:
 680
 681         <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
 682                          contents of <old|new>,
 683         <old|new>-hex:: are the 40-hexdigit SHA1 hashes,
 684         <old|new>-mode:: are the octal representation of the file modes.
 685 +
 686 The file parameters can point at the user's working file
 687 (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
 688 when a new file is added), or a temporary file (e.g. `old-file` in the
 689 index).  'GIT_EXTERNAL_DIFF' should not worry about unlinking the
 690 temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
 691 +
 692 For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
 693 parameter, <path>.
 694
 695 other
 696 ~~~~~
 697 'GIT_MERGE_VERBOSITY'::
 698         A number controlling the amount of output shown by
 699         the recursive merge strategy.  Overrides merge.verbosity.
 700         See linkgit:git-merge[1]
 701
 702 'GIT_PAGER'::
 703         This environment variable overrides `$PAGER`. If it is set
 704         to an empty string or to the value "cat", git will not launch
 705         a pager.  See also the `core.pager` option in
 706         linkgit:git-config[1].
 707
 708 'GIT_SSH'::
 709         If this environment variable is set then 'git fetch'
 710         and 'git push' will use this command instead
 711         of 'ssh' when they need to connect to a remote system.
 712         The '$GIT_SSH' command will be given exactly two arguments:
 713         the 'username@host' (or just 'host') from the URL and the
 714         shell command to execute on that remote system.
 715 +
 716 To pass options to the program that you want to list in GIT_SSH
 717 you will need to wrap the program and options into a shell script,
 718 then set GIT_SSH to refer to the shell script.
 719 +
 720 Usually it is easier to configure any desired options through your
 721 personal `.ssh/config` file.  Please consult your ssh documentation
 722 for further details.
 723
 724 'GIT_ASKPASS'::
 725         If this environment variable is set, then git commands which need to
 726         acquire passwords or passphrases (e.g. for HTTP or IMAP authentication)
 727         will call this program with a suitable prompt as command line argument
 728         and read the password from its STDOUT. See also the 'core.askpass'
 729         option in linkgit:git-config[1].
 730
 731 'GIT_FLUSH'::
 732         If this environment variable is set to "1", then commands such
 733         as 'git blame' (in incremental mode), 'git rev-list', 'git log',
 734         and 'git whatchanged' will force a flush of the output stream
 735         after each commit-oriented record have been flushed.   If this
 736         variable is set to "0", the output of these commands will be done
 737         using completely buffered I/O.   If this environment variable is
 738         not set, git will choose buffered or record-oriented flushing
 739         based on whether stdout appears to be redirected to a file or not.
 740
 741 'GIT_TRACE'::
 742         If this variable is set to "1", "2" or "true" (comparison
 743         is case insensitive), git will print `trace:` messages on
 744         stderr telling about alias expansion, built-in command
 745         execution and external command execution.
 746         If this variable is set to an integer value greater than 1
 747         and lower than 10 (strictly) then git will interpret this
 748         value as an open file descriptor and will try to write the
 749         trace messages into this file descriptor.
 750         Alternatively, if this variable is set to an absolute path
 751         (starting with a '/' character), git will interpret this
 752         as a file path and will try to write the trace messages
 753         into it.
 754
 755 Discussion[[Discussion]]
 756 ------------------------
 757
 758 More detail on the following is available from the
 759 link:user-manual.html#git-concepts[git concepts chapter of the
 760 user-manual] and linkgit:gitcore-tutorial[7].
 761
 762 A git project normally consists of a working directory with a ".git"
 763 subdirectory at the top level.  The .git directory contains, among other
 764 things, a compressed object database representing the complete history
 765 of the project, an "index" file which links that history to the current
 766 contents of the working tree, and named pointers into that history such
 767 as tags and branch heads.
 768
 769 The object database contains objects of three main types: blobs, which
 770 hold file data; trees, which point to blobs and other trees to build up
 771 directory hierarchies; and commits, which each reference a single tree
 772 and some number of parent commits.
 773
 774 The commit, equivalent to what other systems call a "changeset" or
 775 "version", represents a step in the project's history, and each parent
 776 represents an immediately preceding step.  Commits with more than one
 777 parent represent merges of independent lines of development.
 778
 779 All objects are named by the SHA1 hash of their contents, normally
 780 written as a string of 40 hex digits.  Such names are globally unique.
 781 The entire history leading up to a commit can be vouched for by signing
 782 just that commit.  A fourth object type, the tag, is provided for this
 783 purpose.
 784
 785 When first created, objects are stored in individual files, but for
 786 efficiency may later be compressed together into "pack files".
 787
 788 Named pointers called refs mark interesting points in history.  A ref
 789 may contain the SHA1 name of an object or the name of another ref.  Refs
 790 with names beginning `ref/head/` contain the SHA1 name of the most
 791 recent commit (or "head") of a branch under development.  SHA1 names of
 792 tags of interest are stored under `ref/tags/`.  A special ref named
 793 `HEAD` contains the name of the currently checked-out branch.
 794
 795 The index file is initialized with a list of all paths and, for each
 796 path, a blob object and a set of attributes.  The blob object represents
 797 the contents of the file as of the head of the current branch.  The
 798 attributes (last modified time, size, etc.) are taken from the
 799 corresponding file in the working tree.  Subsequent changes to the
 800 working tree can be found by comparing these attributes.  The index may
 801 be updated with new content, and new commits may be created from the
 802 content stored in the index.
 803
 804 The index is also capable of storing multiple entries (called "stages")
 805 for a given pathname.  These stages are used to hold the various
 806 unmerged version of a file when a merge is in progress.
 807
 808 Authors
 809 -------
 810 Git was started by Linus Torvalds, and is currently maintained by Junio
 811 C Hamano. Numerous contributions have come from the git mailing list
 812 <git@vger.kernel.org>. For a more complete list of contributors, see
 813 http://git-scm.com/about. If you have a clone of git.git itself, the
 814 output of linkgit:git-shortlog[1] and linkgit:git-blame[1] can show you
 815 the authors for specific parts of the project.
 816
 817 Reporting Bugs
 818 --------------
 819
 820 Report bugs to the Git mailing list <git@vger.kernel.org> where the
 821 development and maintenance is primarily done.  You do not have to be
 822 subscribed to the list to send a message there.
 823
 824 SEE ALSO
 825 --------
 826 linkgit:gittutorial[7], linkgit:gittutorial-2[7],
 827 link:everyday.html[Everyday Git], linkgit:gitcvs-migration[7],
 828 linkgit:gitglossary[7], linkgit:gitcore-tutorial[7],
 829 linkgit:gitcli[7], link:user-manual.html[The Git User's Manual],
 830 linkgit:gitworkflows[7]
 831
 832 GIT
 833 ---
 834 Part of the linkgit:git[1] suite