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