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