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