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