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