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-repo-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 Low-level commands (plumbing)
  97 -----------------------------
  98
  99 Although git includes its
 100 own porcelain layer, its low-level commands are sufficient to support
 101 development of alternative porcelains.  Developers of such porcelains
 102 might start by reading about gitlink:git-update-index[1] and
 103 gitlink:git-read-tree[1].
 104
 105 We divide the low-level commands into commands that manipulate objects (in
 106 the repository, index, and working tree), commands that interrogate and
 107 compare objects, and commands that move objects and references between
 108 repositories.
 109
 110 Manipulation commands
 111 ~~~~~~~~~~~~~~~~~~~~~
 112
 113 include::cmds-plumbingmanipulators.txt[]
 114
 115
 116 Interrogation commands
 117 ~~~~~~~~~~~~~~~~~~~~~~
 118
 119 include::cmds-plumbinginterrogators.txt[]
 120
 121 In general, the interrogate commands do not touch the files in
 122 the working tree.
 123
 124
 125 Synching repositories
 126 ~~~~~~~~~~~~~~~~~~~~~
 127
 128 include::cmds-synchingrepositories.txt[]
 129
 130
 131 Configuration Mechanism
 132 -----------------------
 133
 134 Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file
 135 is used to hold per-repository configuration options.  It is a
 136 simple text file modeled after `.ini` format familiar to some
 137 people.  Here is an example:
 138
 139 ------------
 140 #
 141 # A '#' or ';' character indicates a comment.
 142 #
 143
 144 ; core variables
 145 [core]
 146         ; Don't trust file modes
 147         filemode = false
 148
 149 ; user identity
 150 [user]
 151         name = "Junio C Hamano"
 152         email = "junkio@twinsun.com"
 153
 154 ------------
 155
 156 Various commands read from the configuration file and adjust
 157 their operation accordingly.
 158
 159
 160 Identifier Terminology
 161 ----------------------
 162 <object>::
 163         Indicates the object name for any type of object.
 164
 165 <blob>::
 166         Indicates a blob object name.
 167
 168 <tree>::
 169         Indicates a tree object name.
 170
 171 <commit>::
 172         Indicates a commit object name.
 173
 174 <tree-ish>::
 175         Indicates a tree, commit or tag object name.  A
 176         command that takes a <tree-ish> argument ultimately wants to
 177         operate on a <tree> object but automatically dereferences
 178         <commit> and <tag> objects that point at a <tree>.
 179
 180 <type>::
 181         Indicates that an object type is required.
 182         Currently one of: `blob`, `tree`, `commit`, or `tag`.
 183
 184 <file>::
 185         Indicates a filename - almost always relative to the
 186         root of the tree structure `GIT_INDEX_FILE` describes.
 187
 188 Symbolic Identifiers
 189 --------------------
 190 Any git command accepting any <object> can also use the following
 191 symbolic notation:
 192
 193 HEAD::
 194         indicates the head of the current branch (i.e. the
 195         contents of `$GIT_DIR/HEAD`).
 196
 197 <tag>::
 198         a valid tag 'name'
 199         (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`).
 200
 201 <head>::
 202         a valid head 'name'
 203         (i.e. the contents of `$GIT_DIR/refs/heads/<head>`).
 204
 205 For a more complete list of ways to spell object names, see
 206 "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1].
 207
 208
 209 File/Directory Structure
 210 ------------------------
 211
 212 Please see link:repository-layout.html[repository layout] document.
 213
 214 Read link:hooks.html[hooks] for more details about each hook.
 215
 216 Higher level SCMs may provide and manage additional information in the
 217 `$GIT_DIR`.
 218
 219
 220 Terminology
 221 -----------
 222 Please see link:glossary.html[glossary] document.
 223
 224
 225 Environment Variables
 226 ---------------------
 227 Various git commands use the following environment variables:
 228
 229 The git Repository
 230 ~~~~~~~~~~~~~~~~~~
 231 These environment variables apply to 'all' core git commands. Nb: it
 232 is worth noting that they may be used/overridden by SCMS sitting above
 233 git so take care if using Cogito etc.
 234
 235 'GIT_INDEX_FILE'::
 236         This environment allows the specification of an alternate
 237         index file. If not specified, the default of `$GIT_DIR/index`
 238         is used.
 239
 240 'GIT_OBJECT_DIRECTORY'::
 241         If the object storage directory is specified via this
 242         environment variable then the sha1 directories are created
 243         underneath - otherwise the default `$GIT_DIR/objects`
 244         directory is used.
 245
 246 'GIT_ALTERNATE_OBJECT_DIRECTORIES'::
 247         Due to the immutable nature of git objects, old objects can be
 248         archived into shared, read-only directories. This variable
 249         specifies a ":" separated list of git object directories which
 250         can be used to search for git objects. New objects will not be
 251         written to these directories.
 252
 253 'GIT_DIR'::
 254         If the 'GIT_DIR' environment variable is set then it
 255         specifies a path to use instead of the default `.git`
 256         for the base of the repository.
 257
 258 git Commits
 259 ~~~~~~~~~~~
 260 'GIT_AUTHOR_NAME'::
 261 'GIT_AUTHOR_EMAIL'::
 262 'GIT_AUTHOR_DATE'::
 263 'GIT_COMMITTER_NAME'::
 264 'GIT_COMMITTER_EMAIL'::
 265         see gitlink:git-commit-tree[1]
 266
 267 git Diffs
 268 ~~~~~~~~~
 269 'GIT_DIFF_OPTS'::
 270         Only valid setting is "--unified=??" or "-u??" to set the
 271         number of context lines shown when a unified diff is created.
 272         This takes precedence over any "-U" or "--unified" option
 273         value passed on the git diff command line.
 274
 275 'GIT_EXTERNAL_DIFF'::
 276         When the environment variable 'GIT_EXTERNAL_DIFF' is set, the
 277         program named by it is called, instead of the diff invocation
 278         described above.  For a path that is added, removed, or modified,
 279         'GIT_EXTERNAL_DIFF' is called with 7 parameters:
 280
 281         path old-file old-hex old-mode new-file new-hex new-mode
 282 +
 283 where:
 284
 285         <old|new>-file:: are files GIT_EXTERNAL_DIFF can use to read the
 286                          contents of <old|new>,
 287         <old|new>-hex:: are the 40-hexdigit SHA1 hashes,
 288         <old|new>-mode:: are the octal representation of the file modes.
 289
 290 +
 291 The file parameters can point at the user's working file
 292 (e.g. `new-file` in "git-diff-files"), `/dev/null` (e.g. `old-file`
 293 when a new file is added), or a temporary file (e.g. `old-file` in the
 294 index).  'GIT_EXTERNAL_DIFF' should not worry about unlinking the
 295 temporary file --- it is removed when 'GIT_EXTERNAL_DIFF' exits.
 296 +
 297 For a path that is unmerged, 'GIT_EXTERNAL_DIFF' is called with 1
 298 parameter, <path>.
 299
 300 other
 301 ~~~~~
 302 'GIT_PAGER'::
 303         This environment variable overrides `$PAGER`.
 304
 305 'GIT_TRACE'::
 306         If this variable is set to "1", "2" or "true" (comparison
 307         is case insensitive), git will print `trace:` messages on
 308         stderr telling about alias expansion, built-in command
 309         execution and external command execution.
 310         If this variable is set to an integer value greater than 1
 311         and lower than 10 (strictly) then git will interpret this
 312         value as an open file descriptor and will try to write the
 313         trace messages into this file descriptor.
 314         Alternatively, if this variable is set to an absolute path
 315         (starting with a '/' character), git will interpret this
 316         as a file path and will try to write the trace messages
 317         into it.
 318
 319 Discussion[[Discussion]]
 320 ------------------------
 321 include::core-intro.txt[]
 322
 323 Authors
 324 -------
 325 * git's founding father is Linus Torvalds <torvalds@osdl.org>.
 326 * The current git nurse is Junio C Hamano <junkio@cox.net>.
 327 * The git potty was written by Andres Ericsson <ae@op5.se>.
 328 * General upbringing is handled by the git-list <git@vger.kernel.org>.
 329
 330 Documentation
 331 --------------
 332 The documentation for git suite was started by David Greaves
 333 <david@dgreaves.com>, and later enhanced greatly by the
 334 contributors on the git-list <git@vger.kernel.org>.
 335
 336 GIT
 337 ---
 338 Part of the gitlink:git[7] suite
 339