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