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.1.2/git.html[documentation for release 1.5.1.2] 41 42* link:RelNotes-1.5.1.2.txt[release notes for 1.5.1.2] 43 44* link:RelNotes-1.5.1.1.txt[release notes for 1.5.1.1] 45 46* link:RelNotes-1.5.0.7.txt[release notes for 1.5.0.7] 47 48* link:RelNotes-1.5.0.6.txt[release notes for 1.5.0.6] 49 50* link:RelNotes-1.5.0.5.txt[release notes for 1.5.0.5] 51 52* link:RelNotes-1.5.0.3.txt[release notes for 1.5.0.3] 53 54* link:RelNotes-1.5.0.2.txt[release notes for 1.5.0.2] 55 56* link:RelNotes-1.5.0.1.txt[release notes for 1.5.0.1] 57 58* link:RelNotes-1.5.0.txt[release notes for 1.5.0] 59 60* link:v1.4.4.4/git.html[documentation for release 1.4.4.4] 61 62* link:v1.3.3/git.html[documentation for release 1.3.3] 63 64* link:v1.2.6/git.html[documentation for release 1.2.6] 65 66* link:v1.0.13/git.html[documentation for release 1.0.13] 67 68============ 69 70endif::stalenotes[] 71 72OPTIONS 73------- 74--version:: 75 Prints the git suite version that the 'git' program came from. 76 77--help:: 78 Prints the synopsis and a list of the most commonly used 79 commands. If a git command is named this option will bring up 80 the man-page for that command. If the option '--all' or '-a' is 81 given then all available commands are printed. 82 83--exec-path:: 84 Path to wherever your core git programs are installed. 85 This can also be controlled by setting the GIT_EXEC_PATH 86 environment variable. If no path is given 'git' will print 87 the current setting and then exit. 88 89-p|--paginate:: 90 Pipe all output into 'less' (or if set, $PAGER). 91 92--git-dir=<path>:: 93 Set the path to the repository. This can also be controlled by 94 setting the GIT_DIR environment variable. 95 96--bare:: 97 Same as --git-dir=`pwd`. 98 99FURTHER DOCUMENTATION 100--------------------- 101 102See the references above to get started using git. The following is 103probably more detail than necessary for a first-time user. 104 105The <<Discussion,Discussion>> section below and the 106link:core-tutorial.html[Core tutorial] both provide introductions to the 107underlying git architecture. 108 109See also the link:howto-index.html[howto] documents for some useful 110examples. 111 112GIT COMMANDS 113------------ 114 115We divide git into high level ("porcelain") commands and low level 116("plumbing") commands. 117 118High-level commands (porcelain) 119------------------------------- 120 121We separate the porcelain commands into the main commands and some 122ancillary user utilities. 123 124Main porcelain commands 125~~~~~~~~~~~~~~~~~~~~~~~ 126 127include::cmds-mainporcelain.txt[] 128 129Ancillary Commands 130~~~~~~~~~~~~~~~~~~ 131Manipulators: 132 133include::cmds-ancillarymanipulators.txt[] 134 135Interrogators: 136 137include::cmds-ancillaryinterrogators.txt[] 138 139 140Interacting with Others 141~~~~~~~~~~~~~~~~~~~~~~~ 142 143These commands are to interact with foreign SCM and with other 144people via patch over e-mail. 145 146include::cmds-foreignscminterface.txt[] 147 148 149Low-level commands (plumbing) 150----------------------------- 151 152Although git includes its 153own porcelain layer, its low-level commands are sufficient to support 154development of alternative porcelains. Developers of such porcelains 155might start by reading about gitlink:git-update-index[1] and 156gitlink:git-read-tree[1]. 157 158The interface (input, output, set of options and the semantics) 159to these low-level commands are meant to be a lot more stable 160than Porcelain level commands, because these commands are 161primarily for scripted use. The interface to Porcelain commands 162on the other hand are subject to change in order to improve the 163end user experience. 164 165The following description divides 166the low-level commands into commands that manipulate objects (in 167the repository, index, and working tree), commands that interrogate and 168compare objects, and commands that move objects and references between 169repositories. 170 171 172Manipulation commands 173~~~~~~~~~~~~~~~~~~~~~ 174 175include::cmds-plumbingmanipulators.txt[] 176 177 178Interrogation commands 179~~~~~~~~~~~~~~~~~~~~~~ 180 181include::cmds-plumbinginterrogators.txt[] 182 183In general, the interrogate commands do not touch the files in 184the working tree. 185 186 187Synching repositories 188~~~~~~~~~~~~~~~~~~~~~ 189 190include::cmds-synchingrepositories.txt[] 191 192The following are helper programs used by the above; end users 193typically do not use them directly. 194 195include::cmds-synchelpers.txt[] 196 197 198Internal helper commands 199~~~~~~~~~~~~~~~~~~~~~~~~ 200 201These are internal helper commands used by other commands; end 202users typically do not use them directly. 203 204include::cmds-purehelpers.txt[] 205 206 207Configuration Mechanism 208----------------------- 209 210Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file 211is used to hold per-repository configuration options. It is a 212simple text file modeled after `.ini` format familiar to some 213people. Here is an example: 214 215------------ 216# 217# A '#' or ';' character indicates a comment. 218# 219 220; core variables 221[core] 222 ; Don't trust file modes 223 filemode = false 224 225; user identity 226[user] 227 name = "Junio C Hamano" 228 email = "junkio@twinsun.com" 229 230------------ 231 232Various commands read from the configuration file and adjust 233their operation accordingly. 234 235 236Identifier Terminology 237---------------------- 238<object>:: 239 Indicates the object name for any type of object. 240 241<blob>:: 242 Indicates a blob object name. 243 244<tree>:: 245 Indicates a tree object name. 246 247<commit>:: 248 Indicates a commit object name. 249 250<tree-ish>:: 251 Indicates a tree, commit or tag object name. A 252 command that takes a <tree-ish> argument ultimately wants to 253 operate on a <tree> object but automatically dereferences 254 <commit> and <tag> objects that point at a <tree>. 255 256<commit-ish>:: 257 Indicates a commit or tag object name. A 258 command that takes a <commit-ish> argument ultimately wants to 259 operate on a <commit> object but automatically dereferences 260 <tag> objects that point at a <commit>. 261 262<type>:: 263 Indicates that an object type is required. 264 Currently one of: `blob`, `tree`, `commit`, or `tag`. 265 266<file>:: 267 Indicates a filename - almost always relative to the 268 root of the tree structure `GIT_INDEX_FILE` describes. 269 270Symbolic Identifiers 271-------------------- 272Any git command accepting any <object> can also use the following 273symbolic notation: 274 275HEAD:: 276 indicates the head of the current branch (i.e. the 277 contents of `$GIT_DIR/HEAD`). 278 279<tag>:: 280 a valid tag 'name' 281 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). 282 283<head>:: 284 a valid head 'name' 285 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). 286 287For a more complete list of ways to spell object names, see 288"SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1]. 289 290 291File/Directory Structure 292------------------------ 293 294Please see link:repository-layout.html[repository layout] document. 295 296Read link:hooks.html[hooks] for more details about each hook. 297 298Higher level SCMs may provide and manage additional information in the 299`$GIT_DIR`. 300 301 302Terminology 303----------- 304Please see link:glossary.html[glossary] document. 305 306 307Environment Variables 308--------------------- 309Various git commands use the following environment variables: 310 311The git Repository 312~~~~~~~~~~~~~~~~~~ 313These environment variables apply to 'all' core git commands. Nb: it 314is worth noting that they may be used/overridden by SCMS sitting above 315git so take care if using Cogito etc. 316 317'GIT_INDEX_FILE':: 318 This environment allows the specification of an alternate 319 index file. If not specified, the default of `$GIT_DIR/index` 320 is used. 321 322'GIT_OBJECT_DIRECTORY':: 323 If the object storage directory is specified via this 324 environment variable then the sha1 directories are created 325 underneath - otherwise the default `$GIT_DIR/objects` 326 directory is used. 327 328'GIT_ALTERNATE_OBJECT_DIRECTORIES':: 329 Due to the immutable nature of git objects, old objects can be 330 archived into shared, read-only directories. This variable 331 specifies a ":" separated list of git object directories which 332 can be used to search for git objects. New objects will not be 333 written to these directories. 334 335'GIT_DIR':: 336 If the 'GIT_DIR' environment variable is set then it 337 specifies a path to use instead of the default `.git` 338 for the base of the repository. 339 340git Commits 341~~~~~~~~~~~ 342'GIT_AUTHOR_NAME':: 343'GIT_AUTHOR_EMAIL':: 344'GIT_AUTHOR_DATE':: 345'GIT_COMMITTER_NAME':: 346'GIT_COMMITTER_EMAIL':: 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