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 75Low-level commands (plumbing) 76----------------------------- 77 78Although git includes its 79own porcelain layer, its low-level commands are sufficient to support 80development of alternative porcelains. Developers of such porcelains 81might start by reading about gitlink:git-update-index[1] and 82gitlink:git-read-tree[1]. 83 84We divide the low-level commands into commands that manipulate objects (in 85the repository, index, and working tree), commands that interrogate and 86compare objects, and commands that move objects and references between 87repositories. 88 89Manipulation commands 90~~~~~~~~~~~~~~~~~~~~~ 91gitlink:git-apply[1]:: 92 Reads a "diff -up1" or git generated patch file and 93 applies it to the working tree. 94 95gitlink:git-checkout-index[1]:: 96 Copy files from the index to the working tree. 97 98gitlink:git-commit-tree[1]:: 99 Creates a new commit object. 100 101gitlink:git-hash-object[1]:: 102 Computes the object ID from a file. 103 104gitlink:git-index-pack[1]:: 105 Build pack idx file for an existing packed archive. 106 107gitlink:git-init-db[1]:: 108 Creates an empty git object database, or reinitialize an 109 existing one. 110 111gitlink:git-merge-index[1]:: 112 Runs a merge for files needing merging. 113 114gitlink:git-mktag[1]:: 115 Creates a tag object. 116 117gitlink:git-mktree[1]:: 118 Build a tree-object from ls-tree formatted text. 119 120gitlink:git-pack-objects[1]:: 121 Creates a packed archive of objects. 122 123gitlink:git-prune-packed[1]:: 124 Remove extra objects that are already in pack files. 125 126gitlink:git-read-tree[1]:: 127 Reads tree information into the index. 128 129gitlink:git-repo-config[1]:: 130 Get and set options in .git/config. 131 132gitlink:git-unpack-objects[1]:: 133 Unpacks objects out of a packed archive. 134 135gitlink:git-update-index[1]:: 136 Registers files in the working tree to the index. 137 138gitlink:git-write-tree[1]:: 139 Creates a tree from the index. 140 141 142Interrogation commands 143~~~~~~~~~~~~~~~~~~~~~~ 144 145gitlink:git-cat-file[1]:: 146 Provide content or type/size information for repository objects. 147 148gitlink:git-describe[1]:: 149 Show the most recent tag that is reachable from a commit. 150 151gitlink:git-diff-index[1]:: 152 Compares content and mode of blobs between the index and repository. 153 154gitlink:git-diff-files[1]:: 155 Compares files in the working tree and the index. 156 157gitlink:git-diff-stages[1]:: 158 Compares two "merge stages" in the index. 159 160gitlink:git-diff-tree[1]:: 161 Compares the content and mode of blobs found via two tree objects. 162 163gitlink:git-fsck-objects[1]:: 164 Verifies the connectivity and validity of the objects in the database. 165 166gitlink:git-ls-files[1]:: 167 Information about files in the index and the working tree. 168 169gitlink:git-ls-tree[1]:: 170 Displays a tree object in human readable form. 171 172gitlink:git-merge-base[1]:: 173 Finds as good common ancestors as possible for a merge. 174 175gitlink:git-name-rev[1]:: 176 Find symbolic names for given revs. 177 178gitlink:git-pack-redundant[1]:: 179 Find redundant pack files. 180 181gitlink:git-rev-list[1]:: 182 Lists commit objects in reverse chronological order. 183 184gitlink:git-show-index[1]:: 185 Displays contents of a pack idx file. 186 187gitlink:git-tar-tree[1]:: 188 Creates a tar archive of the files in the named tree object. 189 190gitlink:git-unpack-file[1]:: 191 Creates a temporary file with a blob's contents. 192 193gitlink:git-var[1]:: 194 Displays a git logical variable. 195 196gitlink:git-verify-pack[1]:: 197 Validates packed git archive files. 198 199In general, the interrogate commands do not touch the files in 200the working tree. 201 202 203Synching repositories 204~~~~~~~~~~~~~~~~~~~~~ 205 206gitlink:git-fetch-pack[1]:: 207 Updates from a remote repository (engine for ssh and 208 local transport). 209 210gitlink:git-http-fetch[1]:: 211 Downloads a remote git repository via HTTP by walking 212 commit chain. 213 214gitlink:git-local-fetch[1]:: 215 Duplicates another git repository on a local system by 216 walking commit chain. 217 218gitlink:git-peek-remote[1]:: 219 Lists references on a remote repository using 220 upload-pack protocol (engine for ssh and local 221 transport). 222 223gitlink:git-receive-pack[1]:: 224 Invoked by 'git-send-pack' to receive what is pushed to it. 225 226gitlink:git-send-pack[1]:: 227 Pushes to a remote repository, intelligently. 228 229gitlink:git-http-push[1]:: 230 Push missing objects using HTTP/DAV. 231 232gitlink:git-shell[1]:: 233 Restricted shell for GIT-only SSH access. 234 235gitlink:git-ssh-fetch[1]:: 236 Pulls from a remote repository over ssh connection by 237 walking commit chain. 238 239gitlink:git-ssh-upload[1]:: 240 Helper "server-side" program used by git-ssh-fetch. 241 242gitlink:git-update-server-info[1]:: 243 Updates auxiliary information on a dumb server to help 244 clients discover references and packs on it. 245 246gitlink:git-upload-pack[1]:: 247 Invoked by 'git-fetch-pack' to push 248 what are asked for. 249 250 251High-level commands (porcelain) 252------------------------------- 253 254We separate the porcelain commands into the main commands and some 255ancillary user utilities. 256 257Main porcelain commands 258~~~~~~~~~~~~~~~~~~~~~~~ 259 260gitlink:git-add[1]:: 261 Add paths to the index. 262 263gitlink:git-am[1]:: 264 Apply patches from a mailbox, but cooler. 265 266gitlink:git-applymbox[1]:: 267 Apply patches from a mailbox, original version by Linus. 268 269gitlink:git-bisect[1]:: 270 Find the change that introduced a bug by binary search. 271 272gitlink:git-branch[1]:: 273 Create and Show branches. 274 275gitlink:git-checkout[1]:: 276 Checkout and switch to a branch. 277 278gitlink:git-cherry-pick[1]:: 279 Cherry-pick the effect of an existing commit. 280 281gitlink:git-clean[1]:: 282 Remove untracked files from the working tree. 283 284gitlink:git-clone[1]:: 285 Clones a repository into a new directory. 286 287gitlink:git-commit[1]:: 288 Record changes to the repository. 289 290gitlink:git-diff[1]:: 291 Show changes between commits, commit and working tree, etc. 292 293gitlink:git-fetch[1]:: 294 Download from a remote repository via various protocols. 295 296gitlink:git-format-patch[1]:: 297 Prepare patches for e-mail submission. 298 299gitlink:git-grep[1]:: 300 Print lines matching a pattern. 301 302gitlink:gitk[1]:: 303 The git repository browser. 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 485Configuration Mechanism 486----------------------- 487 488Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file 489is used to hold per-repository configuration options. It is a 490simple text file modeled after `.ini` format familiar to some 491people. Here is an example: 492 493------------ 494# 495# A '#' or ';' character indicates a comment. 496# 497 498; core variables 499[core] 500 ; Don't trust file modes 501 filemode = false 502 503; user identity 504[user] 505 name = "Junio C Hamano" 506 email = "junkio@twinsun.com" 507 508------------ 509 510Various commands read from the configuration file and adjust 511their operation accordingly. 512 513 514Identifier Terminology 515---------------------- 516<object>:: 517 Indicates the object name for any type of object. 518 519<blob>:: 520 Indicates a blob object name. 521 522<tree>:: 523 Indicates a tree object name. 524 525<commit>:: 526 Indicates a commit object name. 527 528<tree-ish>:: 529 Indicates a tree, commit or tag object name. A 530 command that takes a <tree-ish> argument ultimately wants to 531 operate on a <tree> object but automatically dereferences 532 <commit> and <tag> objects that point at a <tree>. 533 534<type>:: 535 Indicates that an object type is required. 536 Currently one of: `blob`, `tree`, `commit`, or `tag`. 537 538<file>:: 539 Indicates a filename - almost always relative to the 540 root of the tree structure `GIT_INDEX_FILE` describes. 541 542Symbolic Identifiers 543-------------------- 544Any git command accepting any <object> can also use the following 545symbolic notation: 546 547HEAD:: 548 indicates the head of the current branch (i.e. the 549 contents of `$GIT_DIR/HEAD`). 550 551<tag>:: 552 a valid tag 'name' 553 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). 554 555<head>:: 556 a valid head 'name' 557 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). 558 559 560File/Directory Structure 561------------------------ 562 563Please see link:repository-layout.html[repository layout] document. 564 565Read link:hooks.html[hooks] for more details about each hook. 566 567Higher level SCMs may provide and manage additional information in the 568`$GIT_DIR`. 569 570 571Terminology 572----------- 573Please see link:glossary.html[glossary] document. 574 575 576Environment Variables 577--------------------- 578Various git commands use the following environment variables: 579 580The git Repository 581~~~~~~~~~~~~~~~~~~ 582These environment variables apply to 'all' core git commands. Nb: it 583is worth noting that they may be used/overridden by SCMS sitting above 584git so take care if using Cogito etc. 585 586'GIT_INDEX_FILE':: 587 This environment allows the specification of an alternate 588 index file. If not specified, the default of `$GIT_DIR/index` 589 is used. 590 591'GIT_OBJECT_DIRECTORY':: 592 If the object storage directory is specified via this 593 environment variable then the sha1 directories are created 594 underneath - otherwise the default `$GIT_DIR/objects` 595 directory is used. 596 597'GIT_ALTERNATE_OBJECT_DIRECTORIES':: 598 Due to the immutable nature of git objects, old objects can be 599 archived into shared, read-only directories. This variable 600 specifies a ":" separated list of git object directories which 601 can be used to search for git objects. New objects will not be 602 written to these directories. 603 604'GIT_DIR':: 605 If the 'GIT_DIR' environment variable is set then it 606 specifies a path to use instead of the default `.git` 607 for the base of the repository. 608 609git Commits 610~~~~~~~~~~~ 611'GIT_AUTHOR_NAME':: 612'GIT_AUTHOR_EMAIL':: 613'GIT_AUTHOR_DATE':: 614'GIT_COMMITTER_NAME':: 615'GIT_COMMITTER_EMAIL':: 616 see gitlink:git-commit-tree[1] 617 618git Diffs 619~~~~~~~~~ 620'GIT_DIFF_OPTS':: 621'GIT_EXTERNAL_DIFF':: 622 see the "generating patches" section in : 623 gitlink:git-diff-index[1]; 624 gitlink:git-diff-files[1]; 625 gitlink:git-diff-tree[1] 626 627other 628~~~~~ 629'GIT_PAGER':: 630 This environment variable overrides `$PAGER`. 631 632'GIT_TRACE':: 633 If this variable is set to "1", "2" or "true" (comparison 634 is case insensitive), git will print `trace:` messages on 635 stderr telling about alias expansion, built-in command 636 execution and external command execution. 637 If this variable is set to an integer value greater than 1 638 and lower than 10 (strictly) then git will interpret this 639 value as an open file descriptor and will try to write the 640 trace messages into this file descriptor. 641 Alternatively, if this variable is set to an absolute path 642 (starting with a '/' character), git will interpret this 643 as a file path and will try to write the trace messages 644 into it. 645 646Discussion[[Discussion]] 647------------------------ 648include::README[] 649 650Authors 651------- 652* git's founding father is Linus Torvalds <torvalds@osdl.org>. 653* The current git nurse is Junio C Hamano <junkio@cox.net>. 654* The git potty was written by Andres Ericsson <ae@op5.se>. 655* General upbringing is handled by the git-list <git@vger.kernel.org>. 656 657Documentation 658-------------- 659The documentation for git suite was started by David Greaves 660<david@dgreaves.com>, and later enhanced greatly by the 661contributors on the git-list <git@vger.kernel.org>. 662 663GIT 664--- 665Part of the gitlink:git[7] suite 666