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