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-archive[1]:: 270 Creates an archive of files from a named tree. 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:gitk[1]:: 306 The git repository browser. 307 308gitlink:git-log[1]:: 309 Shows commit logs. 310 311gitlink:git-ls-remote[1]:: 312 Shows references in a remote or local repository. 313 314gitlink:git-merge[1]:: 315 Grand unified merge driver. 316 317gitlink:git-mv[1]:: 318 Move or rename a file, a directory, or a symlink. 319 320gitlink:git-pull[1]:: 321 Fetch from and merge with a remote repository. 322 323gitlink:git-push[1]:: 324 Update remote refs along with associated objects. 325 326gitlink:git-rebase[1]:: 327 Rebase local commits to the updated upstream head. 328 329gitlink:git-repack[1]:: 330 Pack unpacked objects in a repository. 331 332gitlink:git-rerere[1]:: 333 Reuse recorded resolution of conflicted merges. 334 335gitlink:git-reset[1]:: 336 Reset current HEAD to the specified state. 337 338gitlink:git-resolve[1]:: 339 Merge two commits. 340 341gitlink:git-revert[1]:: 342 Revert an existing commit. 343 344gitlink:git-rm[1]:: 345 Remove files from the working tree and from the index. 346 347gitlink:git-shortlog[1]:: 348 Summarizes 'git log' output. 349 350gitlink:git-show[1]:: 351 Show one commit log and its diff. 352 353gitlink:git-show-branch[1]:: 354 Show branches and their commits. 355 356gitlink:git-status[1]:: 357 Shows the working tree status. 358 359gitlink:git-verify-tag[1]:: 360 Check the GPG signature of tag. 361 362gitlink:git-whatchanged[1]:: 363 Shows commit logs and differences they introduce. 364 365 366Ancillary Commands 367~~~~~~~~~~~~~~~~~~ 368Manipulators: 369 370gitlink:git-applypatch[1]:: 371 Apply one patch extracted from an e-mail. 372 373gitlink:git-archimport[1]:: 374 Import an arch repository into git. 375 376gitlink:git-convert-objects[1]:: 377 Converts old-style git repository. 378 379gitlink:git-cvsimport[1]:: 380 Salvage your data out of another SCM people love to hate. 381 382gitlink:git-cvsexportcommit[1]:: 383 Export a single commit to a CVS checkout. 384 385gitlink:git-cvsserver[1]:: 386 A CVS server emulator for git. 387 388gitlink:git-lost-found[1]:: 389 Recover lost refs that luckily have not yet been pruned. 390 391gitlink:git-merge-one-file[1]:: 392 The standard helper program to use with `git-merge-index`. 393 394gitlink:git-prune[1]:: 395 Prunes all unreachable objects from the object database. 396 397gitlink:git-quiltimport[1]:: 398 Applies a quilt patchset onto the current branch. 399 400gitlink:git-relink[1]:: 401 Hardlink common objects in local repositories. 402 403gitlink:git-svn[1]:: 404 Bidirectional operation between a single Subversion branch and git. 405 406gitlink:git-svnimport[1]:: 407 Import a SVN repository into git. 408 409gitlink:git-sh-setup[1]:: 410 Common git shell script setup code. 411 412gitlink:git-symbolic-ref[1]:: 413 Read and modify symbolic refs. 414 415gitlink:git-tag[1]:: 416 An example script to create a tag object signed with GPG. 417 418gitlink:git-update-ref[1]:: 419 Update the object name stored in a ref safely. 420 421 422Interrogators: 423 424gitlink:git-annotate[1]:: 425 Annotate file lines with commit info. 426 427gitlink:git-blame[1]:: 428 Blame file lines on commits. 429 430gitlink:git-check-ref-format[1]:: 431 Make sure ref name is well formed. 432 433gitlink:git-cherry[1]:: 434 Find commits not merged upstream. 435 436gitlink:git-count-objects[1]:: 437 Count unpacked number of objects and their disk consumption. 438 439gitlink:git-daemon[1]:: 440 A really simple server for git repositories. 441 442gitlink:git-fmt-merge-msg[1]:: 443 Produce a merge commit message. 444 445gitlink:git-get-tar-commit-id[1]:: 446 Extract commit ID from an archive created using git-tar-tree. 447 448gitlink:git-imap-send[1]:: 449 Dump a mailbox from stdin into an imap folder. 450 451gitlink:git-instaweb[1]:: 452 Instantly browse your working repository in gitweb. 453 454gitlink:git-mailinfo[1]:: 455 Extracts patch and authorship information from a single 456 e-mail message, optionally transliterating the commit 457 message into utf-8. 458 459gitlink:git-mailsplit[1]:: 460 A stupid program to split UNIX mbox format mailbox into 461 individual pieces of e-mail. 462 463gitlink:git-merge-tree[1]:: 464 Show three-way merge without touching index. 465 466gitlink:git-patch-id[1]:: 467 Compute unique ID for a patch. 468 469gitlink:git-parse-remote[1]:: 470 Routines to help parsing `$GIT_DIR/remotes/` files. 471 472gitlink:git-request-pull[1]:: 473 git-request-pull. 474 475gitlink:git-rev-parse[1]:: 476 Pick out and massage parameters. 477 478gitlink:git-send-email[1]:: 479 Send patch e-mails out of "format-patch --mbox" output. 480 481gitlink:git-symbolic-ref[1]:: 482 Read and modify symbolic refs. 483 484gitlink:git-stripspace[1]:: 485 Filter out empty lines. 486 487 488Configuration Mechanism 489----------------------- 490 491Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file 492is used to hold per-repository configuration options. It is a 493simple text file modeled after `.ini` format familiar to some 494people. Here is an example: 495 496------------ 497# 498# A '#' or ';' character indicates a comment. 499# 500 501; core variables 502[core] 503 ; Don't trust file modes 504 filemode = false 505 506; user identity 507[user] 508 name = "Junio C Hamano" 509 email = "junkio@twinsun.com" 510 511------------ 512 513Various commands read from the configuration file and adjust 514their operation accordingly. 515 516 517Identifier Terminology 518---------------------- 519<object>:: 520 Indicates the object name for any type of object. 521 522<blob>:: 523 Indicates a blob object name. 524 525<tree>:: 526 Indicates a tree object name. 527 528<commit>:: 529 Indicates a commit object name. 530 531<tree-ish>:: 532 Indicates a tree, commit or tag object name. A 533 command that takes a <tree-ish> argument ultimately wants to 534 operate on a <tree> object but automatically dereferences 535 <commit> and <tag> objects that point at a <tree>. 536 537<type>:: 538 Indicates that an object type is required. 539 Currently one of: `blob`, `tree`, `commit`, or `tag`. 540 541<file>:: 542 Indicates a filename - almost always relative to the 543 root of the tree structure `GIT_INDEX_FILE` describes. 544 545Symbolic Identifiers 546-------------------- 547Any git command accepting any <object> can also use the following 548symbolic notation: 549 550HEAD:: 551 indicates the head of the current branch (i.e. the 552 contents of `$GIT_DIR/HEAD`). 553 554<tag>:: 555 a valid tag 'name' 556 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). 557 558<head>:: 559 a valid head 'name' 560 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). 561 562 563File/Directory Structure 564------------------------ 565 566Please see link:repository-layout.html[repository layout] document. 567 568Read link:hooks.html[hooks] for more details about each hook. 569 570Higher level SCMs may provide and manage additional information in the 571`$GIT_DIR`. 572 573 574Terminology 575----------- 576Please see link:glossary.html[glossary] document. 577 578 579Environment Variables 580--------------------- 581Various git commands use the following environment variables: 582 583The git Repository 584~~~~~~~~~~~~~~~~~~ 585These environment variables apply to 'all' core git commands. Nb: it 586is worth noting that they may be used/overridden by SCMS sitting above 587git so take care if using Cogito etc. 588 589'GIT_INDEX_FILE':: 590 This environment allows the specification of an alternate 591 index file. If not specified, the default of `$GIT_DIR/index` 592 is used. 593 594'GIT_OBJECT_DIRECTORY':: 595 If the object storage directory is specified via this 596 environment variable then the sha1 directories are created 597 underneath - otherwise the default `$GIT_DIR/objects` 598 directory is used. 599 600'GIT_ALTERNATE_OBJECT_DIRECTORIES':: 601 Due to the immutable nature of git objects, old objects can be 602 archived into shared, read-only directories. This variable 603 specifies a ":" separated list of git object directories which 604 can be used to search for git objects. New objects will not be 605 written to these directories. 606 607'GIT_DIR':: 608 If the 'GIT_DIR' environment variable is set then it 609 specifies a path to use instead of the default `.git` 610 for the base of the repository. 611 612git Commits 613~~~~~~~~~~~ 614'GIT_AUTHOR_NAME':: 615'GIT_AUTHOR_EMAIL':: 616'GIT_AUTHOR_DATE':: 617'GIT_COMMITTER_NAME':: 618'GIT_COMMITTER_EMAIL':: 619 see gitlink:git-commit-tree[1] 620 621git Diffs 622~~~~~~~~~ 623'GIT_DIFF_OPTS':: 624'GIT_EXTERNAL_DIFF':: 625 see the "generating patches" section in : 626 gitlink:git-diff-index[1]; 627 gitlink:git-diff-files[1]; 628 gitlink:git-diff-tree[1] 629 630other 631~~~~~ 632'GIT_PAGER':: 633 This environment variable overrides `$PAGER`. 634 635'GIT_TRACE':: 636 If this variable is set to "1", "2" or "true" (comparison 637 is case insensitive), git will print `trace:` messages on 638 stderr telling about alias expansion, built-in command 639 execution and external command execution. 640 If this variable is set to an integer value greater than 1 641 and lower than 10 (strictly) then git will interpret this 642 value as an open file descriptor and will try to write the 643 trace messages into this file descriptor. 644 Alternatively, if this variable is set to an absolute path 645 (starting with a '/' character), git will interpret this 646 as a file path and will try to write the trace messages 647 into it. 648 649Discussion[[Discussion]] 650------------------------ 651include::README[] 652 653Authors 654------- 655* git's founding father is Linus Torvalds <torvalds@osdl.org>. 656* The current git nurse is Junio C Hamano <junkio@cox.net>. 657* The git potty was written by Andres Ericsson <ae@op5.se>. 658* General upbringing is handled by the git-list <git@vger.kernel.org>. 659 660Documentation 661-------------- 662The documentation for git suite was started by David Greaves 663<david@dgreaves.com>, and later enhanced greatly by the 664contributors on the git-list <git@vger.kernel.org>. 665 666GIT 667--- 668Part of the gitlink:git[7] suite 669