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