1This file contains reference information for the core git commands. 2 3The README contains much useful definition and clarification 4info - read that first. And of the commands, I suggest reading 5'git-update-cache' and 'git-read-tree' first - I wish I had! 6 7David Greaves <david@dgreaves.com> 824/4/05 9 10Updated by Junio C Hamano <junkio@cox.net> on 2005-05-05 to 11reflect recent changes. 12 13Identifier terminology used: 14 15<object> 16 Indicates any object sha1 identifier 17 18<blob> 19 Indicates a blob object sha1 identifier 20 21<tree> 22 Indicates a tree object sha1 identifier 23 24<commit> 25 Indicates a commit object sha1 identifier 26 27<tree-ish> 28 Indicates a tree, commit or tag object sha1 identifier. 29 A command that takes a <tree-ish> argument ultimately 30 wants to operate on a <tree> object but automatically 31 dereferences <commit> and <tag> that points at a 32 <tree>. 33 34<type> 35 Indicates that an object type is required. 36 Currently one of: blob/tree/commit/tag 37 38<file> 39 Indicates a filename - always relative to the root of 40 the tree structure GIT_INDEX_FILE describes. 41 42 43################################################################ 44git-apply-patch-script 45 46This is a sample script to be used as GIT_EXTERNAL_DIFF to apply 47differences git-diff-* family of commands reports to the current 48work tree. 49 50 51################################################################ 52git-cat-file 53 git-cat-file (-t | <type>) <object> 54 55Provides contents or type of objects in the repository. The type 56is required if -t is not being used to find the object type. 57 58<object> 59 The sha1 identifier of the object. 60 61-t 62 Instead of the content, show the object type identified 63 by <object>. 64 65<type> 66 Typically this matches the real type of <object> but 67 asking for type that can trivially dereferenced from the 68 given <object> is also permitted. An example is to ask 69 "tree" with <object> for a commit object that contains 70 it, or to ask "blob" with <object> for a tag object that 71 points at it. 72 73Output 74 75If -t is specified, one of the <type>. 76 77Otherwise the raw (though uncompressed) contents of the <object> will 78be returned. 79 80 81################################################################ 82git-check-files 83 git-check-files <file>... 84 85Check that a list of files are up-to-date between the filesystem and 86the cache. Used to verify a patch target before doing a patch. 87 88Files that do not exist on the filesystem are considered up-to-date 89(whether or not they are in the cache). 90 91Emits an error message on failure. 92preparing to update existing file <file> not in cache 93 <file> exists but is not in the cache 94 95preparing to update file <file> not uptodate in cache 96 <file> on disk is not up-to-date with the cache 97 98Exits with a status code indicating success if all files are 99up-to-date. 100 101see also: git-update-cache 102 103 104################################################################ 105git-checkout-cache 106 git-checkout-cache [-q] [-a] [-f] [-n] [--prefix=<string>] 107 [--] <file>... 108 109Will copy all files listed from the cache to the working directory 110(not overwriting existing files). 111 112-q 113 be quiet if files exist or are not in the cache 114 115-f 116 forces overwrite of existing files 117 118-a 119 checks out all files in the cache (will then continue to 120 process listed files). 121 122-n 123 Don't checkout new files, only refresh files already checked 124 out. 125 126--prefix=<string> 127 When creating files, prepend <string> (usually a directory 128 including a trailing /) 129 130-- 131 Do not interpret any more arguments as options. 132 133Note that the order of the flags matters: 134 135 git-checkout-cache -a -f file.c 136 137will first check out all files listed in the cache (but not overwrite 138any old ones), and then force-checkout file.c a second time (ie that 139one _will_ overwrite any old contents with the same filename). 140 141Also, just doing "git-checkout-cache" does nothing. You probably meant 142"git-checkout-cache -a". And if you want to force it, you want 143"git-checkout-cache -f -a". 144 145Intuitiveness is not the goal here. Repeatability is. The reason for 146the "no arguments means no work" thing is that from scripts you are 147supposed to be able to do things like 148 149 find . -name '*.h' -print0 | xargs -0 git-checkout-cache -f -- 150 151which will force all existing *.h files to be replaced with their 152cached copies. If an empty command line implied "all", then this would 153force-refresh everything in the cache, which was not the point. 154 155To update and refresh only the files already checked out: 156 157 git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh 158 159Oh, and the "--" is just a good idea when you know the rest will be 160filenames. Just so that you wouldn't have a filename of "-a" causing 161problems (not possible in the above example, but get used to it in 162scripting!). 163 164The prefix ability basically makes it trivial to use git-checkout-cache as 165a "git-export as tree" function. Just read the desired tree into the 166index, and do a 167 168 git-checkout-cache --prefix=git-export-dir/ -a 169 170and git-checkout-cache will "git-export" the cache into the specified 171directory. 172 173NOTE! The final "/" is important. The git-exported name is literally just 174prefixed with the specified string, so you can also do something like 175 176 git-checkout-cache --prefix=.merged- Makefile 177 178to check out the currently cached copy of "Makefile" into the file 179".merged-Makefile". 180 181 182################################################################ 183git-commit-tree 184 git-commit-tree <tree> [-p <parent commit>]* < changelog 185 186Creates a new commit object based on the provided tree object and 187emits the new commit object id on stdout. If no parent is given then 188it is considered to be an initial tree. 189 190A commit object usually has 1 parent (a commit after a change) or up 191to 16 parents. More than one parent represents a merge of branches 192that led to them. 193 194While a tree represents a particular directory state of a working 195directory, a commit represents that state in "time", and explains how 196to get there. 197 198Normally a commit would identify a new "HEAD" state, and while git 199doesn't care where you save the note about that state, in practice we 200tend to just write the result to the file ".git/HEAD", so that we can 201always see what the last committed state was. 202 203Options 204 205<tree> 206 An existing tree object 207 208-p <parent commit> 209 Each -p indicates a the id of a parent commit object. 210 211 212Commit Information 213 214A commit encapsulates: 215 all parent object ids 216 author name, email and date 217 committer name and email and the commit time. 218 219If not provided, git-commit-tree uses your name, hostname and domain to 220provide author and committer info. This can be overridden using the 221following environment variables. 222 AUTHOR_NAME 223 AUTHOR_EMAIL 224 AUTHOR_DATE 225 COMMIT_AUTHOR_NAME 226 COMMIT_AUTHOR_EMAIL 227(nb <,> and '\n's are stripped) 228 229A commit comment is read from stdin (max 999 chars). If a changelog 230entry is not provided via '<' redirection, git-commit-tree will just wait 231for one to be entered and terminated with ^D 232 233see also: git-write-tree 234 235 236################################################################ 237git-convert-cache 238 239Converts old-style GIT repository to the latest. 240 241 242################################################################ 243git-diff-cache 244 git-diff-cache [-p] [-r] [-z] [-m] [--cached] <tree-ish> 245 246Compares the content and mode of the blobs found via a tree object 247with the content of the current cache and, optionally ignoring the 248stat state of the file on disk. 249 250<tree-ish> 251 The id of a tree object to diff against. 252 253-p 254 Generate patch (see section on generating patches) 255 256-r 257 This flag does not mean anything. It is there only to match 258 git-diff-tree. Unlike git-diff-tree, git-diff-cache always looks 259 at all the subdirectories. 260 261-z 262 \0 line termination on output 263 264--cached 265 do not consider the on-disk file at all 266 267-m 268 269 By default, files recorded in the index but not checked 270 out are reported as deleted. This flag makes 271 git-diff-cache say that all non-checked-out files are up 272 to date. 273 274Output format: 275 276See "Output format from git-diff-cache, git-diff-tree and git-diff-files" 277section. 278 279Operating Modes 280 281You can choose whether you want to trust the index file entirely 282(using the "--cached" flag) or ask the diff logic to show any files 283that don't match the stat state as being "tentatively changed". Both 284of these operations are very useful indeed. 285 286Cached Mode 287 288If --cached is specified, it allows you to ask: 289 290 show me the differences between HEAD and the current index 291 contents (the ones I'd write with a "git-write-tree") 292 293For example, let's say that you have worked on your index file, and are 294ready to commit. You want to see eactly _what_ you are going to commit is 295without having to write a new tree object and compare it that way, and to 296do that, you just do 297 298 git-diff-cache --cached $(cat .git/HEAD) 299 300Example: let's say I had renamed "commit.c" to "git-commit.c", and I had 301done an "git-update-cache" to make that effective in the index file. 302"git-diff-files" wouldn't show anything at all, since the index file 303matches my working directory. But doing a git-diff-cache does: 304 305 torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD) 306 -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c 307 +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c 308 309You can trivially see that the above is a rename. 310 311In fact, "git-diff-cache --cached" _should_ always be entirely equivalent to 312actually doing a "git-write-tree" and comparing that. Except this one is much 313nicer for the case where you just want to check where you are. 314 315So doing a "git-diff-cache --cached" is basically very useful when you are 316asking yourself "what have I already marked for being committed, and 317what's the difference to a previous tree". 318 319Non-cached Mode 320 321The "non-cached" mode takes a different approach, and is potentially the 322even more useful of the two in that what it does can't be emulated with a 323"git-write-tree + git-diff-tree". Thus that's the default mode. The 324non-cached version asks the question 325 326 "show me the differences between HEAD and the currently checked out 327 tree - index contents _and_ files that aren't up-to-date" 328 329which is obviously a very useful question too, since that tells you what 330you _could_ commit. Again, the output matches the "git-diff-tree -r" 331output to a tee, but with a twist. 332 333The twist is that if some file doesn't match the cache, we don't have a 334backing store thing for it, and we use the magic "all-zero" sha1 to show 335that. So let's say that you have edited "kernel/sched.c", but have not 336actually done an git-update-cache on it yet - there is no "object" associated 337with the new state, and you get: 338 339 torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD ) 340 *100644->100664 blob 7476bb......->000000...... kernel/sched.c 341 342ie it shows that the tree has changed, and that "kernel/sched.c" has is 343not up-to-date and may contain new stuff. The all-zero sha1 means that to 344get the real diff, you need to look at the object in the working directory 345directly rather than do an object-to-object diff. 346 347NOTE! As with other commands of this type, "git-diff-cache" does not 348actually look at the contents of the file at all. So maybe 349"kernel/sched.c" hasn't actually changed, and it's just that you touched 350it. In either case, it's a note that you need to upate-cache it to make 351the cache be in sync. 352 353NOTE 2! You can have a mixture of files show up as "has been updated" and 354"is still dirty in the working directory" together. You can always tell 355which file is in which state, since the "has been updated" ones show a 356valid sha1, and the "not in sync with the index" ones will always have the 357special all-zero sha1. 358 359 360################################################################ 361git-diff-tree 362 git-diff-tree [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] <tree-ish> <tree-ish> [<pattern>]* 363 364Compares the content and mode of the blobs found via two tree objects. 365 366Note that git-diff-tree can use the tree encapsulated in a commit object. 367 368<tree-ish> 369 The id of a tree object. 370 371<pattern> 372 If provided, the results are limited to a subset of files 373 matching one of these prefix strings. 374 ie file matches /^<pattern1>|<pattern2>|.../ 375 Note that pattern does not provide any wildcard or regexp 376 features. 377 378-p 379 generate patch (see section on generating patches). For 380 git-diff-tree, this flag implies -r as well. 381 382-r 383 recurse 384 385-z 386 \0 line termination on output 387 388--stdin 389 When --stdin is specified, the command does not take 390 <tree-ish> arguments from the command line. Instead, it 391 reads either one <commit> or a pair of <tree-ish> 392 separated with a single space from its standard input. 393 394 When a single commit is given on one line of such input, 395 it compares the commit with its parents. The following 396 flags further affects its behaviour. This does not 397 apply to the case where two <tree-ish> separated with a 398 single space are given. 399 400-m 401 By default, "git-diff-tree --stdin" does not show 402 differences for merge commits. With this flag, it shows 403 differences to that commit from all of its parents. 404 405-s 406 By default, "git-diff-tree --stdin" shows differences, 407 either in machine-readable form (without -p) or in patch 408 form (with -p). This output can be supressed. It is 409 only useful with -v flag. 410 411-v 412 This flag causes "git-diff-tree --stdin" to also show 413 the commit message before the differences. 414 415 416Limiting Output 417 418If you're only interested in differences in a subset of files, for 419example some architecture-specific files, you might do: 420 421 git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64 422 423and it will only show you what changed in those two directories. 424 425Or if you are searching for what changed in just kernel/sched.c, just do 426 427 git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c 428 429and it will ignore all differences to other files. 430 431The pattern is always the prefix, and is matched exactly. There are no 432wildcards. Even stricter, it has to match complete path comonent. 433I.e. "foo" does not pick up "foobar.h". "foo" does match "foo/bar.h" 434so it can be used to name subdirectories. 435 436Output format: 437 438See "Output format from git-diff-cache, git-diff-tree and git-diff-files" 439section. 440 441An example of normal usage is: 442 443 torvalds@ppc970:~/git> git-diff-tree 5319e4...... 444 *100664->100664 blob ac348b.......->a01513....... git-fsck-cache.c 445 446which tells you that the last commit changed just one file (it's from 447this one: 448 449 commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8 450 tree 5319e4d609cdd282069cc4dce33c1db559539b03 451 parent b4e628ea30d5ab3606119d2ea5caeab141d38df7 452 author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005 453 committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005 454 455 Make "git-fsck-cache" print out all the root commits it finds. 456 457 Once I do the reference tracking, I'll also make it print out all the 458 HEAD commits it finds, which is even more interesting. 459 460in case you care). 461 462 463################################################################ 464git-diff-tree-helper 465 git-diff-tree-helper [-z] [-R] 466 467Reads output from git-diff-cache, git-diff-tree and git-diff-files and 468generates patch format output. 469 470-z 471 \0 line termination on input 472 473-R 474 Output diff in reverse. This is useful for displaying output from 475 git-diff-cache which always compares tree with cache or working 476 file. E.g. 477 478 git-diff-cache <tree> | git-diff-tree-helper -R file.c 479 480 would show a diff to bring the working file back to what is in the 481 <tree>. 482 483See also the section on generating patches. 484 485 486################################################################ 487git-fsck-cache 488 git-fsck-cache [--tags] [--root] [[--unreachable] [--cache] <object>*] 489 490Verifies the connectivity and validity of the objects in the database. 491 492<object> 493 An object to treat as the head of an unreachability trace. 494 495--unreachable 496 Print out objects that exist but that aren't readable from any 497 of the specified head nodes. 498 499--root 500 Report root nodes. 501 502--tags 503 Report tags. 504 505--cache 506 Consider any object recorded in the cache also as a head node for 507 an unreachability trace. 508 509It tests SHA1 and general object sanity, and it does full tracking of 510the resulting reachability and everything else. It prints out any 511corruption it finds (missing or bad objects), and if you use the 512"--unreachable" flag it will also print out objects that exist but 513that aren't readable from any of the specified head nodes. 514 515So for example 516 517 git-fsck-cache --unreachable $(cat .git/HEAD) 518 519or, for Cogito users: 520 521 git-fsck-cache --unreachable $(cat .git/refs/heads/*) 522 523will do quite a _lot_ of verification on the tree. There are a few 524extra validity tests to be added (make sure that tree objects are 525sorted properly etc), but on the whole if "git-fsck-cache" is happy, you 526do have a valid tree. 527 528Any corrupt objects you will have to find in backups or other archives 529(ie you can just remove them and do an "rsync" with some other site in 530the hopes that somebody else has the object you have corrupted). 531 532Of course, "valid tree" doesn't mean that it wasn't generated by some 533evil person, and the end result might be crap. Git is a revision 534tracking system, not a quality assurance system ;) 535 536Extracted Diagnostics 537 538expect dangling commits - potential heads - due to lack of head information 539 You haven't specified any nodes as heads so it won't be 540 possible to differentiate between un-parented commits and 541 root nodes. 542 543missing sha1 directory '<dir>' 544 The directory holding the sha1 objects is missing. 545 546unreachable <type> <object> 547 The <type> object <object>, isn't actually referred to directly 548 or indirectly in any of the trees or commits seen. This can 549 mean that there's another root na SHA1_ode that you're not specifying 550 or that the tree is corrupt. If you haven't missed a root node 551 then you might as well delete unreachable nodes since they 552 can't be used. 553 554missing <type> <object> 555 The <type> object <object>, is referred to but isn't present in 556 the database. 557 558dangling <type> <object> 559 The <type> object <object>, is present in the database but never 560 _directly_ used. A dangling commit could be a root node. 561 562warning: git-fsck-cache: tree <tree> has full pathnames in it 563 And it shouldn't... 564 565sha1 mismatch <object> 566 The database has an object who's sha1 doesn't match the 567 database value. 568 This indicates a ??serious?? data integrity problem. 569 (note: this error occured during early git development when 570 the database format changed.) 571 572Environment Variables 573 574SHA1_FILE_DIRECTORY 575 used to specify the object database root (usually .git/objects) 576 577GIT_INDEX_FILE 578 used to specify the cache 579 580 581################################################################ 582git-export 583 git-export top [base] 584 585Exports each commit and diff against each of its parents, between 586top and base. If base is not specified it exports everything. 587 588 589################################################################ 590git-init-db 591 git-init-db 592 593This simply creates an empty git object database - basically a .git 594directory and .git/object/??/ directories. 595 596If the object storage directory is specified via the SHA1_FILE_DIRECTORY 597environment variable then the sha1 directories are created underneath - 598otherwise the default .git/objects directory is used. 599 600git-init-db won't hurt an existing repository. 601 602 603################################################################ 604git-http-pull 605 606 git-http-pull [-c] [-t] [-a] [-v] commit-id url 607 608Downloads a remote GIT repository via HTTP protocol. 609 610-c 611 Get the commit objects. 612-t 613 Get trees associated with the commit objects. 614-a 615 Get all the objects. 616-v 617 Report what is downloaded. 618 619 620################################################################ 621git-local-pull 622 623 git-local-pull [-c] [-t] [-a] [-l] [-s] [-n] [-v] commit-id path 624 625Downloads another GIT repository on a local system. 626 627-c 628 Get the commit objects. 629-t 630 Get trees associated with the commit objects. 631-a 632 Get all the objects. 633-v 634 Report what is downloaded. 635 636################################################################ 637git-ls-tree 638 git-ls-tree [-r] [-z] <tree-ish> 639 640Converts the tree object to a human readable (and script processable) 641form. 642 643<tree-ish> 644 Id of a tree. 645 646-r 647 recurse into sub-trees 648 649-z 650 \0 line termination on output 651 652Output Format 653<mode>\t <type>\t <object>\t <file> 654 655 656################################################################ 657git-merge-base 658 git-merge-base <commit> <commit> 659 660git-merge-base finds as good a common ancestor as possible. Given a 661selection of equally good common ancestors it should not be relied on 662to decide in any particular way. 663 664The git-merge-base algorithm is still in flux - use the source... 665 666 667################################################################ 668git-merge-cache 669 git-merge-cache <merge-program> (-a | -- | <file>*) 670 671This looks up the <file>(s) in the cache and, if there are any merge 672entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty 673argument if no file), and <file> as argument 4. File modes for the three 674files are passed as arguments 5, 6 and 7. 675 676-- 677 Interpret all future arguments as filenames. 678 679-a 680 Run merge against all files in the cache that need merging. 681 682If git-merge-cache is called with multiple <file>s (or -a) then it 683processes them in turn only stopping if merge returns a non-zero exit 684code. 685 686Typically this is run with the a script calling the merge command from 687the RCS package. 688 689A sample script called git-merge-one-file-script is included in the 690ditribution. 691 692ALERT ALERT ALERT! The git "merge object order" is different from the 693RCS "merge" program merge object order. In the above ordering, the 694original is first. But the argument order to the 3-way merge program 695"merge" is to have the original in the middle. Don't ask me why. 696 697Examples: 698 699 torvalds@ppc970:~/merge-test> git-merge-cache cat MM 700 This is MM from the original tree. # original 701 This is modified MM in the branch A. # merge1 702 This is modified MM in the branch B. # merge2 703 This is modified MM in the branch B. # current contents 704 705or 706 707 torvalds@ppc970:~/merge-test> git-merge-cache cat AA MM 708 cat: : No such file or directory 709 This is added AA in the branch A. 710 This is added AA in the branch B. 711 This is added AA in the branch B. 712 fatal: merge program failed 713 714where the latter example shows how "git-merge-cache" will stop trying to 715merge once anything has returned an error (ie "cat" returned an error 716for the AA file, because it didn't exist in the original, and thus 717"git-merge-cache" didn't even try to merge the MM thing). 718 719################################################################ 720git-merge-one-file-script 721 722This is the standard helper program to use with git-merge-cache 723to resolve a merge after the trivial merge done with git-read-tree -m. 724 725################################################################ 726git-mktag 727 728Reads a tag contents from its standard input and creates a tag object. 729The input must be a well formed tag object. 730 731 732################################################################ 733git-prune-script 734 735This runs git-fsck-cache --unreachable program using the heads specified 736on the command line (or .git/refs/heads/* and .git/refs/tags/* if none is 737specified), and prunes all unreachable objects from the object database. 738 739 740################################################################ 741git-pull-script 742 743This script is used by Linus to pull from a remote repository and perform 744a merge. 745 746 747################################################################ 748git-read-tree 749 git-read-tree (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])" 750 751Reads the tree information given by <tree> into the directory cache, 752but does not actually _update_ any of the files it "caches". (see: 753git-checkout-cache) 754 755Optionally, it can merge a tree into the cache or perform a 3-way 756merge. 757 758Trivial merges are done by git-read-tree itself. Only conflicting paths 759will be in unmerged state when git-read-tree returns. 760 761-m 762 Perform a merge, not just a read 763 764<tree-ish#> 765 The id of the tree object(s) to be read/merged. 766 767 768Merging 769If -m is specified, git-read-tree performs 2 kinds of merge, a single tree 770merge if only 1 tree is given or a 3-way merge if 3 trees are 771provided. 772 773Single Tree Merge 774If only 1 tree is specified, git-read-tree operates as if the user did not 775specify "-m", except that if the original cache has an entry for a 776given pathname; and the contents of the path matches with the tree 777being read, the stat info from the cache is used. (In other words, the 778cache's stat()s take precedence over the merged tree's) 779 780That means that if you do a "git-read-tree -m <newtree>" followed by a 781"git-checkout-cache -f -a", the git-checkout-cache only checks out the stuff 782that really changed. 783 784This is used to avoid unnecessary false hits when git-diff-files is 785run after git-read-tree. 786 7873-Way Merge 788Each "index" entry has two bits worth of "stage" state. stage 0 is the 789normal one, and is the only one you'd see in any kind of normal use. 790 791However, when you do "git-read-tree" with three trees, the "stage" 792starts out at 1. 793 794This means that you can do 795 796 git-read-tree -m <tree1> <tree2> <tree3> 797 798and you will end up with an index with all of the <tree1> entries in 799"stage1", all of the <tree2> entries in "stage2" and all of the 800<tree3> entries in "stage3". 801 802Furthermore, "git-read-tree" has special-case logic that says: if you see 803a file that matches in all respects in the following states, it 804"collapses" back to "stage0": 805 806 - stage 2 and 3 are the same; take one or the other (it makes no 807 difference - the same work has been done on stage 2 and 3) 808 809 - stage 1 and stage 2 are the same and stage 3 is different; take 810 stage 3 (some work has been done on stage 3) 811 812 - stage 1 and stage 3 are the same and stage 2 is different take 813 stage 2 (some work has been done on stage 2) 814 815The git-write-tree command refuses to write a nonsensical tree, and it 816will complain about unmerged entries if it sees a single entry that is not 817stage 0. 818 819Ok, this all sounds like a collection of totally nonsensical rules, 820but it's actually exactly what you want in order to do a fast 821merge. The different stages represent the "result tree" (stage 0, aka 822"merged"), the original tree (stage 1, aka "orig"), and the two trees 823you are trying to merge (stage 2 and 3 respectively). 824 825In fact, the way "git-read-tree" works, it's entirely agnostic about how 826you assign the stages, and you could really assign them any which way, 827and the above is just a suggested way to do it (except since 828"git-write-tree" refuses to write anything but stage0 entries, it makes 829sense to always consider stage 0 to be the "full merge" state). 830 831So what happens? Try it out. Select the original tree, and two trees 832to merge, and look how it works: 833 834 - if a file exists in identical format in all three trees, it will 835 automatically collapse to "merged" state by the new git-read-tree. 836 837 - a file that has _any_ difference what-so-ever in the three trees 838 will stay as separate entries in the index. It's up to "script 839 policy" to determine how to remove the non-0 stages, and insert a 840 merged version. But since the index is always sorted, they're easy 841 to find: they'll be clustered together. 842 843 - the index file saves and restores with all this information, so you 844 can merge things incrementally, but as long as it has entries in 845 stages 1/2/3 (ie "unmerged entries") you can't write the result. 846 847So now the merge algorithm ends up being really simple: 848 849 - you walk the index in order, and ignore all entries of stage 0, 850 since they've already been done. 851 852 - if you find a "stage1", but no matching "stage2" or "stage3", you 853 know it's been removed from both trees (it only existed in the 854 original tree), and you remove that entry. - if you find a 855 matching "stage2" and "stage3" tree, you remove one of them, and 856 turn the other into a "stage0" entry. Remove any matching "stage1" 857 entry if it exists too. .. all the normal trivial rules .. 858 859Incidentally - it also means that you don't even have to have a separate 860subdirectory for this. All the information literally is in the index file, 861which is a temporary thing anyway. There is no need to worry about what is 862in the working directory, since it is never shown and never used. 863 864see also: 865git-write-tree 866git-ls-files 867 868 869################################################################ 870git-resolve-script 871 872This script is used by Linus to merge two trees. 873 874 875################################################################ 876git-rev-list <commit> 877 878Lists commit objects in reverse chronological order starting at the 879given commit, taking ancestry relationship into account. This is 880useful to produce human-readable log output. 881 882 883################################################################ 884git-rev-tree 885 git-rev-tree [--edges] [--cache <cache-file>] [^]<commit> [[^]<commit>] 886 887Provides the revision tree for one or more commits. 888 889--edges 890 Show edges (ie places where the marking changes between parent 891 and child) 892 893--cache <cache-file> 894 Use the specified file as a cache from a previous git-rev-list run 895 to speed things up. Note that this "cache" is totally different 896 concept from the directory index. Also this option is not 897 implemented yet. 898 899[^]<commit> 900 The commit id to trace (a leading caret means to ignore this 901 commit-id and below) 902 903Output: 904<date> <commit>:<flags> [<parent-commit>:<flags> ]* 905 906<date> 907 Date in 'seconds since epoch' 908 909<commit> 910 id of commit object 911 912<parent-commit> 913 id of each parent commit object (>1 indicates a merge) 914 915<flags> 916 917 The flags are read as a bitmask representing each commit 918 provided on the commandline. eg: given the command: 919 920 $ git-rev-tree <com1> <com2> <com3> 921 922 The output: 923 924 <date> <commit>:5 925 926 means that <commit> is reachable from <com1>(1) and <com3>(4) 927 928A revtree can get quite large. git-rev-tree will eventually allow you to 929cache previous state so that you don't have to follow the whole thing 930down. 931 932So the change difference between two commits is literally 933 934 git-rev-tree [commit-id1] > commit1-revtree 935 git-rev-tree [commit-id2] > commit2-revtree 936 join -t : commit1-revtree commit2-revtree > common-revisions 937 938(this is also how to find the most common parent - you'd look at just 939the head revisions - the ones that aren't referred to by other 940revisions - in "common-revision", and figure out the best one. I 941think.) 942 943 944################################################################ 945git-rpull 946 947 git-rpull [-c] [-t] [-a] [-v] commit-id url 948 949Pulls from a remote repository over ssh connection, invoking git-rpush on 950the other end. 951 952-c 953 Get the commit objects. 954-t 955 Get trees associated with the commit objects. 956-a 957 Get all the objects. 958-v 959 Report what is downloaded. 960 961 962################################################################ 963git-rpush 964 965Helper "server-side" program used by git-rpull. 966 967 968################################################################ 969git-diff-files 970 git-diff-files [-p] [-q] [-r] [-z] [<pattern>...] 971 972Compares the files in the working tree and the cache. When paths 973are specified, compares only those named paths. Otherwise all 974entries in the cache are compared. The output format is the 975same as git-diff-cache and git-diff-tree. 976 977-p 978 generate patch (see section on generating patches). 979 980-q 981 Remain silent even on nonexisting files 982 983-r 984 This flag does not mean anything. It is there only to match 985 git-diff-tree. Unlike git-diff-tree, git-diff-files always looks 986 at all the subdirectories. 987 988 989Output format: 990 991See "Output format from git-diff-cache, git-diff-tree and git-diff-files" 992section. 993 994 995################################################################ 996git-tag-script 997 998This is an example script that uses git-mktag to create a tag object 999signed with GPG.100010011002################################################################1003git-tar-tree10041005 git-tar-tree <tree-ish> [ <base> ]10061007Creates a tar archive containing the tree structure for the named tree.1008When <base> is specified it is added as a leading path as the files in the1009generated tar archive.101010111012################################################################1013git-ls-files1014 git-ls-files [-z] [-t]1015 (--[cached|deleted|others|ignored|stage|unmerged])*1016 (-[c|d|o|i|s|u])*1017 [-x <pattern>|--exclude=<pattern>]1018 [-X <file>|--exclude-from=<file>]10191020This merges the file listing in the directory cache index with the1021actual working directory list, and shows different combinations of the1022two.10231024One or more of the options below may be used to determine the files1025shown:10261027-c|--cached1028 Show cached files in the output (default)10291030-d|--deleted1031 Show deleted files in the output10321033-o|--others1034 Show other files in the output10351036-i|--ignored1037 Show ignored files in the output1038 Note the this also reverses any exclude list present.10391040-s|--stage1041 Show stage files in the output10421043-u|--unmerged1044 Show unmerged files in the output (forces --stage)10451046-z1047 \0 line termination on output10481049-x|--exclude=<pattern>1050 Skips files matching pattern.1051 Note that pattern is a shell wildcard pattern.10521053-X|--exclude-from=<file>1054 exclude patterns are read from <file>; 1 per line.1055 Allows the use of the famous dontdiff file as follows to find1056 out about uncommitted files just as dontdiff is used with1057 the diff command:1058 git-ls-files --others --exclude-from=dontdiff10591060-t1061 Identify the file status with the following tags (followed by1062 a space) at the start of each line:1063 H cached1064 M unmerged1065 R removed/deleted1066 ? other10671068Output1069show files just outputs the filename unless --stage is specified in1070which case it outputs:10711072[<tag> ]<mode> <object> <stage> <file>10731074git-ls-files --unmerged" and "git-ls-files --stage " can be used to examine1075detailed information on unmerged paths.10761077For an unmerged path, instead of recording a single mode/SHA1 pair,1078the dircache records up to three such pairs; one from tree O in stage10791, A in stage 2, and B in stage 3. This information can be used by1080the user (or Cogito) to see what should eventually be recorded at the1081path. (see read-cache for more information on state)10821083see also:1084read-cache108510861087################################################################1088git-unpack-file1089 git-unpack-file <blob>10901091Creates a file holding the contents of the blob specified by sha1. It1092returns the name of the temporary file in the following format:1093 .merge_file_XXXXX10941095<blob>1096 Must be a blob id10971098################################################################1099git-update-cache1100 git-update-cache1101 [--add] [--remove] [--refresh]1102 [--ignore-missing]1103 [--force-remove <file>]1104 [--cacheinfo <mode> <object> <file>]*1105 [--] [<file>]*11061107Modifies the index or directory cache. Each file mentioned is updated1108into the cache and any 'unmerged' or 'needs updating' state is1109cleared.11101111The way git-update-cache handles files it is told about can be modified1112using the various options:11131114--add1115 If a specified file isn't in the cache already then it's1116 added.1117 Default behaviour is to ignore new files.11181119--remove1120 If a specified file is in the cache but is missing then it's1121 removed.1122 Default behaviour is to ignore removed file.11231124--refresh1125 Looks at the current cache and checks to see if merges or1126 updates are needed by checking stat() information.11271128--ignore-missing1129 Ignores missing files during a --refresh11301131--cacheinfo <mode> <object> <path>1132 Directly insert the specified info into the cache.11331134--force-remove1135 Remove the file from the index even when the working directory1136 still has such a file.11371138--1139 Do not interpret any more arguments as options.11401141<file>1142 Files to act on.1143 Note that files begining with '.' are discarded. This includes1144 "./file" and "dir/./file". If you don't want this, then use 1145 cleaner names.1146 The same applies to directories ending '/' and paths with '//'11471148Using --refresh1149--refresh does not calculate a new sha1 file or bring the cache1150up-to-date for mode/content changes. But what it _does_ do is to1151"re-match" the stat information of a file with the cache, so that you1152can refresh the cache for a file that hasn't been changed but where1153the stat entry is out of date.11541155For example, you'd want to do this after doing a "git-read-tree", to link1156up the stat cache details with the proper files.11571158Using --cacheinfo1159--cacheinfo is used to register a file that is not in the current1160working directory. This is useful for minimum-checkout merging.11611162To pretend you have a file with mode and sha1 at path, say:11631164 $ git-update-cache --cacheinfo mode sha1 path11651166To update and refresh only the files already checked out:11671168 git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh116911701171################################################################1172git-write-blob11731174 git-write-blob <any-file-on-the-filesystem>11751176Writes the contents of the named file (which can be outside of the work1177tree) as a blob into the object database, and reports its object ID to its1178standard output. This is used by git-merge-one-file-script to update the1179cache without modifying files in the work tree.118011811182################################################################1183git-write-tree1184 git-write-tree11851186Creates a tree object using the current cache.11871188The cache must be merged.11891190Conceptually, git-write-tree sync()s the current directory cache contents1191into a set of tree files.1192In order to have that match what is actually in your directory right1193now, you need to have done a "git-update-cache" phase before you did the1194"git-write-tree".119511961197################################################################11981199Output format from git-diff-cache, git-diff-tree and git-diff-files.12001201These commands all compare two sets of things; what are1202compared are different:12031204 git-diff-cache <tree-ish>12051206 compares the <tree-ish> and the files on the filesystem.12071208 git-diff-cache --cached <tree-ish>12091210 compares the <tree-ish> and the cache.12111212 git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]12131214 compares the trees named by the two arguments.12151216 git-diff-files [<pattern>...]12171218 compares the cache and the files on the filesystem.12191220The following desription uses "old" and "new" to mean those1221compared entities.12221223For files in old but not in new (i.e. removed):1224-<mode> \t <type> \t <object> \t <path>12251226For files not in old but in new (i.e. added):1227+<mode> \t <type> \t <object> \t <path>12281229For files that differ:1230*<old-mode>-><new-mode> \t <type> \t <old-sha1>-><new-sha1> \t <path>12311232<new-sha1> is shown as all 0's if new is a file on the1233filesystem and it is out of sync with the cache. Example:12341235 *100644->100644 blob 5be4a4.......->000000....... file.c12361237################################################################12381239Generating patches12401241When git-diff-cache, git-diff-tree, or git-diff-files are run with a -p1242option, they do not produce the output described in "Output format from1243git-diff-cache, git-diff-tree and git-diff-files" section. It instead1244produces a patch file.12451246The patch generation can be customized at two levels. This1247customization also applies to git-diff-tree-helper.124812491. When the environment variable GIT_EXTERNAL_DIFF is not set,1250 these commands internally invoke diff like this:12511252 diff -L a/<path> -L a/<path> -pu <old> <new>12531254 For added files, /dev/null is used for <old>. For removed1255 files, /dev/null is used for <new>12561257 The diff formatting options can be customized via the1258 environment variable GIT_DIFF_OPTS. For example, if you1259 prefer context diff:12601261 GIT_DIFF_OPTS=-c git-diff-cache -p $(cat .git/HEAD)1262126312642. When the environment variable GIT_EXTERNAL_DIFF is set, the1265 program named by it is called, instead of the diff invocation1266 described above.12671268 For a path that is added, removed, or modified,1269 GIT_EXTERNAL_DIFF is called with 7 parameters:12701271 path old-file old-hex old-mode new-file new-hex new-mode12721273 where1274 <old|new>-file are files GIT_EXTERNAL_DIFF can use to read the1275 contents of <old|ne>,1276 <old|new>-hex are the 40-hexdigit SHA1 hashes,1277 <old|new>-mode are the octal representation of the file modes.12781279 The file parameters can point at the user's working file (e.g. new-file1280 in git-diff-files), /dev/null (e.g. old-file when a new file is added),1281 or a temporary file (e.g. old-file in the cache). GIT_EXTERNAL_DIFF1282 should not worry about unlinking the temporary file --- it is removed1283 when GIT_EXTERNAL_DIFF exits.12841285 For a path that is unmerged, GIT_EXTERNAL_DIFF is called with1286 1 parameter, path.12871288################################################################12891290Terminology: - see README for description1291Each line contains terms used interchangeably12921293object database, .git directory1294directory cache, index1295id, sha1, sha1-id, sha1 hash1296type, tag1297blob, blob object1298tree, tree object1299commit, commit object1300parent1301root object1302changeset130313041305git Environment Variables1306AUTHOR_NAME1307AUTHOR_EMAIL1308AUTHOR_DATE1309COMMIT_AUTHOR_NAME1310COMMIT_AUTHOR_EMAIL1311GIT_DIFF_OPTS1312GIT_EXTERNAL_DIFF1313GIT_INDEX_FILE1314SHA1_FILE_DIRECTORY