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