1GIT(1) 2====== 3v0.1, May 2005 4 5//////////////////////// 6Please note that this document is in asciidoc format. 7 http://www.methods.co.nz/asciidoc/index.html 8 9You should be able to read it but be aware that there is some minor 10typographical bludgeoning to allow the production of clean man and 11html output. 12 13(eg in some synopsis lines the '*' character is preceded by a '\' and 14there are one or two '+' characters) 15 16//////////////////////// 17 18NAME 19---- 20git - the stupid content tracker 21 22SYNOPSIS 23-------- 24'git-<command>' <args> 25 26DESCRIPTION 27----------- 28 29This is reference information for the core git commands. 30 31The link:README[] contains much useful definition and clarification 32info - read that first. And of the commands, I suggest reading 33'git-update-cache' and 'git-read-tree' first - I wish I had! 34 35David Greaves <david@dgreaves.com> 3608/05/05 37 38Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to 39reflect recent changes. 40 41Commands Overview 42----------------- 43The git commands can helpfully be split into those that manipulate 44the repository, the cache and the working fileset and those that 45interrogate and compare them. 46 47Manipulation commands 48~~~~~~~~~~~~~~~~~~~~~ 49link:git-apply-patch-script.html[git-apply-patch-script]:: 50 Sample script to apply the diffs from git-diff-* 51 52link:git-checkout-cache.html[git-checkout-cache]:: 53 Copy files from the cache to the working directory 54 55link:git-commit-tree.html[git-commit-tree]:: 56 Creates a new commit object 57 58link:git-convert-cache.html[git-convert-cache]:: 59 Converts old-style GIT repository 60 61link:git-http-pull.html[git-http-pull]:: 62 Downloads a remote GIT repository via HTTP 63 64link:git-init-db.html[git-init-db]:: 65 Creates an empty git object database 66 67link:git-local-pull.html[git-local-pull]:: 68 Duplicates another GIT repository on a local system 69 70link:git-merge-base.html[git-merge-base]:: 71 Finds as good a common ancestor as possible for a merge 72 73link:git-merge-one-file-script.html[git-merge-one-file-script]:: 74 The standard helper program to use with "git-merge-cache" 75 76link:git-mktag.html[git-mktag]:: 77 Creates a tag object 78 79link:git-prune-script.html[git-prune-script]:: 80 Prunes all unreachable objects from the object database 81 82link:git-pull-script.html[git-pull-script]:: 83 Script used by Linus to pull and merge a remote repository 84 85link:git-read-tree.html[git-read-tree]:: 86 Reads tree information into the directory cache 87 88link:git-resolve-script.html[git-resolve-script]:: 89 Script used to merge two trees 90 91link:git-rpull.html[git-rpull]:: 92 Pulls from a remote repository over ssh connection 93 94link:git-tag-script.html[git-tag-script]:: 95 An example script to create a tag object signed with GPG 96 97link:git-update-cache.html[git-update-cache]:: 98 Modifies the index or directory cache 99 100link:git-write-blob.html[git-write-blob]:: 101 Creates a blob from a file 102 103link:git-write-tree.html[git-write-tree]:: 104 Creates a tree from the current cache 105 106Interrogation commands 107~~~~~~~~~~~~~~~~~~~~~~ 108link:git-cat-file.html[git-cat-file]:: 109 Provide content or type information for repository objects 110 111link:git-check-files.html[git-check-files]:: 112 Verify a list of files are up-to-date 113 114link:git-diff-cache.html[git-diff-cache]:: 115 Compares content and mode of blobs between the cache and repository 116 117link:git-diff-files.html[git-diff-files]:: 118 Compares files in the working tree and the cache 119 120link:git-diff-tree.html[git-diff-tree]:: 121 Compares the content and mode of blobs found via two tree objects 122 123link:git-diff-tree-helper.html[git-diff-tree-helper]:: 124 Generates patch format output for git-diff-* 125 126link:git-export.html[git-export]:: 127 Exports each commit and a diff against each of its parents 128 129link:git-fsck-cache.html[git-fsck-cache]:: 130 Verifies the connectivity and validity of the objects in the database 131 132link:git-ls-files.html[git-ls-files]:: 133 Information about files in the cache/working directory 134 135link:git-ls-tree.html[git-ls-tree]:: 136 Displays a tree object in human readable form 137 138link:git-merge-cache.html[git-merge-cache]:: 139 Runs a merge for files needing merging 140 141link:git-rev-list.html[git-rev-list]:: 142 Lists commit objects in reverse chronological order 143 144link:git-rev-tree.html[git-rev-tree]:: 145 Provides the revision tree for one or more commits 146 147link:git-rpush.html[git-rpush]:: 148 Helper "server-side" program used by git-rpull 149 150link:git-tar-tree.html[git-tar-tree]:: 151 Creates a tar archive of the files in the named tree 152 153link:git-unpack-file.html[git-unpack-file]:: 154 Creates a temporary file with a blob's contents 155 156The interrogate commands may create files - and you can force them to 157touch the working file set - but in general they don't 158 159 160Terminology 161----------- 162see README for description 163 164Identifier terminology 165---------------------- 166<object>:: 167 Indicates any object sha1 identifier 168 169<blob>:: 170 Indicates a blob object sha1 identifier 171 172<tree>:: 173 Indicates a tree object sha1 identifier 174 175<commit>:: 176 Indicates a commit object sha1 identifier 177 178<tree-ish>:: 179 Indicates a tree, commit or tag object sha1 identifier. 180 A command that takes a <tree-ish> argument ultimately 181 wants to operate on a <tree> object but automatically 182 dereferences <commit> and <tag> that points at a 183 <tree>. 184 185<type>:: 186 Indicates that an object type is required. 187 Currently one of: blob/tree/commit/tag 188 189<file>:: 190 Indicates a filename - always relative to the root of 191 the tree structure GIT_INDEX_FILE describes. 192 193Terminology 194----------- 195Each line contains terms used interchangeably 196 197 object database, .git directory 198 directory cache, index 199 id, sha1, sha1-id, sha1 hash 200 type, tag 201 blob, blob object 202 tree, tree object 203 commit, commit object 204 parent 205 root object 206 changeset 207 208 209Environment Variables 210--------------------- 211Various git commands use the following environment variables: 212 213- 'GIT_AUTHOR_NAME' 214- 'GIT_AUTHOR_EMAIL' 215- 'GIT_AUTHOR_DATE' 216- 'GIT_COMMITTER_NAME' 217- 'GIT_COMMITTER_EMAIL' 218- 'GIT_DIFF_OPTS' 219- 'GIT_EXTERNAL_DIFF' 220- 'GIT_INDEX_FILE' 221- 'GIT_OBJECT_DIRECTORY' 222- 'GIT_ALTERNATE_OBJECT_DIRECTORIES' 223 224 225NAME 226---- 227git-apply-patch-script - Sample script to apply the diffs from git-diff-* 228 229SYNOPSIS 230-------- 231'git-apply-patch-script' 232 233DESCRIPTION 234----------- 235This is a sample script to be used via the 'GIT_EXTERNAL_DIFF' 236environment variable to apply the differences that the "git-diff-*" 237family of commands report to the current work tree. 238 239 240NAME 241---- 242git-cat-file - Provide content or type information for repository objects 243 244SYNOPSIS 245-------- 246'git-cat-file' (-t | <type>) <object> 247 248DESCRIPTION 249----------- 250Provides content or type of objects in the repository. The type 251is required if '-t' is not being used to find the object type. 252 253OPTIONS 254------- 255<object>:: 256 The sha1 identifier of the object. 257 258-t:: 259 Instead of the content, show the object type identified by 260 <object>. 261 262<type>:: 263 Typically this matches the real type of <object> but asking 264 for a type that can trivially dereferenced from the given 265 <object> is also permitted. An example is to ask for a 266 "tree" with <object> being a commit object that contains it, 267 or to ask for a "blob" with <object> being a tag object that 268 points at it. 269 270OUTPUT 271------ 272If '-t' is specified, one of the <type>. 273 274Otherwise the raw (though uncompressed) contents of the <object> will 275be returned. 276 277 278NAME 279---- 280git-check-files - Verify a list of files are up-to-date 281 282 283SYNOPSIS 284-------- 285'git-check-files' <file>... 286 287DESCRIPTION 288----------- 289Check that a list of files are up-to-date between the filesystem and 290the cache. Used to verify a patch target before doing a patch. 291 292Files that do not exist on the filesystem are considered up-to-date 293(whether or not they are in the cache). 294 295Emits an error message on failure: 296 297preparing to update existing file <file> not in cache:: 298 <file> exists but is not in the cache 299 300preparing to update file <file> not uptodate in cache:: 301 <file> on disk is not up-to-date with the cache 302 303Exits with a status code indicating success if all files are 304up-to-date. 305 306see also: link:git-update-cache.html[git-update-cache] 307 308 309NAME 310---- 311git-checkout-cache - Copy files from the cache to the working directory 312 313SYNOPSIS 314-------- 315'git-checkout-cache' [-q] [-a] [-f] [-n] [--prefix=<string>] 316 [--] <file>... 317 318DESCRIPTION 319----------- 320Will copy all files listed from the cache to the working directory 321(not overwriting existing files). 322 323OPTIONS 324------- 325-q:: 326 be quiet if files exist or are not in the cache 327 328-f:: 329 forces overwrite of existing files 330 331-a:: 332 checks out all files in the cache (will then continue to 333 process listed files). 334 335-n:: 336 Don't checkout new files, only refresh files already checked 337 out. 338 339--prefix=<string>:: 340 When creating files, prepend <string> (usually a directory 341 including a trailing /) 342 343--:: 344 Do not interpret any more arguments as options. 345 346Note that the order of the flags matters: 347 348 git-checkout-cache -a -f file.c 349 350will first check out all files listed in the cache (but not overwrite 351any old ones), and then force-checkout `file.c` a second time (ie that 352one *will* overwrite any old contents with the same filename). 353 354Also, just doing "git-checkout-cache" does nothing. You probably meant 355"git-checkout-cache -a". And if you want to force it, you want 356"git-checkout-cache -f -a". 357 358Intuitiveness is not the goal here. Repeatability is. The reason for 359the "no arguments means no work" thing is that from scripts you are 360supposed to be able to do things like: 361 362 find . -name '*.h' -print0 | xargs -0 git-checkout-cache -f -- 363 364which will force all existing `*.h` files to be replaced with their 365cached copies. If an empty command line implied "all", then this would 366force-refresh everything in the cache, which was not the point. 367 368To update and refresh only the files already checked out: 369 370 git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh 371 372Oh, and the "--" is just a good idea when you know the rest will be 373filenames. Just so that you wouldn't have a filename of "-a" causing 374problems (not possible in the above example, but get used to it in 375scripting!). 376 377The prefix ability basically makes it trivial to use 378git-checkout-cache as an "export as tree" function. Just read the 379desired tree into the index, and do a 380 381 git-checkout-cache --prefix=git-export-dir/ -a 382 383and git-checkout-cache will "export" the cache into the specified 384directory. 385 386NOTE The final "/" is important. The exported name is literally just 387prefixed with the specified string, so you can also do something like 388 389 git-checkout-cache --prefix=.merged- Makefile 390 391to check out the currently cached copy of `Makefile` into the file 392`.merged-Makefile` 393 394NAME 395---- 396git-commit-tree - Creates a new commit object 397 398SYNOPSIS 399-------- 400'git-commit-tree' <tree> [-p <parent commit>]\ < changelog 401 402DESCRIPTION 403----------- 404Creates a new commit object based on the provided tree object and 405emits the new commit object id on stdout. If no parent is given then 406it is considered to be an initial tree. 407 408A commit object usually has 1 parent (a commit after a change) or up 409to 16 parents. More than one parent represents a merge of branches 410that led to them. 411 412While a tree represents a particular directory state of a working 413directory, a commit represents that state in "time", and explains how 414to get there. 415 416Normally a commit would identify a new "HEAD" state, and while git 417doesn't care where you save the note about that state, in practice we 418tend to just write the result to the file `.git/HEAD`, so that we can 419always see what the last committed state was. 420 421OPTIONS 422------- 423<tree>:: 424 An existing tree object 425 426-p <parent commit>:: 427 Each '-p' indicates a the id of a parent commit object. 428 429 430Commit Information 431------------------ 432 433A commit encapsulates: 434 435- all parent object ids 436- author name, email and date 437- committer name and email and the commit time. 438 439If not provided, "git-commit-tree" uses your name, hostname and domain to 440provide author and committer info. This can be overridden using the 441following environment variables. 442 443 GIT_AUTHOR_NAME 444 GIT_AUTHOR_EMAIL 445 GIT_AUTHOR_DATE 446 GIT_COMMITTER_NAME 447 GIT_COMMITTER_EMAIL 448 449(nb <,> and '\n's are stripped) 450 451A commit comment is read from stdin (max 999 chars). If a changelog 452entry is not provided via '<' redirection, "git-commit-tree" will just wait 453for one to be entered and terminated with ^D 454 455see also: link:git-write-tree.html[git-write-tree] 456 457 458NAME 459---- 460git-convert-cache - Converts old-style GIT repository 461 462SYNOPSIS 463-------- 464'git-convert-cache' 465 466DESCRIPTION 467----------- 468Converts old-style GIT repository to the latest format 469 470 471NAME 472---- 473git-diff-cache - Compares content and mode of blobs between the cache and repository 474 475SYNOPSIS 476-------- 477'git-diff-cache' [-p] [-r] [-z] [-m] [--cached] <tree-ish> 478 479DESCRIPTION 480----------- 481Compares the content and mode of the blobs found via a tree object 482with the content of the current cache and, optionally ignoring the 483stat state of the file on disk. 484 485OPTIONS 486------- 487<tree-ish>:: 488 The id of a tree object to diff against. 489 490-p:: 491 Generate patch (see section on generating patches) 492 493-r:: 494 This flag does not mean anything. It is there only to match 495 "git-diff-tree". Unlike "git-diff-tree", "git-diff-cache" 496 always looks at all the subdirectories. 497 498-z:: 499 \0 line termination on output 500 501--cached:: 502 do not consider the on-disk file at all 503 504-m:: 505 By default, files recorded in the index but not checked 506 out are reported as deleted. This flag makes 507 "git-diff-cache" say that all non-checked-out files are up 508 to date. 509 510Output format 511------------- 512include::diff-format.txt[] 513 514Operating Modes 515--------------- 516You can choose whether you want to trust the index file entirely 517(using the '--cached' flag) or ask the diff logic to show any files 518that don't match the stat state as being "tentatively changed". Both 519of these operations are very useful indeed. 520 521Cached Mode 522----------- 523If '--cached' is specified, it allows you to ask: 524 525 show me the differences between HEAD and the current index 526 contents (the ones I'd write with a "git-write-tree") 527 528For example, let's say that you have worked on your index file, and are 529ready to commit. You want to see eactly *what* you are going to commit is 530without having to write a new tree object and compare it that way, and to 531do that, you just do 532 533 git-diff-cache --cached $(cat .git/HEAD) 534 535Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had 536done an "git-update-cache" to make that effective in the index file. 537"git-diff-files" wouldn't show anything at all, since the index file 538matches my working directory. But doing a "git-diff-cache" does: 539 540 torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD) 541 -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c 542 +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c 543 544You can trivially see that the above is a rename. 545 546In fact, "git-diff-cache --cached" *should* always be entirely equivalent to 547actually doing a "git-write-tree" and comparing that. Except this one is much 548nicer for the case where you just want to check where you are. 549 550So doing a "git-diff-cache --cached" is basically very useful when you are 551asking yourself "what have I already marked for being committed, and 552what's the difference to a previous tree". 553 554Non-cached Mode 555--------------- 556The "non-cached" mode takes a different approach, and is potentially 557the more useful of the two in that what it does can't be emulated with 558a "git-write-tree" + "git-diff-tree". Thus that's the default mode. 559The non-cached version asks the question: 560 561 show me the differences between HEAD and the currently checked out 562 tree - index contents _and_ files that aren't up-to-date 563 564which is obviously a very useful question too, since that tells you what 565you *could* commit. Again, the output matches the "git-diff-tree -r" 566output to a tee, but with a twist. 567 568The twist is that if some file doesn't match the cache, we don't have 569a backing store thing for it, and we use the magic "all-zero" sha1 to 570show that. So let's say that you have edited `kernel/sched.c`, but 571have not actually done a "git-update-cache" on it yet - there is no 572"object" associated with the new state, and you get: 573 574 torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD ) 575 *100644->100664 blob 7476bb......->000000...... kernel/sched.c 576 577ie it shows that the tree has changed, and that `kernel/sched.c` has is 578not up-to-date and may contain new stuff. The all-zero sha1 means that to 579get the real diff, you need to look at the object in the working directory 580directly rather than do an object-to-object diff. 581 582NOTE! As with other commands of this type, "git-diff-cache" does not 583actually look at the contents of the file at all. So maybe 584`kernel/sched.c` hasn't actually changed, and it's just that you 585touched it. In either case, it's a note that you need to 586"git-upate-cache" it to make the cache be in sync. 587 588NOTE 2! You can have a mixture of files show up as "has been updated" 589and "is still dirty in the working directory" together. You can always 590tell which file is in which state, since the "has been updated" ones 591show a valid sha1, and the "not in sync with the index" ones will 592always have the special all-zero sha1. 593 594 595NAME 596---- 597git-diff-files - Compares files in the working tree and the cache 598 599SYNOPSIS 600-------- 601'git-diff-files' [-p] [-q] [-r] [-z] [<pattern>...] 602 603DESCRIPTION 604----------- 605Compares the files in the working tree and the cache. When paths 606are specified, compares only those named paths. Otherwise all 607entries in the cache are compared. The output format is the 608same as "git-diff-cache" and "git-diff-tree". 609 610OPTIONS 611------- 612-p:: 613 generate patch (see section on generating patches). 614 615-q:: 616 Remain silent even on nonexisting files 617 618-r:: 619 This flag does not mean anything. It is there only to match 620 git-diff-tree. Unlike git-diff-tree, git-diff-files always looks 621 at all the subdirectories. 622 623 624Output format 625------------- 626include::diff-format.txt[] 627 628 629NAME 630---- 631git-diff-tree - Compares the content and mode of blobs found via two tree objects 632 633SYNOPSIS 634-------- 635'git-diff-tree' [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] <tree-ish> <tree-ish> [<pattern>]\* 636 637DESCRIPTION 638----------- 639Compares the content and mode of the blobs found via two tree objects. 640 641Note that "git-diff-tree" can use the tree encapsulated in a commit object. 642 643OPTIONS 644------- 645<tree-ish>:: 646 The id of a tree object. 647 648<pattern>:: 649 If provided, the results are limited to a subset of files 650 matching one of these prefix strings. 651 ie file matches `/^<pattern1>|<pattern2>|.../` 652 Note that pattern does not provide any wildcard or regexp 653 features. 654 655-p:: 656 generate patch (see section on generating patches). For 657 git-diff-tree, this flag implies '-r' as well. 658 659-r:: 660 recurse 661 662-z:: 663 \0 line termination on output 664 665--stdin:: 666 When '--stdin' is specified, the command does not take 667 <tree-ish> arguments from the command line. Instead, it 668 reads either one <commit> or a pair of <tree-ish> 669 separated with a single space from its standard input. 670+ 671When a single commit is given on one line of such input, it compares 672the commit with its parents. The following flags further affects its 673behaviour. This does not apply to the case where two <tree-ish> 674separated with a single space are given. 675 676-m:: 677 By default, "git-diff-tree --stdin" does not show 678 differences for merge commits. With this flag, it shows 679 differences to that commit from all of its parents. 680 681-s:: 682 By default, "git-diff-tree --stdin" shows differences, 683 either in machine-readable form (without '-p') or in patch 684 form (with '-p'). This output can be supressed. It is 685 only useful with '-v' flag. 686 687-v:: 688 This flag causes "git-diff-tree --stdin" to also show 689 the commit message before the differences. 690 691 692Limiting Output 693--------------- 694If you're only interested in differences in a subset of files, for 695example some architecture-specific files, you might do: 696 697 git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64 698 699and it will only show you what changed in those two directories. 700 701Or if you are searching for what changed in just `kernel/sched.c`, just do 702 703 git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c 704 705and it will ignore all differences to other files. 706 707The pattern is always the prefix, and is matched exactly. There are no 708wildcards. Even stricter, it has to match complete path comonent. 709I.e. "foo" does not pick up `foobar.h`. "foo" does match `foo/bar.h` 710so it can be used to name subdirectories. 711 712An example of normal usage is: 713 714 torvalds@ppc970:~/git> git-diff-tree 5319e4...... 715 *100664->100664 blob ac348b.......->a01513....... git-fsck-cache.c 716 717which tells you that the last commit changed just one file (it's from 718this one: 719 720 commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8 721 tree 5319e4d609cdd282069cc4dce33c1db559539b03 722 parent b4e628ea30d5ab3606119d2ea5caeab141d38df7 723 author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005 724 committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005 725 726 Make "git-fsck-cache" print out all the root commits it finds. 727 728 Once I do the reference tracking, I'll also make it print out all the 729 HEAD commits it finds, which is even more interesting. 730 731in case you care). 732 733Output format 734------------- 735include::diff-format.txt[] 736 737 738NAME 739---- 740git-diff-tree-helper - Generates patch format output for git-diff-* 741 742SYNOPSIS 743-------- 744'git-diff-tree-helper' [-z] [-R] 745 746DESCRIPTION 747----------- 748Reads output from "git-diff-cache", "git-diff-tree" and "git-diff-files" and 749generates patch format output. 750 751OPTIONS 752------- 753-z:: 754 \0 line termination on input 755 756-R:: 757 Output diff in reverse. This is useful for displaying output from 758 "git-diff-cache" which always compares tree with cache or working 759 file. E.g. 760 761 git-diff-cache <tree> | git-diff-tree-helper -R file.c 762+ 763would show a diff to bring the working file back to what is in the <tree>. 764 765See also the section on generating patches in link:git-diff-cache.html[git-diff-cache] 766 767 768NAME 769---- 770git-export - Exports each commit and a diff against each of its parents 771 772SYNOPSIS 773-------- 774'git-export' top [base] 775 776DESCRIPTION 777----------- 778Exports each commit and diff against each of its parents, between 779top and base. If base is not specified it exports everything. 780 781 782NAME 783---- 784git-fsck-cache - Verifies the connectivity and validity of the objects in the database 785 786SYNOPSIS 787-------- 788'git-fsck-cache' [--tags] [--root] [[--unreachable] [--cache] <object>\*] 789 790DESCRIPTION 791----------- 792Verifies the connectivity and validity of the objects in the database. 793 794OPTIONS 795------- 796<object>:: 797 An object to treat as the head of an unreachability trace. 798 799--unreachable:: 800 Print out objects that exist but that aren't readable from any 801 of the specified head nodes. 802 803--root:: 804 Report root nodes. 805 806--tags:: 807 Report tags. 808 809--cache:: 810 Consider any object recorded in the cache also as a head node for 811 an unreachability trace. 812 813It tests SHA1 and general object sanity, and it does full tracking of 814the resulting reachability and everything else. It prints out any 815corruption it finds (missing or bad objects), and if you use the 816'--unreachable' flag it will also print out objects that exist but 817that aren't readable from any of the specified head nodes. 818 819So for example 820 821 git-fsck-cache --unreachable $(cat .git/HEAD) 822 823or, for Cogito users: 824 825 git-fsck-cache --unreachable $(cat .git/refs/heads/*) 826 827will do quite a _lot_ of verification on the tree. There are a few 828extra validity tests to be added (make sure that tree objects are 829sorted properly etc), but on the whole if "git-fsck-cache" is happy, you 830do have a valid tree. 831 832Any corrupt objects you will have to find in backups or other archives 833(ie you can just remove them and do an "rsync" with some other site in 834the hopes that somebody else has the object you have corrupted). 835 836Of course, "valid tree" doesn't mean that it wasn't generated by some 837evil person, and the end result might be crap. Git is a revision 838tracking system, not a quality assurance system ;) 839 840Extracted Diagnostics 841--------------------- 842 843expect dangling commits - potential heads - due to lack of head information:: 844 You haven't specified any nodes as heads so it won't be 845 possible to differentiate between un-parented commits and 846 root nodes. 847 848missing sha1 directory '<dir>':: 849 The directory holding the sha1 objects is missing. 850 851unreachable <type> <object>:: 852 The <type> object <object>, isn't actually referred to directly 853 or indirectly in any of the trees or commits seen. This can 854 mean that there's another root node that you're not specifying 855 or that the tree is corrupt. If you haven't missed a root node 856 then you might as well delete unreachable nodes since they 857 can't be used. 858 859missing <type> <object>:: 860 The <type> object <object>, is referred to but isn't present in 861 the database. 862 863dangling <type> <object>:: 864 The <type> object <object>, is present in the database but never 865 'directly' used. A dangling commit could be a root node. 866 867warning: git-fsck-cache: tree <tree> has full pathnames in it:: 868 And it shouldn't... 869 870sha1 mismatch <object>:: 871 The database has an object who's sha1 doesn't match the 872 database value. 873 This indicates a serious data integrity problem. 874 (note: this error occured during early git development when 875 the database format changed.) 876 877Environment Variables 878--------------------- 879 880GIT_OBJECT_DIRECTORY:: 881 used to specify the object database root (usually .git/objects) 882 883GIT_INDEX_FILE:: 884 used to specify the cache 885 886 887NAME 888---- 889git-http-pull - Downloads a remote GIT repository via HTTP 890 891SYNOPSIS 892-------- 893'git-http-pull' [-c] [-t] [-a] [-v] commit-id url 894 895DESCRIPTION 896----------- 897Downloads a remote GIT repository via HTTP. 898 899-c:: 900 Get the commit objects. 901-t:: 902 Get trees associated with the commit objects. 903-a:: 904 Get all the objects. 905-v:: 906 Report what is downloaded. 907 908 909NAME 910---- 911git-init-db - Creates an empty git object database 912 913SYNOPSIS 914-------- 915'git-init-db' 916 917DESCRIPTION 918----------- 919This simply creates an empty git object database - basically a `.git` 920directory and `.git/object/??/` directories. 921 922If the object storage directory is specified via the 'GIT_OBJECT_DIRECTORY' 923environment variable then the sha1 directories are created underneath - 924otherwise the default `.git/objects` directory is used. 925 926"git-init-db" won't hurt an existing repository. 927 928 929NAME 930---- 931git-local-pull - Duplicates another GIT repository on a local system 932 933SYNOPSIS 934-------- 935'git-local-pull' [-c] [-t] [-a] [-l] [-s] [-n] [-v] commit-id path 936 937DESCRIPTION 938----------- 939Duplicates another GIT repository on a local system. 940 941OPTIONS 942------- 943-c:: 944 Get the commit objects. 945-t:: 946 Get trees associated with the commit objects. 947-a:: 948 Get all the objects. 949-v:: 950 Report what is downloaded. 951 952NAME 953---- 954git-ls-files - Information about files in the cache/working directory 955 956SYNOPSIS 957-------- 958'git-ls-files' [-z] [-t] 959 (--[cached|deleted|others|ignored|stage|unmerged])\* 960 (-[c|d|o|i|s|u])\* 961 [-x <pattern>|--exclude=<pattern>] 962 [-X <file>|--exclude-from=<file>] 963 964DESCRIPTION 965----------- 966This merges the file listing in the directory cache index with the 967actual working directory list, and shows different combinations of the 968two. 969 970One or more of the options below may be used to determine the files 971shown: 972 973OPTIONS 974------- 975-c|--cached:: 976 Show cached files in the output (default) 977 978-d|--deleted:: 979 Show deleted files in the output 980 981-o|--others:: 982 Show other files in the output 983 984-i|--ignored:: 985 Show ignored files in the output 986 Note the this also reverses any exclude list present. 987 988-s|--stage:: 989 Show stage files in the output 990 991-u|--unmerged:: 992 Show unmerged files in the output (forces --stage) 993 994-z:: 995 \0 line termination on output 996 997-x|--exclude=<pattern>:: 998 Skips files matching pattern. 999 Note that pattern is a shell wildcard pattern.10001001-X|--exclude-from=<file>::1002 exclude patterns are read from <file>; 1 per line.1003 Allows the use of the famous dontdiff file as follows to find1004 out about uncommitted files just as dontdiff is used with1005 the diff command:1006 git-ls-files --others --exclude-from=dontdiff10071008-t::1009 Identify the file status with the following tags (followed by1010 a space) at the start of each line:1011 H cached1012 M unmerged1013 R removed/deleted1014 ? other10151016Output1017------1018show files just outputs the filename unless '--stage' is specified in1019which case it outputs:10201021 [<tag> ]<mode> <object> <stage> <file>10221023"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine1024detailed information on unmerged paths.10251026For an unmerged path, instead of recording a single mode/SHA1 pair,1027the dircache records up to three such pairs; one from tree O in stage10281, A in stage 2, and B in stage 3. This information can be used by1029the user (or Cogito) to see what should eventually be recorded at the1030path. (see read-cache for more information on state)10311032see also: link:read-cache.html[read-cache]103310341035NAME1036----1037git-ls-tree - Displays a tree object in human readable form10381039SYNOPSIS1040--------1041'git-ls-tree' [-r] [-z] <tree-ish>10421043DESCRIPTION1044-----------1045Converts the tree object to a human readable (and script processable)1046form.10471048OPTIONS1049-------1050<tree-ish>::1051 Id of a tree.10521053-r::1054 recurse into sub-trees10551056-z::1057 \0 line termination on output10581059Output Format1060-------------1061 <mode>\t <type>\t <object>\t <file>106210631064NAME1065----1066git-merge-base - Finds as good a common ancestor as possible for a merge10671068SYNOPSIS1069--------1070'git-merge-base' <commit> <commit>10711072DESCRIPTION1073-----------1074"git-merge-base" finds as good a common ancestor as possible. Given a1075selection of equally good common ancestors it should not be relied on1076to decide in any particular way.10771078The "git-merge-base" algorithm is still in flux - use the source...107910801081NAME1082----1083git-merge-cache - Runs a merge for files needing merging10841085SYNOPSIS1086--------1087'git-merge-cache' <merge-program> (-a | -- | <file>\*) 10881089DESCRIPTION1090-----------1091This looks up the <file>(s) in the cache and, if there are any merge1092entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty1093argument if no file), and <file> as argument 4. File modes for the three1094files are passed as arguments 5, 6 and 7.10951096OPTIONS1097-------1098--::1099 Interpret all future arguments as filenames.11001101-a::1102 Run merge against all files in the cache that need merging.11031104If "git-merge-cache" is called with multiple <file>s (or -a) then it1105processes them in turn only stopping if merge returns a non-zero exit1106code.11071108Typically this is run with the a script calling the merge command from1109the RCS package.11101111A sample script called "git-merge-one-file-script" is included in the1112ditribution.11131114ALERT ALERT ALERT! The git "merge object order" is different from the1115RCS "merge" program merge object order. In the above ordering, the1116original is first. But the argument order to the 3-way merge program1117"merge" is to have the original in the middle. Don't ask me why.11181119Examples:11201121 torvalds@ppc970:~/merge-test> git-merge-cache cat MM1122 This is MM from the original tree. # original1123 This is modified MM in the branch A. # merge11124 This is modified MM in the branch B. # merge21125 This is modified MM in the branch B. # current contents11261127or 11281129 torvalds@ppc970:~/merge-test> git-merge-cache cat AA MM1130 cat: : No such file or directory1131 This is added AA in the branch A.1132 This is added AA in the branch B.1133 This is added AA in the branch B.1134 fatal: merge program failed11351136where the latter example shows how "git-merge-cache" will stop trying to1137merge once anything has returned an error (ie "cat" returned an error1138for the AA file, because it didn't exist in the original, and thus1139"git-merge-cache" didn't even try to merge the MM thing).11401141NAME1142----1143git-merge-one-file-script - The standard helper program to use with "git-merge-cache"11441145SYNOPSIS1146--------1147'git-merge-one-file-script'11481149DESCRIPTION1150-----------1151This is the standard helper program to use with "git-merge-cache"1152to resolve a merge after the trivial merge done with "git-read-tree -m".11531154NAME1155----1156git-mktag - Creates a tag object11571158SYNOPSIS1159--------1160'git-mktag'11611162DESCRIPTION1163-----------1164Reads a tag contents from its standard input and creates a tag object.1165The input must be a well formed tag object.116611671168NAME1169----1170git-prune-script - Prunes all unreachable objects from the object database11711172SYNOPSIS1173--------1174'git-prune-script'11751176DESCRIPTION1177-----------1178This runs "git-fsck-cache --unreachable" program using the heads specified1179on the command line (or `.git/refs/heads/\*` and `.git/refs/tags/\*` if none is1180specified), and prunes all unreachable objects from the object database.118111821183NAME1184----1185git-pull-script - Script used by Linus to pull and merge a remote repository11861187SYNOPSIS1188--------1189'git-pull-script'11901191DESCRIPTION1192-----------1193This script is used by Linus to pull from a remote repository and perform1194a merge.119511961197NAME1198----1199git-read-tree - Reads tree information into the directory cache12001201SYNOPSIS1202--------1203'git-read-tree' (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])"12041205DESCRIPTION1206-----------1207Reads the tree information given by <tree> into the directory cache,1208but does not actually _update_ any of the files it "caches". (see:1209git-checkout-cache)12101211Optionally, it can merge a tree into the cache or perform a 3-way1212merge.12131214Trivial merges are done by "git-read-tree" itself. Only conflicting paths1215will be in unmerged state when "git-read-tree" returns.12161217OPTIONS1218-------1219-m::1220 Perform a merge, not just a read12211222<tree-ish#>::1223 The id of the tree object(s) to be read/merged.122412251226Merging1227-------1228If '-m' is specified, "git-read-tree" performs 2 kinds of merge, a single tree1229merge if only 1 tree is given or a 3-way merge if 3 trees are1230provided.12311232Single Tree Merge1233~~~~~~~~~~~~~~~~~1234If only 1 tree is specified, git-read-tree operates as if the user did not1235specify '-m', except that if the original cache has an entry for a1236given pathname; and the contents of the path matches with the tree1237being read, the stat info from the cache is used. (In other words, the1238cache's stat()s take precedence over the merged tree's)12391240That means that if you do a "git-read-tree -m <newtree>" followed by a1241"git-checkout-cache -f -a", the "git-checkout-cache" only checks out1242the stuff that really changed.12431244This is used to avoid unnecessary false hits when "git-diff-files" is1245run after git-read-tree.124612473-Way Merge1248~~~~~~~~~~~1249Each "index" entry has two bits worth of "stage" state. stage 0 is the1250normal one, and is the only one you'd see in any kind of normal use.12511252However, when you do "git-read-tree" with three trees, the "stage"1253starts out at 1.12541255This means that you can do12561257 git-read-tree -m <tree1> <tree2> <tree3>12581259and you will end up with an index with all of the <tree1> entries in1260"stage1", all of the <tree2> entries in "stage2" and all of the1261<tree3> entries in "stage3".12621263Furthermore, "git-read-tree" has special-case logic that says: if you see1264a file that matches in all respects in the following states, it1265"collapses" back to "stage0":12661267 - stage 2 and 3 are the same; take one or the other (it makes no1268 difference - the same work has been done on stage 2 and 3)12691270 - stage 1 and stage 2 are the same and stage 3 is different; take1271 stage 3 (some work has been done on stage 3)12721273 - stage 1 and stage 3 are the same and stage 2 is different take1274 stage 2 (some work has been done on stage 2)12751276The "git-write-tree" command refuses to write a nonsensical tree, and it1277will complain about unmerged entries if it sees a single entry that is not1278stage 0.12791280Ok, this all sounds like a collection of totally nonsensical rules,1281but it's actually exactly what you want in order to do a fast1282merge. The different stages represent the "result tree" (stage 0, aka1283"merged"), the original tree (stage 1, aka "orig"), and the two trees1284you are trying to merge (stage 2 and 3 respectively).12851286In fact, the way "git-read-tree" works, it's entirely agnostic about how1287you assign the stages, and you could really assign them any which way,1288and the above is just a suggested way to do it (except since1289"git-write-tree" refuses to write anything but stage0 entries, it makes1290sense to always consider stage 0 to be the "full merge" state).12911292So what happens? Try it out. Select the original tree, and two trees1293to merge, and look how it works:12941295- if a file exists in identical format in all three trees, it will1296 automatically collapse to "merged" state by the new git-read-tree.12971298- a file that has _any_ difference what-so-ever in the three trees1299 will stay as separate entries in the index. It's up to "script1300 policy" to determine how to remove the non-0 stages, and insert a1301 merged version. But since the index is always sorted, they're easy1302 to find: they'll be clustered together.13031304- the index file saves and restores with all this information, so you1305 can merge things incrementally, but as long as it has entries in1306 stages 1/2/3 (ie "unmerged entries") you can't write the result. So1307 now the merge algorithm ends up being really simple:13081309 * you walk the index in order, and ignore all entries of stage 0,1310 since they've already been done.13111312 * if you find a "stage1", but no matching "stage2" or "stage3", you1313 know it's been removed from both trees (it only existed in the1314 original tree), and you remove that entry.13151316 * if you find a matching "stage2" and "stage3" tree, you remove one1317 of them, and turn the other into a "stage0" entry. Remove any1318 matching "stage1" entry if it exists too. .. all the normal1319 trivial rules ..13201321Incidentally - it also means that you don't even have to have a1322separate subdirectory for this. All the information literally is in1323the index file, which is a temporary thing anyway. There is no need to1324worry about what is in the working directory, since it is never shown1325and never used.13261327see also: link:git-write-tree.html[git-write-tree], link:git-ls-files.html[git-ls-files]132813291330NAME1331----1332git-resolve-script - Script used to merge two trees13331334SYNOPSIS1335--------1336'git-resolve-script'13371338DESCRIPTION1339-----------1340This script is used by Linus to merge two trees.134113421343NAME1344----1345git-rev-list - Lists commit objects in reverse chronological order13461347SYNOPSIS1348--------1349'git-rev-list' <commit>13501351DESCRIPTION1352-----------1353Lists commit objects in reverse chronological order starting at the1354given commit, taking ancestry relationship into account. This is1355useful to produce human-readable log output.135613571358NAME1359----1360git-rev-tree - Provides the revision tree for one or more commits13611362SYNOPSIS1363--------1364'git-rev-tree' [--edges] [--cache <cache-file>] [^]<commit> [[^]<commit>]13651366DESCRIPTION1367-----------1368Provides the revision tree for one or more commits.13691370OPTIONS1371-------1372--edges::1373 Show edges (ie places where the marking changes between parent1374 and child)13751376--cache <cache-file>::1377 Use the specified file as a cache from a previous git-rev-list run1378 to speed things up. Note that this "cache" is totally different1379 concept from the directory index. Also this option is not1380 implemented yet.13811382[^]<commit>::1383 The commit id to trace (a leading caret means to ignore this1384 commit-id and below)13851386Output1387------13881389 <date> <commit>:<flags> [<parent-commit>:<flags> ]\*13901391<date>::1392 Date in 'seconds since epoch'13931394<commit>::1395 id of commit object13961397<parent-commit>::1398 id of each parent commit object (>1 indicates a merge)13991400<flags>::14011402 The flags are read as a bitmask representing each commit1403 provided on the commandline. eg: given the command:14041405 $ git-rev-tree <com1> <com2> <com3>14061407 The output:14081409 <date> <commit>:514101411 means that <commit> is reachable from <com1>(1) and <com3>(4)14121413A revtree can get quite large. "git-rev-tree" will eventually allow1414you to cache previous state so that you don't have to follow the whole1415thing down.14161417So the change difference between two commits is literally14181419 git-rev-tree [commit-id1] > commit1-revtree1420 git-rev-tree [commit-id2] > commit2-revtree1421 join -t : commit1-revtree commit2-revtree > common-revisions14221423(this is also how to find the most common parent - you'd look at just1424the head revisions - the ones that aren't referred to by other1425revisions - in "common-revision", and figure out the best one. I1426think.)142714281429NAME1430----1431git-rpull - Pulls from a remote repository over ssh connection143214331434SYNOPSIS1435--------1436'git-rpull' [-c] [-t] [-a] [-v] commit-id url14371438DESCRIPTION1439-----------1440Pulls from a remote repository over ssh connection, invoking git-rpush on1441the other end.14421443OPTIONS1444-------1445-c::1446 Get the commit objects.1447-t::1448 Get trees associated with the commit objects.1449-a::1450 Get all the objects.1451-v::1452 Report what is downloaded.145314541455NAME1456----1457git-rpush - Helper "server-side" program used by git-rpull14581459SYNOPSIS1460--------1461'git-rpush'14621463DESCRIPTION1464-----------1465Helper "server-side" program used by git-rpull.146614671468NAME1469----1470git-tag-script - An example script to create a tag object signed with GPG147114721473SYNOPSIS1474--------1475'git-tag-script'14761477DESCRIPTION1478-----------1479This is an example script that uses "git-mktag" to create a tag object1480signed with GPG.148114821483NAME1484----1485git-tar-tree - Creates a tar archive of the files in the named tree14861487SYNOPSIS1488--------1489'git-tar-tree' <tree-ish> [ <base> ]14901491DESCRIPTION1492-----------1493Creates a tar archive containing the tree structure for the named tree.1494When <base> is specified it is added as a leading path as the files in the1495generated tar archive.149614971498NAME1499----1500git-unpack-file - Creates a temporary file with a blob's contents150115021503SYNOPSIS1504--------1505'git-unpack-file' <blob>15061507DESCRIPTION1508-----------1509Creates a file holding the contents of the blob specified by sha1. It1510returns the name of the temporary file in the following format:1511 .merge_file_XXXXX15121513OPTIONS1514-------1515<blob>::1516 Must be a blob id15171518NAME1519----1520git-update-cache - Modifies the index or directory cache15211522SYNOPSIS1523--------1524'git-update-cache'1525 [--add] [--remove] [--refresh] [--replace]1526 [--ignore-missing]1527 [--force-remove <file>]1528 [--cacheinfo <mode> <object> <file>]\*1529 [--] [<file>]\*15301531DESCRIPTION1532-----------1533Modifies the index or directory cache. Each file mentioned is updated1534into the cache and any 'unmerged' or 'needs updating' state is1535cleared.15361537The way "git-update-cache" handles files it is told about can be modified1538using the various options:15391540OPTIONS1541-------1542--add::1543 If a specified file isn't in the cache already then it's1544 added.1545 Default behaviour is to ignore new files.15461547--remove::1548 If a specified file is in the cache but is missing then it's1549 removed.1550 Default behaviour is to ignore removed file.15511552--refresh::1553 Looks at the current cache and checks to see if merges or1554 updates are needed by checking stat() information.15551556--ignore-missing::1557 Ignores missing files during a --refresh15581559--cacheinfo <mode> <object> <path>::1560 Directly insert the specified info into the cache.15611562--force-remove::1563 Remove the file from the index even when the working directory1564 still has such a file.15651566--replace::1567 By default, when a file `path` exists in the index,1568 git-update-cache refuses an attempt to add `path/file`.1569 Similarly if a file `path/file` exists, a file `path`1570 cannot be added. With --replace flag, existing entries1571 that conflicts with the entry being added are1572 automatically removed with warning messages.15731574--::1575 Do not interpret any more arguments as options.15761577<file>::1578 Files to act on.1579 Note that files begining with '.' are discarded. This includes1580 `./file` and `dir/./file`. If you don't want this, then use 1581 cleaner names.1582 The same applies to directories ending '/' and paths with '//'15831584Using --refresh1585---------------1586'--refresh' does not calculate a new sha1 file or bring the cache1587up-to-date for mode/content changes. But what it *does* do is to1588"re-match" the stat information of a file with the cache, so that you1589can refresh the cache for a file that hasn't been changed but where1590the stat entry is out of date.15911592For example, you'd want to do this after doing a "git-read-tree", to link1593up the stat cache details with the proper files.15941595Using --cacheinfo1596-----------------1597'--cacheinfo' is used to register a file that is not in the current1598working directory. This is useful for minimum-checkout merging.15991600To pretend you have a file with mode and sha1 at path, say:16011602 $ git-update-cache --cacheinfo mode sha1 path16031604To update and refresh only the files already checked out:16051606 git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh160716081609NAME1610----1611git-write-blob - Creates a blob from a file16121613SYNOPSIS1614--------1615'git-write-blob' <any-file-on-the-filesystem>16161617DESCRIPTION1618-----------1619Writes the contents of the named file (which can be outside of the work1620tree) as a blob into the object database, and reports its object ID to its1621standard output. This is used by "git-merge-one-file-script" to update the1622cache without modifying files in the work tree.162316241625NAME1626----1627git-write-tree - Creates a tree from the current cache16281629SYNOPSIS1630--------1631'git-write-tree'16321633DESCRIPTION1634-----------1635Creates a tree object using the current cache.16361637The cache must be merged.16381639Conceptually, "git-write-tree" sync()s the current directory cache contents1640into a set of tree files.1641In order to have that match what is actually in your directory right1642now, you need to have done a "git-update-cache" phase before you did the1643"git-write-tree".16441645164616471648////////////////////////////////////////////////////////////////16491650Producing man pages and html16511652To create a set of html pages run:1653 perl split-docs.pl -html < core-git.txt16541655To create a set of man pages run:1656 perl split-docs.pl -man < core-git.txt165716581659////////////////////////////////////////////////////////////////1660