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