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