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