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