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