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-describe[1]:: 143 Show the most recent tag that is reachable from a commit. 144 145gitlink:git-diff-index[1]:: 146 Compares content and mode of blobs between the index and repository. 147 148gitlink:git-diff-files[1]:: 149 Compares files in the working tree and the index. 150 151gitlink:git-diff-stages[1]:: 152 Compares two "merge stages" in the index. 153 154gitlink:git-diff-tree[1]:: 155 Compares the content and mode of blobs found via two tree objects. 156 157gitlink:git-fsck-objects[1]:: 158 Verifies the connectivity and validity of the objects in the database. 159 160gitlink:git-ls-files[1]:: 161 Information about files in the index and the working tree. 162 163gitlink:git-ls-tree[1]:: 164 Displays a tree object in human readable form. 165 166gitlink:git-merge-base[1]:: 167 Finds as good common ancestors as possible for a merge. 168 169gitlink:git-name-rev[1]:: 170 Find symbolic names for given revs. 171 172gitlink:git-pack-redundant[1]:: 173 Find redundant pack files. 174 175gitlink:git-rev-list[1]:: 176 Lists commit objects in reverse chronological order. 177 178gitlink:git-show-index[1]:: 179 Displays contents of a pack idx file. 180 181gitlink:git-tar-tree[1]:: 182 Creates a tar archive of the files in the named tree object. 183 184gitlink:git-unpack-file[1]:: 185 Creates a temporary file with a blob's contents. 186 187gitlink:git-var[1]:: 188 Displays a git logical variable. 189 190gitlink:git-verify-pack[1]:: 191 Validates packed git archive files. 192 193In general, the interrogate commands do not touch the files in 194the working tree. 195 196 197Synching repositories 198~~~~~~~~~~~~~~~~~~~~~ 199 200gitlink:git-clone-pack[1]:: 201 Clones a repository into the current repository (engine 202 for ssh and local transport). 203 204gitlink:git-fetch-pack[1]:: 205 Updates from a remote repository (engine for ssh and 206 local transport). 207 208gitlink:git-http-fetch[1]:: 209 Downloads a remote git repository via HTTP by walking 210 commit chain. 211 212gitlink:git-local-fetch[1]:: 213 Duplicates another git repository on a local system by 214 walking commit chain. 215 216gitlink:git-peek-remote[1]:: 217 Lists references on a remote repository using 218 upload-pack protocol (engine for ssh and local 219 transport). 220 221gitlink:git-receive-pack[1]:: 222 Invoked by 'git-send-pack' to receive what is pushed to it. 223 224gitlink:git-send-pack[1]:: 225 Pushes to a remote repository, intelligently. 226 227gitlink:git-http-push[1]:: 228 Push missing objects using HTTP/DAV. 229 230gitlink:git-shell[1]:: 231 Restricted shell for GIT-only SSH access. 232 233gitlink:git-ssh-fetch[1]:: 234 Pulls from a remote repository over ssh connection by 235 walking commit chain. 236 237gitlink:git-ssh-upload[1]:: 238 Helper "server-side" program used by git-ssh-fetch. 239 240gitlink:git-update-server-info[1]:: 241 Updates auxiliary information on a dumb server to help 242 clients discover references and packs on it. 243 244gitlink:git-upload-pack[1]:: 245 Invoked by 'git-clone-pack' and 'git-fetch-pack' to push 246 what are asked for. 247 248 249Porcelain-ish Commands 250---------------------- 251 252gitlink:git-add[1]:: 253 Add paths to the index. 254 255gitlink:git-am[1]:: 256 Apply patches from a mailbox, but cooler. 257 258gitlink:git-applymbox[1]:: 259 Apply patches from a mailbox, original version by Linus. 260 261gitlink:git-bisect[1]:: 262 Find the change that introduced a bug by binary search. 263 264gitlink:git-branch[1]:: 265 Create and Show branches. 266 267gitlink:git-checkout[1]:: 268 Checkout and switch to a branch. 269 270gitlink:git-cherry-pick[1]:: 271 Cherry-pick the effect of an existing commit. 272 273gitlink:git-clone[1]:: 274 Clones a repository into a new directory. 275 276gitlink:git-commit[1]:: 277 Record changes to the repository. 278 279gitlink:git-diff[1]:: 280 Show changes between commits, commit and working tree, etc. 281 282gitlink:git-fetch[1]:: 283 Download from a remote repository via various protocols. 284 285gitlink:git-format-patch[1]:: 286 Prepare patches for e-mail submission. 287 288gitlink:git-grep[1]:: 289 Print lines matching a pattern. 290 291gitlink:git-log[1]:: 292 Shows commit logs. 293 294gitlink:git-ls-remote[1]:: 295 Shows references in a remote or local repository. 296 297gitlink:git-merge[1]:: 298 Grand unified merge driver. 299 300gitlink:git-mv[1]:: 301 Move or rename a file, a directory, or a symlink. 302 303gitlink:git-pull[1]:: 304 Fetch from and merge with a remote repository. 305 306gitlink:git-push[1]:: 307 Update remote refs along with associated objects. 308 309gitlink:git-rebase[1]:: 310 Rebase local commits to the updated upstream head. 311 312gitlink:git-repack[1]:: 313 Pack unpacked objects in a repository. 314 315gitlink:git-reset[1]:: 316 Reset current HEAD to the specified state. 317 318gitlink:git-resolve[1]:: 319 Merge two commits. 320 321gitlink:git-revert[1]:: 322 Revert an existing commit. 323 324gitlink:git-shortlog[1]:: 325 Summarizes 'git log' output. 326 327gitlink:git-show-branch[1]:: 328 Show branches and their commits. 329 330gitlink:git-status[1]:: 331 Shows the working tree status. 332 333gitlink:git-verify-tag[1]:: 334 Check the GPG signature of tag. 335 336gitlink:git-whatchanged[1]:: 337 Shows commit logs and differences they introduce. 338 339 340Ancillary Commands 341------------------ 342Manipulators: 343 344gitlink:git-applypatch[1]:: 345 Apply one patch extracted from an e-mail. 346 347gitlink:git-archimport[1]:: 348 Import an arch repository into git. 349 350gitlink:git-convert-objects[1]:: 351 Converts old-style git repository. 352 353gitlink:git-cvsimport[1]:: 354 Salvage your data out of another SCM people love to hate. 355 356gitlink:git-cvsexportcommit[1]:: 357 Export a single commit to a CVS checkout. 358 359gitlink:git-lost-found[1]:: 360 Recover lost refs that luckily have not yet been pruned. 361 362gitlink:git-merge-one-file[1]:: 363 The standard helper program to use with `git-merge-index`. 364 365gitlink:git-prune[1]:: 366 Prunes all unreachable objects from the object database. 367 368gitlink:git-relink[1]:: 369 Hardlink common objects in local repositories. 370 371gitlink:git-svnimport[1]:: 372 Import a SVN repository into git. 373 374gitlink:git-sh-setup[1]:: 375 Common git shell script setup code. 376 377gitlink:git-symbolic-ref[1]:: 378 Read and modify symbolic refs. 379 380gitlink:git-tag[1]:: 381 An example script to create a tag object signed with GPG. 382 383gitlink:git-update-ref[1]:: 384 Update the object name stored in a ref safely. 385 386 387Interrogators: 388 389gitlink:git-check-ref-format[1]:: 390 Make sure ref name is well formed. 391 392gitlink:git-cherry[1]:: 393 Find commits not merged upstream. 394 395gitlink:git-count-objects[1]:: 396 Count unpacked number of objects and their disk consumption. 397 398gitlink:git-daemon[1]:: 399 A really simple server for git repositories. 400 401gitlink:git-get-tar-commit-id[1]:: 402 Extract commit ID from an archive created using git-tar-tree. 403 404gitlink:git-mailinfo[1]:: 405 Extracts patch and authorship information from a single 406 e-mail message, optionally transliterating the commit 407 message into utf-8. 408 409gitlink:git-mailsplit[1]:: 410 A stupid program to split UNIX mbox format mailbox into 411 individual pieces of e-mail. 412 413gitlink:git-patch-id[1]:: 414 Compute unique ID for a patch. 415 416gitlink:git-parse-remote[1]:: 417 Routines to help parsing `$GIT_DIR/remotes/` files. 418 419gitlink:git-request-pull[1]:: 420 git-request-pull. 421 422gitlink:git-rev-parse[1]:: 423 Pick out and massage parameters. 424 425gitlink:git-send-email[1]:: 426 Send patch e-mails out of "format-patch --mbox" output. 427 428gitlink:git-symbolic-ref[1]:: 429 Read and modify symbolic refs. 430 431gitlink:git-stripspace[1]:: 432 Filter out empty lines. 433 434 435Commands not yet documented 436--------------------------- 437 438gitlink:gitk[1]:: 439 The gitk repository browser. 440 441 442Configuration Mechanism 443----------------------- 444 445Starting from 0.99.9 (actually mid 0.99.8.GIT), `.git/config` file 446is used to hold per-repository configuration options. It is a 447simple text file modelled after `.ini` format familiar to some 448people. Here is an example: 449 450------------ 451# 452# A '#' or ';' character indicates a comment. 453# 454 455; core variables 456[core] 457 ; Don't trust file modes 458 filemode = false 459 460; user identity 461[user] 462 name = "Junio C Hamano" 463 email = "junkio@twinsun.com" 464 465------------ 466 467Various commands read from the configuration file and adjust 468their operation accordingly. 469 470 471Identifier Terminology 472---------------------- 473<object>:: 474 Indicates the object name for any type of object. 475 476<blob>:: 477 Indicates a blob object name. 478 479<tree>:: 480 Indicates a tree object name. 481 482<commit>:: 483 Indicates a commit object name. 484 485<tree-ish>:: 486 Indicates a tree, commit or tag object name. A 487 command that takes a <tree-ish> argument ultimately wants to 488 operate on a <tree> object but automatically dereferences 489 <commit> and <tag> objects that point at a <tree>. 490 491<type>:: 492 Indicates that an object type is required. 493 Currently one of: `blob`, `tree`, `commit`, or `tag`. 494 495<file>:: 496 Indicates a filename - almost always relative to the 497 root of the tree structure `GIT_INDEX_FILE` describes. 498 499Symbolic Identifiers 500-------------------- 501Any git command accepting any <object> can also use the following 502symbolic notation: 503 504HEAD:: 505 indicates the head of the current branch (i.e. the 506 contents of `$GIT_DIR/HEAD`). 507 508<tag>:: 509 a valid tag 'name' 510 (i.e. the contents of `$GIT_DIR/refs/tags/<tag>`). 511 512<head>:: 513 a valid head 'name' 514 (i.e. the contents of `$GIT_DIR/refs/heads/<head>`). 515 516<snap>:: 517 a valid snapshot 'name' 518 (i.e. the contents of `$GIT_DIR/refs/snap/<snap>`). 519 520 521File/Directory Structure 522------------------------ 523 524Please see link:repository-layout.html[repository layout] document. 525 526Higher level SCMs may provide and manage additional information in the 527`$GIT_DIR`. 528 529 530Terminology 531----------- 532Please see link:glossary.html[glossary] document. 533 534 535Environment Variables 536--------------------- 537Various git commands use the following environment variables: 538 539The git Repository 540~~~~~~~~~~~~~~~~~~ 541These environment variables apply to 'all' core git commands. Nb: it 542is worth noting that they may be used/overridden by SCMS sitting above 543git so take care if using Cogito etc. 544 545'GIT_INDEX_FILE':: 546 This environment allows the specification of an alternate 547 index file. If not specified, the default of `$GIT_DIR/index` 548 is used. 549 550'GIT_OBJECT_DIRECTORY':: 551 If the object storage directory is specified via this 552 environment variable then the sha1 directories are created 553 underneath - otherwise the default `$GIT_DIR/objects` 554 directory is used. 555 556'GIT_ALTERNATE_OBJECT_DIRECTORIES':: 557 Due to the immutable nature of git objects, old objects can be 558 archived into shared, read-only directories. This variable 559 specifies a ":" separated list of git object directories which 560 can be used to search for git objects. New objects will not be 561 written to these directories. 562 563'GIT_DIR':: 564 If the 'GIT_DIR' environment variable is set then it 565 specifies a path to use instead of the default `.git` 566 for the base of the repository. 567 568git Commits 569~~~~~~~~~~~ 570'GIT_AUTHOR_NAME':: 571'GIT_AUTHOR_EMAIL':: 572'GIT_AUTHOR_DATE':: 573'GIT_COMMITTER_NAME':: 574'GIT_COMMITTER_EMAIL':: 575 see gitlink:git-commit-tree[1] 576 577git Diffs 578~~~~~~~~~ 579'GIT_DIFF_OPTS':: 580'GIT_EXTERNAL_DIFF':: 581 see the "generating patches" section in : 582 gitlink:git-diff-index[1]; 583 gitlink:git-diff-files[1]; 584 gitlink:git-diff-tree[1] 585 586Discussion[[Discussion]] 587------------------------ 588include::../README[] 589 590Authors 591------- 592* git's founding father is Linus Torvalds <torvalds@osdl.org>. 593* The current git nurse is Junio C Hamano <junkio@cox.net>. 594* The git potty was written by Andres Ericsson <ae@op5.se>. 595* General upbringing is handled by the git-list <git@vger.kernel.org>. 596 597Documentation 598-------------- 599The documentation for git suite was started by David Greaves 600<david@dgreaves.com>, and later enhanced greatly by the 601contributors on the git-list <git@vger.kernel.org>. 602 603GIT 604--- 605Part of the gitlink:git[7] suite 606