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