1git(7) 2====== 3 4NAME 5---- 6git - the stupid content tracker 7 8 9SYNOPSIS 10-------- 11'git' [--version] [--exec-path[=GIT_EXEC_PATH]] [--help] COMMAND [ARGS] 12 13DESCRIPTION 14----------- 15Git is a fast, scalable, distributed revision control system with an 16unusually rich command set that provides both high-level operations 17and full access to internals. 18 19See this link:tutorial.html[tutorial] to get started, then see 20link:everyday.html[Everyday Git] for a useful minimum set of commands, and 21"man git-commandname" for documentation of each command. CVS users may 22also want to read link:cvs-migration.html[CVS migration]. 23 24OPTIONS 25------- 26--version:: 27 Prints the git suite version that the 'git' program came from. 28 29--help:: 30 Prints the synopsis and a list of the most commonly used 31 commands. If a git command is named this option will bring up 32 the man-page for that command. If the option '--all' or '-a' is 33 given then all available commands are printed. 34 35--exec-path:: 36 Path to wherever your core git programs are installed. 37 This can also be controlled by setting the GIT_EXEC_PATH 38 environment variable. If no path is given 'git' will print 39 the current setting and then exit. 40 41 42FURTHER DOCUMENTATION 43--------------------- 44 45See the references above to get started using git. The following is 46probably more detail than necessary for a first-time user. 47 48The <<Discussion,Discussion>> section below and the 49link:core-tutorial.html[Core tutorial] both provide introductions to the 50underlying git architecture. 51 52See also the link:howto-index.html[howto] documents for some useful 53examples. 54 55GIT COMMANDS 56------------ 57 58We divide git into high level ("porcelain") commands and low level 59("plumbing") commands. 60 61Low-level commands (plumbing) 62----------------------------- 63 64Although git includes its 65own porcelain layer, its low-level commands are sufficient to support 66development of alternative porcelains. Developers of such porcelains 67might start by reading about gitlink:git-update-index[1] and 68gitlink:git-read-tree[1]. 69 70We divide the low-level commands into commands that manipulate objects (in 71the repository, index, and working tree), commands that interrogate and 72compare objects, and commands that move objects and references between 73repositories. 74 75Manipulation commands 76~~~~~~~~~~~~~~~~~~~~~ 77gitlink:git-apply[1]:: 78 Reads a "diff -up1" or git generated patch file and 79 applies it to the working tree. 80 81gitlink:git-checkout-index[1]:: 82 Copy files from the index to the working tree. 83 84gitlink:git-commit-tree[1]:: 85 Creates a new commit object. 86 87gitlink:git-hash-object[1]:: 88 Computes the object ID from a file. 89 90gitlink:git-index-pack[1]:: 91 Build pack idx file for an existing packed archive. 92 93gitlink:git-init-db[1]:: 94 Creates an empty git object database, or reinitialize an 95 existing one. 96 97gitlink:git-merge-index[1]:: 98 Runs a merge for files needing merging. 99 100gitlink:git-mktag[1]:: 101 Creates a tag object. 102 103gitlink:git-pack-objects[1]:: 104 Creates a packed archive of objects. 105 106gitlink:git-prune-packed[1]:: 107 Remove extra objects that are already in pack files. 108 109gitlink:git-read-tree[1]:: 110 Reads tree information into the index. 111 112gitlink:git-repo-config[1]:: 113 Get and set options in .git/config. 114 115gitlink:git-unpack-objects[1]:: 116 Unpacks objects out of a packed archive. 117 118gitlink:git-update-index[1]:: 119 Registers files in the working tree to the index. 120 121gitlink:git-write-tree[1]:: 122 Creates a tree from the index. 123 124 125Interrogation commands 126~~~~~~~~~~~~~~~~~~~~~~ 127 128gitlink:git-cat-file[1]:: 129 Provide content or type/size information for repository objects. 130 131gitlink:git-describe[1]:: 132 Show the most recent tag that is reachable from a commit. 133 134gitlink:git-diff-index[1]:: 135 Compares content and mode of blobs between the index and repository. 136 137gitlink:git-diff-files[1]:: 138 Compares files in the working tree and the index. 139 140gitlink:git-diff-stages[1]:: 141 Compares two "merge stages" in the index. 142 143gitlink:git-diff-tree[1]:: 144 Compares the content and mode of blobs found via two tree objects. 145 146gitlink:git-fsck-objects[1]:: 147 Verifies the connectivity and validity of the objects in the database. 148 149gitlink:git-ls-files[1]:: 150 Information about files in the index and the working tree. 151 152gitlink:git-ls-tree[1]:: 153 Displays a tree object in human readable form. 154 155gitlink:git-merge-base[1]:: 156 Finds as good common ancestors as possible for a merge. 157 158gitlink:git-name-rev[1]:: 159 Find symbolic names for given revs. 160 161gitlink:git-pack-redundant[1]:: 162 Find redundant pack files. 163 164gitlink:git-rev-list[1]:: 165 Lists commit objects in reverse chronological order. 166 167gitlink:git-show-index[1]:: 168 Displays contents of a pack idx file. 169 170gitlink:git-tar-tree[1]:: 171 Creates a tar archive of the files in the named tree object. 172 173gitlink:git-unpack-file[1]:: 174 Creates a temporary file with a blob's contents. 175 176gitlink:git-var[1]:: 177 Displays a git logical variable. 178 179gitlink:git-verify-pack[1]:: 180 Validates packed git archive files. 181 182In general, the interrogate commands do not touch the files in 183the working tree. 184 185 186Synching repositories 187~~~~~~~~~~~~~~~~~~~~~ 188 189gitlink:git-clone-pack[1]:: 190 Clones a repository into the current repository (engine 191 for ssh and local transport). 192 193gitlink:git-fetch-pack[1]:: 194 Updates from a remote repository (engine for ssh and 195 local transport). 196 197gitlink:git-http-fetch[1]:: 198 Downloads a remote git repository via HTTP by walking 199 commit chain. 200 201gitlink:git-local-fetch[1]:: 202 Duplicates another git repository on a local system by 203 walking commit chain. 204 205gitlink:git-peek-remote[1]:: 206 Lists references on a remote repository using 207 upload-pack protocol (engine for ssh and local 208 transport). 209 210gitlink:git-receive-pack[1]:: 211 Invoked by 'git-send-pack' to receive what is pushed to it. 212 213gitlink:git-send-pack[1]:: 214 Pushes to a remote repository, intelligently. 215 216gitlink:git-http-push[1]:: 217 Push missing objects using HTTP/DAV. 218 219gitlink:git-shell[1]:: 220 Restricted shell for GIT-only SSH access. 221 222gitlink:git-ssh-fetch[1]:: 223 Pulls from a remote repository over ssh connection by 224 walking commit chain. 225 226gitlink:git-ssh-upload[1]:: 227 Helper "server-side" program used by git-ssh-fetch. 228 229gitlink:git-update-server-info[1]:: 230 Updates auxiliary information on a dumb server to help 231 clients discover references and packs on it. 232 233gitlink:git-upload-pack[1]:: 234 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push 235 what are asked for. 236 237 238High-level commands (porcelain) 239------------------------------- 240 241We separate the porcelain commands into the main commands and some 242ancillary user utilities. 243 244Main porcelain commands 245~~~~~~~~~~~~~~~~~~~~~~~ 246 247gitlink:git-add[1]:: 248 Add paths to the index. 249 250gitlink:git-am[1]:: 251 Apply patches from a mailbox, but cooler. 252 253gitlink:git-applymbox[1]:: 254 Apply patches from a mailbox, original version by Linus. 255 256gitlink:git-bisect[1]:: 257 Find the change that introduced a bug by binary search. 258 259gitlink:git-branch[1]:: 260 Create and Show branches. 261 262gitlink:git-checkout[1]:: 263 Checkout and switch to a branch. 264 265gitlink:git-cherry-pick[1]:: 266 Cherry-pick the effect of an existing commit. 267 268gitlink:git-clone[1]:: 269 Clones a repository into a new directory. 270 271gitlink:git-commit[1]:: 272 Record changes to the repository. 273 274gitlink:git-diff[1]:: 275 Show changes between commits, commit and working tree, etc. 276 277gitlink:git-fetch[1]:: 278 Download from a remote repository via various protocols. 279 280gitlink:git-format-patch[1]:: 281 Prepare patches for e-mail submission. 282 283gitlink:git-grep[1]:: 284 Print lines matching a pattern. 285 286gitlink:git-log[1]:: 287 Shows commit logs. 288 289gitlink:git-ls-remote[1]:: 290 Shows references in a remote or local repository. 291 292gitlink:git-merge[1]:: 293 Grand unified merge driver. 294 295gitlink:git-mv[1]:: 296 Move or rename a file, a directory, or a symlink. 297 298gitlink:git-pull[1]:: 299 Fetch from and merge with a remote repository. 300 301gitlink:git-push[1]:: 302 Update remote refs along with associated objects. 303 304gitlink:git-rebase[1]:: 305 Rebase local commits to the updated upstream head. 306 307gitlink:git-repack[1]:: 308 Pack unpacked objects in a repository. 309 310gitlink:git-rerere[1]:: 311 Reuse recorded resolution of conflicted merges. 312 313gitlink:git-reset[1]:: 314 Reset current HEAD to the specified state. 315 316gitlink:git-resolve[1]:: 317 Merge two commits. 318 319gitlink:git-revert[1]:: 320 Revert an existing commit. 321 322gitlink:git-shortlog[1]:: 323 Summarizes 'git log' output. 324 325gitlink:git-show[1]:: 326 Show one commit log and its diff. 327 328gitlink:git-show-branch[1]:: 329 Show branches and their commits. 330 331gitlink:git-status[1]:: 332 Shows the working tree status. 333 334gitlink:git-verify-tag[1]:: 335 Check the GPG signature of tag. 336 337gitlink:git-whatchanged[1]:: 338 Shows commit logs and differences they introduce. 339 340 341Ancillary Commands 342~~~~~~~~~~~~~~~~~~ 343Manipulators: 344 345gitlink:git-applypatch[1]:: 346 Apply one patch extracted from an e-mail. 347 348gitlink:git-archimport[1]:: 349 Import an arch repository into git. 350 351gitlink:git-convert-objects[1]:: 352 Converts old-style git repository. 353 354gitlink:git-cvsimport[1]:: 355 Salvage your data out of another SCM people love to hate. 356 357gitlink:git-cvsexportcommit[1]:: 358 Export a single commit to a CVS checkout. 359 360gitlink:git-lost-found[1]:: 361 Recover lost refs that luckily have not yet been pruned. 362 363gitlink:git-merge-one-file[1]:: 364 The standard helper program to use with `git-merge-index`. 365 366gitlink:git-prune[1]:: 367 Prunes all unreachable objects from the object database. 368 369gitlink:git-relink[1]:: 370 Hardlink common objects in local repositories. 371 372gitlink:git-svnimport[1]:: 373 Import a SVN repository into git. 374 375gitlink:git-sh-setup[1]:: 376 Common git shell script setup code. 377 378gitlink:git-symbolic-ref[1]:: 379 Read and modify symbolic refs. 380 381gitlink:git-tag[1]:: 382 An example script to create a tag object signed with GPG. 383 384gitlink:git-update-ref[1]:: 385 Update the object name stored in a ref safely. 386 387 388Interrogators: 389 390gitlink:git-check-ref-format[1]:: 391 Make sure ref name is well formed. 392 393gitlink:git-cherry[1]:: 394 Find commits not merged upstream. 395 396gitlink:git-count-objects[1]:: 397 Count unpacked number of objects and their disk consumption. 398 399gitlink:git-daemon[1]:: 400 A really simple server for git repositories. 401 402gitlink:git-get-tar-commit-id[1]:: 403 Extract commit ID from an archive created using git-tar-tree. 404 405gitlink:git-mailinfo[1]:: 406 Extracts patch and authorship information from a single 407 e-mail message, optionally transliterating the commit 408 message into utf-8. 409 410gitlink:git-mailsplit[1]:: 411 A stupid program to split UNIX mbox format mailbox into 412 individual pieces of e-mail. 413 414gitlink:git-patch-id[1]:: 415 Compute unique ID for a patch. 416 417gitlink:git-parse-remote[1]:: 418 Routines to help parsing `$GIT_DIR/remotes/` files. 419 420gitlink:git-request-pull[1]:: 421 git-request-pull. 422 423gitlink:git-rev-parse[1]:: 424 Pick out and massage parameters. 425 426gitlink:git-send-email[1]:: 427 Send patch e-mails out of "format-patch --mbox" output. 428 429gitlink:git-symbolic-ref[1]:: 430 Read and modify symbolic refs. 431 432gitlink:git-stripspace[1]:: 433 Filter out empty lines. 434 435 436Commands not yet documented 437--------------------------- 438 439gitlink:gitk[1]:: 440 The gitk repository browser. 441 442 443Configuration Mechanism 444----------------------- 445 446Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file 447is used to hold per-repository configuration options. It is a 448simple text file modelled after `.ini` format familiar to some 449people. Here is an example: 450 451------------ 452# 453# A '#' or ';' character indicates a comment. 454# 455 456; core variables 457[core] 458 ; Don't trust file modes 459 filemode = false 460 461; user identity 462[user] 463 name = "Junio C Hamano" 464 email = "junkio@twinsun.com" 465 466------------ 467 468Various commands read from the configuration file and adjust 469their operation accordingly. 470 471 472Identifier Terminology 473---------------------- 474<object>:: 475 Indicates the object name for any type of object. 476 477<blob>:: 478 Indicates a blob object name. 479 480<tree>:: 481 Indicates a tree object name. 482 483<commit>:: 484 Indicates a commit object name. 485 486<tree-ish>:: 487 Indicates a tree, commit or tag object name. A 488 command that takes a <tree-ish> argument ultimately wants to 489 operate on a <tree> object but automatically dereferences 490 <commit> and <tag> objects that point at a <tree>. 491 492<type>:: 493 Indicates that an object type is required. 494 Currently one of: `blob`, `tree`, `commit`, or `tag`. 495 496<file>:: 497 Indicates a filename - almost always relative to the 498 root of the tree structure `GIT_INDEX_FILE` describes. 499 500Symbolic Identifiers 501-------------------- 502Any git command accepting any <object> can also use the following 503symbolic notation: 504 505HEAD:: 506 indicates the head of the current branch (i.e. the 507 contents of `$GIT_DIR/HEAD`). 508 509<tag>:: 510 a valid tag 'name' 511 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). 512 513<head>:: 514 a valid head 'name' 515 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). 516 517 518File/Directory Structure 519------------------------ 520 521Please see link:repository-layout.html[repository layout] document. 522 523Read link:hooks.html[hooks] for more details about each hook. 524 525Higher level SCMs may provide and manage additional information in the 526`$GIT_DIR`. 527 528 529Terminology 530----------- 531Please see link:glossary.html[glossary] document. 532 533 534Environment Variables 535--------------------- 536Various git commands use the following environment variables: 537 538The git Repository 539~~~~~~~~~~~~~~~~~~ 540These environment variables apply to 'all' core git commands. Nb: it 541is worth noting that they may be used/overridden by SCMS sitting above 542git so take care if using Cogito etc. 543 544'GIT_INDEX_FILE':: 545 This environment allows the specification of an alternate 546 index file. If not specified, the default of `$GIT_DIR/index` 547 is used. 548 549'GIT_OBJECT_DIRECTORY':: 550 If the object storage directory is specified via this 551 environment variable then the sha1 directories are created 552 underneath - otherwise the default `$GIT_DIR/objects` 553 directory is used. 554 555'GIT_ALTERNATE_OBJECT_DIRECTORIES':: 556 Due to the immutable nature of git objects, old objects can be 557 archived into shared, read-only directories. This variable 558 specifies a ":" separated list of git object directories which 559 can be used to search for git objects. New objects will not be 560 written to these directories. 561 562'GIT_DIR':: 563 If the 'GIT_DIR' environment variable is set then it 564 specifies a path to use instead of the default `.git` 565 for the base of the repository. 566 567git Commits 568~~~~~~~~~~~ 569'GIT_AUTHOR_NAME':: 570'GIT_AUTHOR_EMAIL':: 571'GIT_AUTHOR_DATE':: 572'GIT_COMMITTER_NAME':: 573'GIT_COMMITTER_EMAIL':: 574 see gitlink:git-commit-tree[1] 575 576git Diffs 577~~~~~~~~~ 578'GIT_DIFF_OPTS':: 579'GIT_EXTERNAL_DIFF':: 580 see the "generating patches" section in : 581 gitlink:git-diff-index[1]; 582 gitlink:git-diff-files[1]; 583 gitlink:git-diff-tree[1] 584 585Discussion[[Discussion]] 586------------------------ 587include::README[] 588 589Authors 590------- 591* git's founding father is Linus Torvalds <torvalds@osdl.org>. 592* The current git nurse is Junio C Hamano <junkio@cox.net>. 593* The git potty was written by Andres Ericsson <ae@op5.se>. 594* General upbringing is handled by the git-list <git@vger.kernel.org>. 595 596Documentation 597-------------- 598The documentation for git suite was started by David Greaves 599<david@dgreaves.com>, and later enhanced greatly by the 600contributors on the git-list <git@vger.kernel.org>. 601 602GIT 603--- 604Part of the gitlink:git[7] suite 605