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