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