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