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