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