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-branch[1]:: 333 Show branches and their commits. 334 335gitlink:git-status[1]:: 336 Shows the working tree status. 337 338gitlink:git-verify-tag[1]:: 339 Check the GPG signature of tag. 340 341gitlink:git-whatchanged[1]:: 342 Shows commit logs and differences they introduce. 343 344 345Ancillary Commands 346------------------ 347Manipulators: 348 349gitlink:git-applypatch[1]:: 350 Apply one patch extracted from an e-mail. 351 352gitlink:git-archimport[1]:: 353 Import an arch repository into git. 354 355gitlink:git-convert-objects[1]:: 356 Converts old-style git repository. 357 358gitlink:git-cvsimport[1]:: 359 Salvage your data out of another SCM people love to hate. 360 361gitlink:git-cvsexportcommit[1]:: 362 Export a single commit to a CVS checkout. 363 364gitlink:git-lost-found[1]:: 365 Recover lost refs that luckily have not yet been pruned. 366 367gitlink:git-merge-one-file[1]:: 368 The standard helper program to use with `git-merge-index`. 369 370gitlink:git-prune[1]:: 371 Prunes all unreachable objects from the object database. 372 373gitlink:git-relink[1]:: 374 Hardlink common objects in local repositories. 375 376gitlink:git-svnimport[1]:: 377 Import a SVN repository into git. 378 379gitlink:git-sh-setup[1]:: 380 Common git shell script setup code. 381 382gitlink:git-symbolic-ref[1]:: 383 Read and modify symbolic refs. 384 385gitlink:git-tag[1]:: 386 An example script to create a tag object signed with GPG. 387 388gitlink:git-update-ref[1]:: 389 Update the object name stored in a ref safely. 390 391 392Interrogators: 393 394gitlink:git-check-ref-format[1]:: 395 Make sure ref name is well formed. 396 397gitlink:git-cherry[1]:: 398 Find commits not merged upstream. 399 400gitlink:git-count-objects[1]:: 401 Count unpacked number of objects and their disk consumption. 402 403gitlink:git-daemon[1]:: 404 A really simple server for git repositories. 405 406gitlink:git-get-tar-commit-id[1]:: 407 Extract commit ID from an archive created using git-tar-tree. 408 409gitlink:git-mailinfo[1]:: 410 Extracts patch and authorship information from a single 411 e-mail message, optionally transliterating the commit 412 message into utf-8. 413 414gitlink:git-mailsplit[1]:: 415 A stupid program to split UNIX mbox format mailbox into 416 individual pieces of e-mail. 417 418gitlink:git-patch-id[1]:: 419 Compute unique ID for a patch. 420 421gitlink:git-parse-remote[1]:: 422 Routines to help parsing `$GIT_DIR/remotes/` files. 423 424gitlink:git-request-pull[1]:: 425 git-request-pull. 426 427gitlink:git-rev-parse[1]:: 428 Pick out and massage parameters. 429 430gitlink:git-send-email[1]:: 431 Send patch e-mails out of "format-patch --mbox" output. 432 433gitlink:git-symbolic-ref[1]:: 434 Read and modify symbolic refs. 435 436gitlink:git-stripspace[1]:: 437 Filter out empty lines. 438 439 440Commands not yet documented 441--------------------------- 442 443gitlink:gitk[1]:: 444 The gitk repository browser. 445 446 447Configuration Mechanism 448----------------------- 449 450Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file 451is used to hold per-repository configuration options. It is a 452simple text file modelled after `.ini` format familiar to some 453people. Here is an example: 454 455------------ 456# 457# A '#' or ';' character indicates a comment. 458# 459 460; core variables 461[core] 462 ; Don't trust file modes 463 filemode = false 464 465; user identity 466[user] 467 name = "Junio C Hamano" 468 email = "junkio@twinsun.com" 469 470------------ 471 472Various commands read from the configuration file and adjust 473their operation accordingly. 474 475 476Identifier Terminology 477---------------------- 478<object>:: 479 Indicates the object name for any type of object. 480 481<blob>:: 482 Indicates a blob object name. 483 484<tree>:: 485 Indicates a tree object name. 486 487<commit>:: 488 Indicates a commit object name. 489 490<tree-ish>:: 491 Indicates a tree, commit or tag object name. A 492 command that takes a <tree-ish> argument ultimately wants to 493 operate on a <tree> object but automatically dereferences 494 <commit> and <tag> objects that point at a <tree>. 495 496<type>:: 497 Indicates that an object type is required. 498 Currently one of: `blob`, `tree`, `commit`, or `tag`. 499 500<file>:: 501 Indicates a filename - almost always relative to the 502 root of the tree structure `GIT_INDEX_FILE` describes. 503 504Symbolic Identifiers 505-------------------- 506Any git command accepting any <object> can also use the following 507symbolic notation: 508 509HEAD:: 510 indicates the head of the current branch (i.e. the 511 contents of `$GIT_DIR/HEAD`). 512 513<tag>:: 514 a valid tag 'name' 515 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). 516 517<head>:: 518 a valid head 'name' 519 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). 520 521<snap>:: 522 a valid snapshot 'name' 523 (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`). 524 525 526File/Directory Structure 527------------------------ 528 529Please see link:repository-layout.html[repository layout] document. 530 531Higher level SCMs may provide and manage additional information in the 532`$GIT_DIR`. 533 534 535Terminology 536----------- 537Please see link:glossary.html[glossary] document. 538 539 540Environment Variables 541--------------------- 542Various git commands use the following environment variables: 543 544The git Repository 545~~~~~~~~~~~~~~~~~~ 546These environment variables apply to 'all' core git commands. Nb: it 547is worth noting that they may be used/overridden by SCMS sitting above 548git so take care if using Cogito etc. 549 550'GIT_INDEX_FILE':: 551 This environment allows the specification of an alternate 552 index file. If not specified, the default of `$GIT_DIR/index` 553 is used. 554 555'GIT_OBJECT_DIRECTORY':: 556 If the object storage directory is specified via this 557 environment variable then the sha1 directories are created 558 underneath - otherwise the default `$GIT_DIR/objects` 559 directory is used. 560 561'GIT_ALTERNATE_OBJECT_DIRECTORIES':: 562 Due to the immutable nature of git objects, old objects can be 563 archived into shared, read-only directories. This variable 564 specifies a ":" separated list of git object directories which 565 can be used to search for git objects. New objects will not be 566 written to these directories. 567 568'GIT_DIR':: 569 If the 'GIT_DIR' environment variable is set then it 570 specifies a path to use instead of the default `.git` 571 for the base of the repository. 572 573git Commits 574~~~~~~~~~~~ 575'GIT_AUTHOR_NAME':: 576'GIT_AUTHOR_EMAIL':: 577'GIT_AUTHOR_DATE':: 578'GIT_COMMITTER_NAME':: 579'GIT_COMMITTER_EMAIL':: 580 see gitlink:git-commit-tree[1] 581 582git Diffs 583~~~~~~~~~ 584'GIT_DIFF_OPTS':: 585'GIT_EXTERNAL_DIFF':: 586 see the "generating patches" section in : 587 gitlink:git-diff-index[1]; 588 gitlink:git-diff-files[1]; 589 gitlink:git-diff-tree[1] 590 591Discussion[[Discussion]] 592------------------------ 593include::README[] 594 595Authors 596------- 597* git's founding father is Linus Torvalds <torvalds@osdl.org>. 598* The current git nurse is Junio C Hamano <junkio@cox.net>. 599* The git potty was written by Andres Ericsson <ae@op5.se>. 600* General upbringing is handled by the git-list <git@vger.kernel.org>. 601 602Documentation 603-------------- 604The documentation for git suite was started by David Greaves 605<david@dgreaves.com>, and later enhanced greatly by the 606contributors on the git-list <git@vger.kernel.org>. 607 608GIT 609--- 610Part of the gitlink:git[7] suite 611