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