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