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