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