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