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