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