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