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