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