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