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