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