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-svnimport[1]:: 401 Import a SVN repository into git. 402 403gitlink:git-sh-setup[1]:: 404 Common git shell script setup code. 405 406gitlink:git-symbolic-ref[1]:: 407 Read and modify symbolic refs. 408 409gitlink:git-tag[1]:: 410 An example script to create a tag object signed with GPG. 411 412gitlink:git-update-ref[1]:: 413 Update the object name stored in a ref safely. 414 415 416Interrogators: 417 418gitlink:git-annotate[1]:: 419 Annotate file lines with commit info. 420 421gitlink:git-blame[1]:: 422 Blame file lines on commits. 423 424gitlink:git-check-ref-format[1]:: 425 Make sure ref name is well formed. 426 427gitlink:git-cherry[1]:: 428 Find commits not merged upstream. 429 430gitlink:git-count-objects[1]:: 431 Count unpacked number of objects and their disk consumption. 432 433gitlink:git-daemon[1]:: 434 A really simple server for git repositories. 435 436gitlink:git-fmt-merge-msg[1]:: 437 Produce a merge commit message. 438 439gitlink:git-get-tar-commit-id[1]:: 440 Extract commit ID from an archive created using git-tar-tree. 441 442gitlink:git-imap-send[1]:: 443 Dump a mailbox from stdin into an imap folder. 444 445gitlink:git-mailinfo[1]:: 446 Extracts patch and authorship information from a single 447 e-mail message, optionally transliterating the commit 448 message into utf-8. 449 450gitlink:git-mailsplit[1]:: 451 A stupid program to split UNIX mbox format mailbox into 452 individual pieces of e-mail. 453 454gitlink:git-merge-tree[1]:: 455 Show three-way merge without touching index. 456 457gitlink:git-patch-id[1]:: 458 Compute unique ID for a patch. 459 460gitlink:git-parse-remote[1]:: 461 Routines to help parsing `$GIT_DIR/remotes/` files. 462 463gitlink:git-request-pull[1]:: 464 git-request-pull. 465 466gitlink:git-rev-parse[1]:: 467 Pick out and massage parameters. 468 469gitlink:git-send-email[1]:: 470 Send patch e-mails out of "format-patch --mbox" output. 471 472gitlink:git-symbolic-ref[1]:: 473 Read and modify symbolic refs. 474 475gitlink:git-stripspace[1]:: 476 Filter out empty lines. 477 478 479Commands not yet documented 480--------------------------- 481 482gitlink:gitk[1]:: 483 The gitk repository browser. 484 485 486Configuration Mechanism 487----------------------- 488 489Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file 490is used to hold per-repository configuration options. It is a 491simple text file modeled after `.ini` format familiar to some 492people. Here is an example: 493 494------------ 495# 496# A '#' or ';' character indicates a comment. 497# 498 499; core variables 500[core] 501 ; Don't trust file modes 502 filemode = false 503 504; user identity 505[user] 506 name = "Junio C Hamano" 507 email = "junkio@twinsun.com" 508 509------------ 510 511Various commands read from the configuration file and adjust 512their operation accordingly. 513 514 515Identifier Terminology 516---------------------- 517<object>:: 518 Indicates the object name for any type of object. 519 520<blob>:: 521 Indicates a blob object name. 522 523<tree>:: 524 Indicates a tree object name. 525 526<commit>:: 527 Indicates a commit object name. 528 529<tree-ish>:: 530 Indicates a tree, commit or tag object name. A 531 command that takes a <tree-ish> argument ultimately wants to 532 operate on a <tree> object but automatically dereferences 533 <commit> and <tag> objects that point at a <tree>. 534 535<type>:: 536 Indicates that an object type is required. 537 Currently one of: `blob`, `tree`, `commit`, or `tag`. 538 539<file>:: 540 Indicates a filename - almost always relative to the 541 root of the tree structure `GIT_INDEX_FILE` describes. 542 543Symbolic Identifiers 544-------------------- 545Any git command accepting any <object> can also use the following 546symbolic notation: 547 548HEAD:: 549 indicates the head of the current branch (i.e. the 550 contents of `$GIT_DIR/HEAD`). 551 552<tag>:: 553 a valid tag 'name' 554 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). 555 556<head>:: 557 a valid head 'name' 558 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). 559 560 561File/Directory Structure 562------------------------ 563 564Please see link:repository-layout.html[repository layout] document. 565 566Read link:hooks.html[hooks] for more details about each hook. 567 568Higher level SCMs may provide and manage additional information in the 569`$GIT_DIR`. 570 571 572Terminology 573----------- 574Please see link:glossary.html[glossary] document. 575 576 577Environment Variables 578--------------------- 579Various git commands use the following environment variables: 580 581The git Repository 582~~~~~~~~~~~~~~~~~~ 583These environment variables apply to 'all' core git commands. Nb: it 584is worth noting that they may be used/overridden by SCMS sitting above 585git so take care if using Cogito etc. 586 587'GIT_INDEX_FILE':: 588 This environment allows the specification of an alternate 589 index file. If not specified, the default of `$GIT_DIR/index` 590 is used. 591 592'GIT_OBJECT_DIRECTORY':: 593 If the object storage directory is specified via this 594 environment variable then the sha1 directories are created 595 underneath - otherwise the default `$GIT_DIR/objects` 596 directory is used. 597 598'GIT_ALTERNATE_OBJECT_DIRECTORIES':: 599 Due to the immutable nature of git objects, old objects can be 600 archived into shared, read-only directories. This variable 601 specifies a ":" separated list of git object directories which 602 can be used to search for git objects. New objects will not be 603 written to these directories. 604 605'GIT_DIR':: 606 If the 'GIT_DIR' environment variable is set then it 607 specifies a path to use instead of the default `.git` 608 for the base of the repository. 609 610git Commits 611~~~~~~~~~~~ 612'GIT_AUTHOR_NAME':: 613'GIT_AUTHOR_EMAIL':: 614'GIT_AUTHOR_DATE':: 615'GIT_COMMITTER_NAME':: 616'GIT_COMMITTER_EMAIL':: 617 see gitlink:git-commit-tree[1] 618 619git Diffs 620~~~~~~~~~ 621'GIT_DIFF_OPTS':: 622'GIT_EXTERNAL_DIFF':: 623 see the "generating patches" section in : 624 gitlink:git-diff-index[1]; 625 gitlink:git-diff-files[1]; 626 gitlink:git-diff-tree[1] 627 628other 629~~~~~ 630'GIT_TRACE':: 631 If this variable is set git will print `trace:` messages on 632 stderr telling about alias expansion, built-in command 633 execution and external command execution. 634 635Discussion[[Discussion]] 636------------------------ 637include::README[] 638 639Authors 640------- 641* git's founding father is Linus Torvalds <torvalds@osdl.org>. 642* The current git nurse is Junio C Hamano <junkio@cox.net>. 643* The git potty was written by Andres Ericsson <ae@op5.se>. 644* General upbringing is handled by the git-list <git@vger.kernel.org>. 645 646Documentation 647-------------- 648The documentation for git suite was started by David Greaves 649<david@dgreaves.com>, and later enhanced greatly by the 650contributors on the git-list <git@vger.kernel.org>. 651 652GIT 653--- 654Part of the gitlink:git[7] suite 655