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