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