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