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