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