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