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