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-fetch-pack[1]:: 196 Updates from a remote repository (engine for ssh and 197 local transport). 198 199gitlink:git-http-fetch[1]:: 200 Downloads a remote git repository via HTTP by walking 201 commit chain. 202 203gitlink:git-local-fetch[1]:: 204 Duplicates another git repository on a local system by 205 walking commit chain. 206 207gitlink:git-peek-remote[1]:: 208 Lists references on a remote repository using 209 upload-pack protocol (engine for ssh and local 210 transport). 211 212gitlink:git-receive-pack[1]:: 213 Invoked by 'git-send-pack' to receive what is pushed to it. 214 215gitlink:git-send-pack[1]:: 216 Pushes to a remote repository, intelligently. 217 218gitlink:git-http-push[1]:: 219 Push missing objects using HTTP/DAV. 220 221gitlink:git-shell[1]:: 222 Restricted shell for GIT-only SSH access. 223 224gitlink:git-ssh-fetch[1]:: 225 Pulls from a remote repository over ssh connection by 226 walking commit chain. 227 228gitlink:git-ssh-upload[1]:: 229 Helper "server-side" program used by git-ssh-fetch. 230 231gitlink:git-update-server-info[1]:: 232 Updates auxiliary information on a dumb server to help 233 clients discover references and packs on it. 234 235gitlink:git-upload-pack[1]:: 236 Invoked by 'git-fetch-pack' to push 237 what are asked for. 238 239gitlink:git-upload-tar[1]:: 240 Invoked by 'git-tar-tree --remote' to return the tar 241 archive the other end asked for. 242 243 244High-level commands (porcelain) 245------------------------------- 246 247We separate the porcelain commands into the main commands and some 248ancillary user utilities. 249 250Main porcelain commands 251~~~~~~~~~~~~~~~~~~~~~~~ 252 253gitlink:git-add[1]:: 254 Add paths to the index. 255 256gitlink:git-am[1]:: 257 Apply patches from a mailbox, but cooler. 258 259gitlink:git-applymbox[1]:: 260 Apply patches from a mailbox, original version by Linus. 261 262gitlink:git-bisect[1]:: 263 Find the change that introduced a bug by binary search. 264 265gitlink:git-branch[1]:: 266 Create and Show branches. 267 268gitlink:git-checkout[1]:: 269 Checkout and switch to a branch. 270 271gitlink:git-cherry-pick[1]:: 272 Cherry-pick the effect of an existing commit. 273 274gitlink:git-clean[1]:: 275 Remove untracked files from the working tree. 276 277gitlink:git-clone[1]:: 278 Clones a repository into a new directory. 279 280gitlink:git-commit[1]:: 281 Record changes to the repository. 282 283gitlink:git-diff[1]:: 284 Show changes between commits, commit and working tree, etc. 285 286gitlink:git-fetch[1]:: 287 Download from a remote repository via various protocols. 288 289gitlink:git-format-patch[1]:: 290 Prepare patches for e-mail submission. 291 292gitlink:git-grep[1]:: 293 Print lines matching a pattern. 294 295gitlink:git-log[1]:: 296 Shows commit logs. 297 298gitlink:git-ls-remote[1]:: 299 Shows references in a remote or local repository. 300 301gitlink:git-merge[1]:: 302 Grand unified merge driver. 303 304gitlink:git-mv[1]:: 305 Move or rename a file, a directory, or a symlink. 306 307gitlink:git-pull[1]:: 308 Fetch from and merge with a remote repository. 309 310gitlink:git-push[1]:: 311 Update remote refs along with associated objects. 312 313gitlink:git-rebase[1]:: 314 Rebase local commits to the updated upstream head. 315 316gitlink:git-repack[1]:: 317 Pack unpacked objects in a repository. 318 319gitlink:git-rerere[1]:: 320 Reuse recorded resolution of conflicted merges. 321 322gitlink:git-reset[1]:: 323 Reset current HEAD to the specified state. 324 325gitlink:git-resolve[1]:: 326 Merge two commits. 327 328gitlink:git-revert[1]:: 329 Revert an existing commit. 330 331gitlink:git-rm[1]:: 332 Remove files from the working tree and from the index. 333 334gitlink:git-shortlog[1]:: 335 Summarizes 'git log' output. 336 337gitlink:git-show[1]:: 338 Show one commit log and its diff. 339 340gitlink:git-show-branch[1]:: 341 Show branches and their commits. 342 343gitlink:git-status[1]:: 344 Shows the working tree status. 345 346gitlink:git-verify-tag[1]:: 347 Check the GPG signature of tag. 348 349gitlink:git-whatchanged[1]:: 350 Shows commit logs and differences they introduce. 351 352 353Ancillary Commands 354~~~~~~~~~~~~~~~~~~ 355Manipulators: 356 357gitlink:git-applypatch[1]:: 358 Apply one patch extracted from an e-mail. 359 360gitlink:git-archimport[1]:: 361 Import an arch repository into git. 362 363gitlink:git-convert-objects[1]:: 364 Converts old-style git repository. 365 366gitlink:git-cvsimport[1]:: 367 Salvage your data out of another SCM people love to hate. 368 369gitlink:git-cvsexportcommit[1]:: 370 Export a single commit to a CVS checkout. 371 372gitlink:git-cvsserver[1]:: 373 A CVS server emulator for git. 374 375gitlink:git-lost-found[1]:: 376 Recover lost refs that luckily have not yet been pruned. 377 378gitlink:git-merge-one-file[1]:: 379 The standard helper program to use with `git-merge-index`. 380 381gitlink:git-prune[1]:: 382 Prunes all unreachable objects from the object database. 383 384gitlink:git-quiltimport[1]:: 385 Applies a quilt patchset onto the current branch. 386 387gitlink:git-relink[1]:: 388 Hardlink common objects in local repositories. 389 390gitlink:git-svnimport[1]:: 391 Import a SVN repository into git. 392 393gitlink:git-sh-setup[1]:: 394 Common git shell script setup code. 395 396gitlink:git-symbolic-ref[1]:: 397 Read and modify symbolic refs. 398 399gitlink:git-tag[1]:: 400 An example script to create a tag object signed with GPG. 401 402gitlink:git-update-ref[1]:: 403 Update the object name stored in a ref safely. 404 405 406Interrogators: 407 408gitlink:git-annotate[1]:: 409 Annotate file lines with commit info. 410 411gitlink:git-blame[1]:: 412 Blame file lines on commits. 413 414gitlink:git-check-ref-format[1]:: 415 Make sure ref name is well formed. 416 417gitlink:git-cherry[1]:: 418 Find commits not merged upstream. 419 420gitlink:git-count-objects[1]:: 421 Count unpacked number of objects and their disk consumption. 422 423gitlink:git-daemon[1]:: 424 A really simple server for git repositories. 425 426gitlink:git-fmt-merge-msg[1]:: 427 Produce a merge commit message. 428 429gitlink:git-get-tar-commit-id[1]:: 430 Extract commit ID from an archive created using git-tar-tree. 431 432gitlink:git-imap-send[1]:: 433 Dump a mailbox from stdin into an imap folder. 434 435gitlink:git-mailinfo[1]:: 436 Extracts patch and authorship information from a single 437 e-mail message, optionally transliterating the commit 438 message into utf-8. 439 440gitlink:git-mailsplit[1]:: 441 A stupid program to split UNIX mbox format mailbox into 442 individual pieces of e-mail. 443 444gitlink:git-merge-tree[1]:: 445 Show three-way merge without touching index. 446 447gitlink:git-patch-id[1]:: 448 Compute unique ID for a patch. 449 450gitlink:git-parse-remote[1]:: 451 Routines to help parsing `$GIT_DIR/remotes/` files. 452 453gitlink:git-request-pull[1]:: 454 git-request-pull. 455 456gitlink:git-rev-parse[1]:: 457 Pick out and massage parameters. 458 459gitlink:git-send-email[1]:: 460 Send patch e-mails out of "format-patch --mbox" output. 461 462gitlink:git-symbolic-ref[1]:: 463 Read and modify symbolic refs. 464 465gitlink:git-stripspace[1]:: 466 Filter out empty lines. 467 468 469Commands not yet documented 470--------------------------- 471 472gitlink:gitk[1]:: 473 The gitk repository browser. 474 475 476Configuration Mechanism 477----------------------- 478 479Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file 480is used to hold per-repository configuration options. It is a 481simple text file modelled after `.ini` format familiar to some 482people. Here is an example: 483 484------------ 485# 486# A '#' or ';' character indicates a comment. 487# 488 489; core variables 490[core] 491 ; Don't trust file modes 492 filemode = false 493 494; user identity 495[user] 496 name = "Junio C Hamano" 497 email = "junkio@twinsun.com" 498 499------------ 500 501Various commands read from the configuration file and adjust 502their operation accordingly. 503 504 505Identifier Terminology 506---------------------- 507<object>:: 508 Indicates the object name for any type of object. 509 510<blob>:: 511 Indicates a blob object name. 512 513<tree>:: 514 Indicates a tree object name. 515 516<commit>:: 517 Indicates a commit object name. 518 519<tree-ish>:: 520 Indicates a tree, commit or tag object name. A 521 command that takes a <tree-ish> argument ultimately wants to 522 operate on a <tree> object but automatically dereferences 523 <commit> and <tag> objects that point at a <tree>. 524 525<type>:: 526 Indicates that an object type is required. 527 Currently one of: `blob`, `tree`, `commit`, or `tag`. 528 529<file>:: 530 Indicates a filename - almost always relative to the 531 root of the tree structure `GIT_INDEX_FILE` describes. 532 533Symbolic Identifiers 534-------------------- 535Any git command accepting any <object> can also use the following 536symbolic notation: 537 538HEAD:: 539 indicates the head of the current branch (i.e. the 540 contents of `$GIT_DIR/HEAD`). 541 542<tag>:: 543 a valid tag 'name' 544 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). 545 546<head>:: 547 a valid head 'name' 548 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). 549 550 551File/Directory Structure 552------------------------ 553 554Please see link:repository-layout.html[repository layout] document. 555 556Read link:hooks.html[hooks] for more details about each hook. 557 558Higher level SCMs may provide and manage additional information in the 559`$GIT_DIR`. 560 561 562Terminology 563----------- 564Please see link:glossary.html[glossary] document. 565 566 567Environment Variables 568--------------------- 569Various git commands use the following environment variables: 570 571The git Repository 572~~~~~~~~~~~~~~~~~~ 573These environment variables apply to 'all' core git commands. Nb: it 574is worth noting that they may be used/overridden by SCMS sitting above 575git so take care if using Cogito etc. 576 577'GIT_INDEX_FILE':: 578 This environment allows the specification of an alternate 579 index file. If not specified, the default of `$GIT_DIR/index` 580 is used. 581 582'GIT_OBJECT_DIRECTORY':: 583 If the object storage directory is specified via this 584 environment variable then the sha1 directories are created 585 underneath - otherwise the default `$GIT_DIR/objects` 586 directory is used. 587 588'GIT_ALTERNATE_OBJECT_DIRECTORIES':: 589 Due to the immutable nature of git objects, old objects can be 590 archived into shared, read-only directories. This variable 591 specifies a ":" separated list of git object directories which 592 can be used to search for git objects. New objects will not be 593 written to these directories. 594 595'GIT_DIR':: 596 If the 'GIT_DIR' environment variable is set then it 597 specifies a path to use instead of the default `.git` 598 for the base of the repository. 599 600git Commits 601~~~~~~~~~~~ 602'GIT_AUTHOR_NAME':: 603'GIT_AUTHOR_EMAIL':: 604'GIT_AUTHOR_DATE':: 605'GIT_COMMITTER_NAME':: 606'GIT_COMMITTER_EMAIL':: 607 see gitlink:git-commit-tree[1] 608 609git Diffs 610~~~~~~~~~ 611'GIT_DIFF_OPTS':: 612'GIT_EXTERNAL_DIFF':: 613 see the "generating patches" section in : 614 gitlink:git-diff-index[1]; 615 gitlink:git-diff-files[1]; 616 gitlink:git-diff-tree[1] 617 618Discussion[[Discussion]] 619------------------------ 620include::README[] 621 622Authors 623------- 624* git's founding father is Linus Torvalds <torvalds@osdl.org>. 625* The current git nurse is Junio C Hamano <junkio@cox.net>. 626* The git potty was written by Andres Ericsson <ae@op5.se>. 627* General upbringing is handled by the git-list <git@vger.kernel.org>. 628 629Documentation 630-------------- 631The documentation for git suite was started by David Greaves 632<david@dgreaves.com>, and later enhanced greatly by the 633contributors on the git-list <git@vger.kernel.org>. 634 635GIT 636--- 637Part of the gitlink:git[7] suite 638