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:tutorial.html[The Tutorial] to get you started, 47and then link:everyday.html[Everyday GIT] as a guide to the 48minimum set of commands you need to know for day-to-day work. 49Most likely, that will get you started, and you can go a long 50way without knowing the low level details too much. 51 52The link:core-tutorial.html[Core tutorial] document covers how things 53internally work. 54 55If you are migrating from CVS, link:cvs-migration.html[cvs 56migration] document may be helpful after you finish the 57tutorial. 58 59After you get the general feel from the tutorial and this 60overview page, you may want to take a look at the 61link:howto-index.html[howto] documents. 62 63 64CORE GIT COMMANDS 65----------------- 66 67If you are writing your own Porcelain, you need to be familiar 68with most of the low level commands --- I suggest starting from 69gitlink:git-update-index[1] and gitlink:git-read-tree[1]. 70 71 72Commands Overview 73----------------- 74The git commands can helpfully be split into those that manipulate 75the repository, the index and the files in the working tree, those that 76interrogate and compare them, and those that moves objects and 77references between repositories. 78 79In addition, git itself comes with a spartan set of porcelain 80commands. They are usable but are not meant to compete with real 81Porcelains. 82 83There are also some ancillary programs that can be viewed as useful 84aids for using the core commands but which are unlikely to be used by 85SCMs layered over git. 86 87Manipulation commands 88~~~~~~~~~~~~~~~~~~~~~ 89gitlink:git-apply[1]:: 90 Reads a "diff -up1" or git generated patch file and 91 applies it to the working tree. 92 93gitlink:git-checkout-index[1]:: 94 Copy files from the index to the working tree. 95 96gitlink:git-commit-tree[1]:: 97 Creates a new commit object. 98 99gitlink:git-hash-object[1]:: 100 Computes the object ID from a file. 101 102gitlink:git-index-pack[1]:: 103 Build pack idx file for an existing packed archive. 104 105gitlink:git-init-db[1]:: 106 Creates an empty git object database, or reinitialize an 107 existing one. 108 109gitlink:git-merge-index[1]:: 110 Runs a merge for files needing merging. 111 112gitlink:git-mktag[1]:: 113 Creates a tag object. 114 115gitlink:git-pack-objects[1]:: 116 Creates a packed archive of objects. 117 118gitlink:git-prune-packed[1]:: 119 Remove extra objects that are already in pack files. 120 121gitlink:git-read-tree[1]:: 122 Reads tree information into the index. 123 124gitlink:git-repo-config[1]:: 125 Get and set options in .git/config. 126 127gitlink:git-unpack-objects[1]:: 128 Unpacks objects out of a packed archive. 129 130gitlink:git-update-index[1]:: 131 Registers files in the working tree to the index. 132 133gitlink:git-write-tree[1]:: 134 Creates a tree from the index. 135 136 137Interrogation commands 138~~~~~~~~~~~~~~~~~~~~~~ 139 140gitlink:git-cat-file[1]:: 141 Provide content or type/size information for repository objects. 142 143gitlink:git-describe[1]:: 144 Show the most recent tag that is reachable from a commit. 145 146gitlink:git-diff-index[1]:: 147 Compares content and mode of blobs between the index and repository. 148 149gitlink:git-diff-files[1]:: 150 Compares files in the working tree and the index. 151 152gitlink:git-diff-stages[1]:: 153 Compares two "merge stages" in the index. 154 155gitlink:git-diff-tree[1]:: 156 Compares the content and mode of blobs found via two tree objects. 157 158gitlink:git-fsck-objects[1]:: 159 Verifies the connectivity and validity of the objects in the database. 160 161gitlink:git-ls-files[1]:: 162 Information about files in the index and the working tree. 163 164gitlink:git-ls-tree[1]:: 165 Displays a tree object in human readable form. 166 167gitlink:git-merge-base[1]:: 168 Finds as good common ancestors as possible for a merge. 169 170gitlink:git-name-rev[1]:: 171 Find symbolic names for given revs. 172 173gitlink:git-pack-redundant[1]:: 174 Find redundant pack files. 175 176gitlink:git-rev-list[1]:: 177 Lists commit objects in reverse chronological order. 178 179gitlink:git-show-index[1]:: 180 Displays contents of a pack idx file. 181 182gitlink:git-tar-tree[1]:: 183 Creates a tar archive of the files in the named tree object. 184 185gitlink:git-unpack-file[1]:: 186 Creates a temporary file with a blob's contents. 187 188gitlink:git-var[1]:: 189 Displays a git logical variable. 190 191gitlink:git-verify-pack[1]:: 192 Validates packed git archive files. 193 194In general, the interrogate commands do not touch the files in 195the working tree. 196 197 198Synching repositories 199~~~~~~~~~~~~~~~~~~~~~ 200 201gitlink:git-clone-pack[1]:: 202 Clones a repository into the current repository (engine 203 for ssh and local transport). 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-clone-pack' and 'git-fetch-pack' to push 247 what are asked for. 248 249 250Porcelain-ish 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-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-shortlog[1]:: 329 Summarizes 'git log' output. 330 331gitlink:git-show-branch[1]:: 332 Show branches and their commits. 333 334gitlink:git-status[1]:: 335 Shows the working tree status. 336 337gitlink:git-verify-tag[1]:: 338 Check the GPG signature of tag. 339 340gitlink:git-whatchanged[1]:: 341 Shows commit logs and differences they introduce. 342 343 344Ancillary Commands 345------------------ 346Manipulators: 347 348gitlink:git-applypatch[1]:: 349 Apply one patch extracted from an e-mail. 350 351gitlink:git-archimport[1]:: 352 Import an arch repository into git. 353 354gitlink:git-convert-objects[1]:: 355 Converts old-style git repository. 356 357gitlink:git-cvsimport[1]:: 358 Salvage your data out of another SCM people love to hate. 359 360gitlink:git-cvsexportcommit[1]:: 361 Export a single commit to a CVS checkout. 362 363gitlink:git-lost-found[1]:: 364 Recover lost refs that luckily have not yet been pruned. 365 366gitlink:git-merge-one-file[1]:: 367 The standard helper program to use with `git-merge-index`. 368 369gitlink:git-prune[1]:: 370 Prunes all unreachable objects from the object database. 371 372gitlink:git-relink[1]:: 373 Hardlink common objects in local repositories. 374 375gitlink:git-svnimport[1]:: 376 Import a SVN repository into git. 377 378gitlink:git-sh-setup[1]:: 379 Common git shell script setup code. 380 381gitlink:git-symbolic-ref[1]:: 382 Read and modify symbolic refs. 383 384gitlink:git-tag[1]:: 385 An example script to create a tag object signed with GPG. 386 387gitlink:git-update-ref[1]:: 388 Update the object name stored in a ref safely. 389 390 391Interrogators: 392 393gitlink:git-check-ref-format[1]:: 394 Make sure ref name is well formed. 395 396gitlink:git-cherry[1]:: 397 Find commits not merged upstream. 398 399gitlink:git-count-objects[1]:: 400 Count unpacked number of objects and their disk consumption. 401 402gitlink:git-daemon[1]:: 403 A really simple server for git repositories. 404 405gitlink:git-get-tar-commit-id[1]:: 406 Extract commit ID from an archive created using git-tar-tree. 407 408gitlink:git-mailinfo[1]:: 409 Extracts patch and authorship information from a single 410 e-mail message, optionally transliterating the commit 411 message into utf-8. 412 413gitlink:git-mailsplit[1]:: 414 A stupid program to split UNIX mbox format mailbox into 415 individual pieces of e-mail. 416 417gitlink:git-patch-id[1]:: 418 Compute unique ID for a patch. 419 420gitlink:git-parse-remote[1]:: 421 Routines to help parsing `$GIT_DIR/remotes/` files. 422 423gitlink:git-request-pull[1]:: 424 git-request-pull. 425 426gitlink:git-rev-parse[1]:: 427 Pick out and massage parameters. 428 429gitlink:git-send-email[1]:: 430 Send patch e-mails out of "format-patch --mbox" output. 431 432gitlink:git-symbolic-ref[1]:: 433 Read and modify symbolic refs. 434 435gitlink:git-stripspace[1]:: 436 Filter out empty lines. 437 438 439Commands not yet documented 440--------------------------- 441 442gitlink:gitk[1]:: 443 The gitk repository browser. 444 445 446Configuration Mechanism 447----------------------- 448 449Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file 450is used to hold per-repository configuration options. It is a 451simple text file modelled after `.ini` format familiar to some 452people. Here is an example: 453 454------------ 455# 456# A '#' or ';' character indicates a comment. 457# 458 459; core variables 460[core] 461 ; Don't trust file modes 462 filemode = false 463 464; user identity 465[user] 466 name = "Junio C Hamano" 467 email = "junkio@twinsun.com" 468 469------------ 470 471Various commands read from the configuration file and adjust 472their operation accordingly. 473 474 475Identifier Terminology 476---------------------- 477<object>:: 478 Indicates the object name for any type of object. 479 480<blob>:: 481 Indicates a blob object name. 482 483<tree>:: 484 Indicates a tree object name. 485 486<commit>:: 487 Indicates a commit object name. 488 489<tree-ish>:: 490 Indicates a tree, commit or tag object name. A 491 command that takes a <tree-ish> argument ultimately wants to 492 operate on a <tree> object but automatically dereferences 493 <commit> and <tag> objects that point at a <tree>. 494 495<type>:: 496 Indicates that an object type is required. 497 Currently one of: `blob`, `tree`, `commit`, or `tag`. 498 499<file>:: 500 Indicates a filename - almost always relative to the 501 root of the tree structure `GIT_INDEX_FILE` describes. 502 503Symbolic Identifiers 504-------------------- 505Any git command accepting any <object> can also use the following 506symbolic notation: 507 508HEAD:: 509 indicates the head of the current branch (i.e. the 510 contents of `$GIT_DIR/HEAD`). 511 512<tag>:: 513 a valid tag 'name' 514 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). 515 516<head>:: 517 a valid head 'name' 518 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). 519 520<snap>:: 521 a valid snapshot 'name' 522 (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`). 523 524 525File/Directory Structure 526------------------------ 527 528Please see link:repository-layout.html[repository layout] document. 529 530Higher level SCMs may provide and manage additional information in the 531`$GIT_DIR`. 532 533 534Terminology 535----------- 536Please see link:glossary.html[glossary] document. 537 538 539Environment Variables 540--------------------- 541Various git commands use the following environment variables: 542 543The git Repository 544~~~~~~~~~~~~~~~~~~ 545These environment variables apply to 'all' core git commands. Nb: it 546is worth noting that they may be used/overridden by SCMS sitting above 547git so take care if using Cogito etc. 548 549'GIT_INDEX_FILE':: 550 This environment allows the specification of an alternate 551 index file. If not specified, the default of `$GIT_DIR/index` 552 is used. 553 554'GIT_OBJECT_DIRECTORY':: 555 If the object storage directory is specified via this 556 environment variable then the sha1 directories are created 557 underneath - otherwise the default `$GIT_DIR/objects` 558 directory is used. 559 560'GIT_ALTERNATE_OBJECT_DIRECTORIES':: 561 Due to the immutable nature of git objects, old objects can be 562 archived into shared, read-only directories. This variable 563 specifies a ":" separated list of git object directories which 564 can be used to search for git objects. New objects will not be 565 written to these directories. 566 567'GIT_DIR':: 568 If the 'GIT_DIR' environment variable is set then it 569 specifies a path to use instead of the default `.git` 570 for the base of the repository. 571 572git Commits 573~~~~~~~~~~~ 574'GIT_AUTHOR_NAME':: 575'GIT_AUTHOR_EMAIL':: 576'GIT_AUTHOR_DATE':: 577'GIT_COMMITTER_NAME':: 578'GIT_COMMITTER_EMAIL':: 579 see gitlink:git-commit-tree[1] 580 581git Diffs 582~~~~~~~~~ 583'GIT_DIFF_OPTS':: 584'GIT_EXTERNAL_DIFF':: 585 see the "generating patches" section in : 586 gitlink:git-diff-index[1]; 587 gitlink:git-diff-files[1]; 588 gitlink:git-diff-tree[1] 589 590Discussion[[Discussion]] 591------------------------ 592include::README[] 593 594Authors 595------- 596* git's founding father is Linus Torvalds <torvalds@osdl.org>. 597* The current git nurse is Junio C Hamano <junkio@cox.net>. 598* The git potty was written by Andres Ericsson <ae@op5.se>. 599* General upbringing is handled by the git-list <git@vger.kernel.org>. 600 601Documentation 602-------------- 603The documentation for git suite was started by David Greaves 604<david@dgreaves.com>, and later enhanced greatly by the 605contributors on the git-list <git@vger.kernel.org>. 606 607GIT 608--- 609Part of the gitlink:git[7] suite 610