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