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