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