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