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