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] [--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 267Output format: 268 269See "Output format from git-diff-cache, git-diff-tree and git-diff-files" 270section. 271 272Operating Modes 273 274You can choose whether you want to trust the index file entirely 275(using the "--cached" flag) or ask the diff logic to show any files 276that don't match the stat state as being "tentatively changed". Both 277of these operations are very useful indeed. 278 279Cached Mode 280 281If --cached is specified, it allows you to ask: 282 283 show me the differences between HEAD and the current index 284 contents (the ones I'd write with a "git-write-tree") 285 286For example, let's say that you have worked on your index file, and are 287ready to commit. You want to see eactly _what_ you are going to commit is 288without having to write a new tree object and compare it that way, and to 289do that, you just do 290 291 git-diff-cache --cached $(cat .git/HEAD) 292 293Example: let's say I had renamed "commit.c" to "git-commit.c", and I had 294done an "git-update-cache" to make that effective in the index file. 295"git-diff-files" wouldn't show anything at all, since the index file 296matches my working directory. But doing a git-diff-cache does: 297 298 torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD) 299 -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c 300 +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c 301 302You can trivially see that the above is a rename. 303 304In fact, "git-diff-cache --cached" _should_ always be entirely equivalent to 305actually doing a "git-write-tree" and comparing that. Except this one is much 306nicer for the case where you just want to check where you are. 307 308So doing a "git-diff-cache --cached" is basically very useful when you are 309asking yourself "what have I already marked for being committed, and 310what's the difference to a previous tree". 311 312Non-cached Mode 313 314The "non-cached" mode takes a different approach, and is potentially the 315even more useful of the two in that what it does can't be emulated with a 316"git-write-tree + git-diff-tree". Thus that's the default mode. The 317non-cached version asks the question 318 319 "show me the differences between HEAD and the currently checked out 320 tree - index contents _and_ files that aren't up-to-date" 321 322which is obviously a very useful question too, since that tells you what 323you _could_ commit. Again, the output matches the "git-diff-tree -r" 324output to a tee, but with a twist. 325 326The twist is that if some file doesn't match the cache, we don't have a 327backing store thing for it, and we use the magic "all-zero" sha1 to show 328that. So let's say that you have edited "kernel/sched.c", but have not 329actually done an git-update-cache on it yet - there is no "object" associated 330with the new state, and you get: 331 332 torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD ) 333 *100644->100664 blob 7476bb......->000000...... kernel/sched.c 334 335ie it shows that the tree has changed, and that "kernel/sched.c" has is 336not up-to-date and may contain new stuff. The all-zero sha1 means that to 337get the real diff, you need to look at the object in the working directory 338directly rather than do an object-to-object diff. 339 340NOTE! As with other commands of this type, "git-diff-cache" does not 341actually look at the contents of the file at all. So maybe 342"kernel/sched.c" hasn't actually changed, and it's just that you touched 343it. In either case, it's a note that you need to upate-cache it to make 344the cache be in sync. 345 346NOTE 2! You can have a mixture of files show up as "has been updated" and 347"is still dirty in the working directory" together. You can always tell 348which file is in which state, since the "has been updated" ones show a 349valid sha1, and the "not in sync with the index" ones will always have the 350special all-zero sha1. 351 352 353################################################################ 354git-diff-tree 355 git-diff-tree [-p] [-r] [-z] <tree-ish> <tree-ish> [<pattern>]* 356 357Compares the content and mode of the blobs found via two tree objects. 358 359Note that git-diff-tree can use the tree encapsulated in a commit object. 360 361<tree-ish> 362 The id of a tree object. 363 364<pattern> 365 If provided, the results are limited to a subset of files 366 matching one of these prefix strings. 367 ie file matches /^<pattern1>|<pattern2>|.../ 368 Note that pattern does not provide any wildcard or regexp 369 features. 370 371-p 372 generate patch (see section on generating patches). For 373 git-diff-tree, this flag implies -r as well. 374 375-r 376 recurse 377 378-z 379 \0 line termination on output 380 381Limiting Output 382 383If you're only interested in differences in a subset of files, for 384example some architecture-specific files, you might do: 385 386 git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64 387 388and it will only show you what changed in those two directories. 389 390Or if you are searching for what changed in just kernel/sched.c, just do 391 392 git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c 393 394and it will ignore all differences to other files. 395 396The pattern is always the prefix, and is matched exactly. There are no 397wildcards. Even stricter, it has to match complete path comonent. 398I.e. "foo" does not pick up "foobar.h". "foo" does match "foo/bar.h" 399so it can be used to name subdirectories. 400 401Output format: 402 403See "Output format from git-diff-cache, git-diff-tree and git-diff-files" 404section. 405 406An example of normal usage is: 407 408 torvalds@ppc970:~/git> git-diff-tree 5319e4...... 409 *100664->100664 blob ac348b.......->a01513....... git-fsck-cache.c 410 411which tells you that the last commit changed just one file (it's from 412this one: 413 414 commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8 415 tree 5319e4d609cdd282069cc4dce33c1db559539b03 416 parent b4e628ea30d5ab3606119d2ea5caeab141d38df7 417 author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005 418 committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005 419 420 Make "git-fsck-cache" print out all the root commits it finds. 421 422 Once I do the reference tracking, I'll also make it print out all the 423 HEAD commits it finds, which is even more interesting. 424 425in case you care). 426 427 428################################################################ 429git-diff-tree-helper 430 git-diff-tree-helper [-z] [-R] 431 432Reads output from git-diff-cache, git-diff-tree and git-diff-files and 433generates patch format output. 434 435-z 436 \0 line termination on input 437 438-R 439 Output diff in reverse. This is useful for displaying output from 440 git-diff-cache which always compares tree with cache or working 441 file. E.g. 442 443 git-diff-cache <tree> | git-diff-tree-helper -R file.c 444 445 would show a diff to bring the working file back to what is in the 446 <tree>. 447 448See also the section on generating patches. 449 450 451################################################################ 452git-fsck-cache 453 git-fsck-cache [--tags] [--root] [[--unreachable] [--cache] <object>*] 454 455Verifies the connectivity and validity of the objects in the database. 456 457<object> 458 An object to treat as the head of an unreachability trace. 459 460--unreachable 461 Print out objects that exist but that aren't readable from any 462 of the specified head nodes. 463 464--root 465 Report root nodes. 466 467--tags 468 Report tags. 469 470--cache 471 Consider any object recorded in the cache also as a head node for 472 an unreachability trace. 473 474It tests SHA1 and general object sanity, and it does full tracking of 475the resulting reachability and everything else. It prints out any 476corruption it finds (missing or bad objects), and if you use the 477"--unreachable" flag it will also print out objects that exist but 478that aren't readable from any of the specified head nodes. 479 480So for example 481 482 git-fsck-cache --unreachable $(cat .git/HEAD) 483 484or, for Cogito users: 485 486 git-fsck-cache --unreachable $(cat .git/refs/heads/*) 487 488will do quite a _lot_ of verification on the tree. There are a few 489extra validity tests to be added (make sure that tree objects are 490sorted properly etc), but on the whole if "git-fsck-cache" is happy, you 491do have a valid tree. 492 493Any corrupt objects you will have to find in backups or other archives 494(ie you can just remove them and do an "rsync" with some other site in 495the hopes that somebody else has the object you have corrupted). 496 497Of course, "valid tree" doesn't mean that it wasn't generated by some 498evil person, and the end result might be crap. Git is a revision 499tracking system, not a quality assurance system ;) 500 501Extracted Diagnostics 502 503expect dangling commits - potential heads - due to lack of head information 504 You haven't specified any nodes as heads so it won't be 505 possible to differentiate between un-parented commits and 506 root nodes. 507 508missing sha1 directory '<dir>' 509 The directory holding the sha1 objects is missing. 510 511unreachable <type> <object> 512 The <type> object <object>, isn't actually referred to directly 513 or indirectly in any of the trees or commits seen. This can 514 mean that there's another root na SHA1_ode that you're not specifying 515 or that the tree is corrupt. If you haven't missed a root node 516 then you might as well delete unreachable nodes since they 517 can't be used. 518 519missing <type> <object> 520 The <type> object <object>, is referred to but isn't present in 521 the database. 522 523dangling <type> <object> 524 The <type> object <object>, is present in the database but never 525 _directly_ used. A dangling commit could be a root node. 526 527warning: git-fsck-cache: tree <tree> has full pathnames in it 528 And it shouldn't... 529 530sha1 mismatch <object> 531 The database has an object who's sha1 doesn't match the 532 database value. 533 This indicates a ??serious?? data integrity problem. 534 (note: this error occured during early git development when 535 the database format changed.) 536 537Environment Variables 538 539SHA1_FILE_DIRECTORY 540 used to specify the object database root (usually .git/objects) 541 542GIT_INDEX_FILE 543 used to specify the cache 544 545 546################################################################ 547git-export 548 git-export top [base] 549 550Exports each commit and diff against each of its parents, between 551top and base. If base is not specified it exports everything. 552 553 554################################################################ 555git-init-db 556 git-init-db 557 558This simply creates an empty git object database - basically a .git 559directory and .git/object/??/ directories. 560 561If the object storage directory is specified via the SHA1_FILE_DIRECTORY 562environment variable then the sha1 directories are created underneath - 563otherwise the default .git/objects directory is used. 564 565git-init-db won't hurt an existing repository. 566 567 568################################################################ 569git-http-pull 570 571Downloads a remote GIT repository via HTTP protocol. 572 573 574################################################################ 575git-local-pull 576 577Downloads another GIT repository on a local system. 578 579 580################################################################ 581git-ls-tree 582 git-ls-tree [-r] [-z] <tree-ish> 583 584Converts the tree object to a human readable (and script processable) 585form. 586 587<tree-ish> 588 Id of a tree. 589 590-r 591 recurse into sub-trees 592 593-z 594 \0 line termination on output 595 596Output Format 597<mode>\t <type>\t <object>\t <file> 598 599 600################################################################ 601git-merge-base 602 git-merge-base <commit> <commit> 603 604git-merge-base finds as good a common ancestor as possible. Given a 605selection of equally good common ancestors it should not be relied on 606to decide in any particular way. 607 608The git-merge-base algorithm is still in flux - use the source... 609 610 611################################################################ 612git-merge-cache 613 git-merge-cache <merge-program> (-a | -- | <file>*) 614 615This looks up the <file>(s) in the cache and, if there are any merge 616entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty 617argument if no file), and <file> as argument 4. File modes for the three 618files are passed as arguments 5, 6 and 7. 619 620-- 621 Interpret all future arguments as filenames. 622 623-a 624 Run merge against all files in the cache that need merging. 625 626If git-merge-cache is called with multiple <file>s (or -a) then it 627processes them in turn only stopping if merge returns a non-zero exit 628code. 629 630Typically this is run with the a script calling the merge command from 631the RCS package. 632 633A sample script called git-merge-one-file-script is included in the 634ditribution. 635 636ALERT ALERT ALERT! The git "merge object order" is different from the 637RCS "merge" program merge object order. In the above ordering, the 638original is first. But the argument order to the 3-way merge program 639"merge" is to have the original in the middle. Don't ask me why. 640 641Examples: 642 643 torvalds@ppc970:~/merge-test> git-merge-cache cat MM 644 This is MM from the original tree. # original 645 This is modified MM in the branch A. # merge1 646 This is modified MM in the branch B. # merge2 647 This is modified MM in the branch B. # current contents 648 649or 650 651 torvalds@ppc970:~/merge-test> git-merge-cache cat AA MM 652 cat: : No such file or directory 653 This is added AA in the branch A. 654 This is added AA in the branch B. 655 This is added AA in the branch B. 656 fatal: merge program failed 657 658where the latter example shows how "git-merge-cache" will stop trying to 659merge once anything has returned an error (ie "cat" returned an error 660for the AA file, because it didn't exist in the original, and thus 661"git-merge-cache" didn't even try to merge the MM thing). 662 663################################################################ 664git-merge-one-file-script 665 666This is the standard helper program to use with git-merge-cache 667to resolve a merge after the trivial merge done with git-read-tree -m. 668 669################################################################ 670git-mktag 671 672Reads a tag contents from its standard input and creates a tag object. 673The input must be a well formed tag object. 674 675 676################################################################ 677git-prune-script 678 679This runs git-fsck-cache --unreachable program using the heads specified 680on the command line (or .git/refs/heads/* and .git/refs/tags/* if none is 681specified), and prunes all unreachable objects from the object database. 682 683 684################################################################ 685git-pull-script 686 687This script is used by Linus to pull from a remote repository and perform 688a merge. 689 690 691################################################################ 692git-read-tree 693 git-read-tree (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])" 694 695Reads the tree information given by <tree> into the directory cache, 696but does not actually _update_ any of the files it "caches". (see: 697git-checkout-cache) 698 699Optionally, it can merge a tree into the cache or perform a 3-way 700merge. 701 702Trivial merges are done by git-read-tree itself. Only conflicting paths 703will be in unmerged state when git-read-tree returns. 704 705-m 706 Perform a merge, not just a read 707 708<tree-ish#> 709 The id of the tree object(s) to be read/merged. 710 711 712Merging 713If -m is specified, git-read-tree performs 2 kinds of merge, a single tree 714merge if only 1 tree is given or a 3-way merge if 3 trees are 715provided. 716 717Single Tree Merge 718If only 1 tree is specified, git-read-tree operates as if the user did not 719specify "-m", except that if the original cache has an entry for a 720given pathname; and the contents of the path matches with the tree 721being read, the stat info from the cache is used. (In other words, the 722cache's stat()s take precedence over the merged tree's) 723 724That means that if you do a "git-read-tree -m <newtree>" followed by a 725"git-checkout-cache -f -a", the git-checkout-cache only checks out the stuff 726that really changed. 727 728This is used to avoid unnecessary false hits when git-diff-files is 729run after git-read-tree. 730 7313-Way Merge 732Each "index" entry has two bits worth of "stage" state. stage 0 is the 733normal one, and is the only one you'd see in any kind of normal use. 734 735However, when you do "git-read-tree" with three trees, the "stage" 736starts out at 1. 737 738This means that you can do 739 740 git-read-tree -m <tree1> <tree2> <tree3> 741 742and you will end up with an index with all of the <tree1> entries in 743"stage1", all of the <tree2> entries in "stage2" and all of the 744<tree3> entries in "stage3". 745 746Furthermore, "git-read-tree" has special-case logic that says: if you see 747a file that matches in all respects in the following states, it 748"collapses" back to "stage0": 749 750 - stage 2 and 3 are the same; take one or the other (it makes no 751 difference - the same work has been done on stage 2 and 3) 752 753 - stage 1 and stage 2 are the same and stage 3 is different; take 754 stage 3 (some work has been done on stage 3) 755 756 - stage 1 and stage 3 are the same and stage 2 is different take 757 stage 2 (some work has been done on stage 2) 758 759The git-write-tree command refuses to write a nonsensical tree, and it 760will complain about unmerged entries if it sees a single entry that is not 761stage 0. 762 763Ok, this all sounds like a collection of totally nonsensical rules, 764but it's actually exactly what you want in order to do a fast 765merge. The different stages represent the "result tree" (stage 0, aka 766"merged"), the original tree (stage 1, aka "orig"), and the two trees 767you are trying to merge (stage 2 and 3 respectively). 768 769In fact, the way "git-read-tree" works, it's entirely agnostic about how 770you assign the stages, and you could really assign them any which way, 771and the above is just a suggested way to do it (except since 772"git-write-tree" refuses to write anything but stage0 entries, it makes 773sense to always consider stage 0 to be the "full merge" state). 774 775So what happens? Try it out. Select the original tree, and two trees 776to merge, and look how it works: 777 778 - if a file exists in identical format in all three trees, it will 779 automatically collapse to "merged" state by the new git-read-tree. 780 781 - a file that has _any_ difference what-so-ever in the three trees 782 will stay as separate entries in the index. It's up to "script 783 policy" to determine how to remove the non-0 stages, and insert a 784 merged version. But since the index is always sorted, they're easy 785 to find: they'll be clustered together. 786 787 - the index file saves and restores with all this information, so you 788 can merge things incrementally, but as long as it has entries in 789 stages 1/2/3 (ie "unmerged entries") you can't write the result. 790 791So now the merge algorithm ends up being really simple: 792 793 - you walk the index in order, and ignore all entries of stage 0, 794 since they've already been done. 795 796 - if you find a "stage1", but no matching "stage2" or "stage3", you 797 know it's been removed from both trees (it only existed in the 798 original tree), and you remove that entry. - if you find a 799 matching "stage2" and "stage3" tree, you remove one of them, and 800 turn the other into a "stage0" entry. Remove any matching "stage1" 801 entry if it exists too. .. all the normal trivial rules .. 802 803Incidentally - it also means that you don't even have to have a separate 804subdirectory for this. All the information literally is in the index file, 805which is a temporary thing anyway. There is no need to worry about what is 806in the working directory, since it is never shown and never used. 807 808see also: 809git-write-tree 810git-ls-files 811 812 813################################################################ 814git-resolve-script 815 816This script is used by Linus to merge two trees. 817 818 819################################################################ 820git-rev-list <commit> 821 822Lists commit objects in reverse chronological order starting at the 823given commit, taking ancestry relationship into account. This is 824useful to produce human-readable log output. 825 826 827################################################################ 828git-rev-tree 829 git-rev-tree [--edges] [--cache <cache-file>] [^]<commit> [[^]<commit>] 830 831Provides the revision tree for one or more commits. 832 833--edges 834 Show edges (ie places where the marking changes between parent 835 and child) 836 837--cache <cache-file> 838 Use the specified file as a cache from a previous git-rev-list run 839 to speed things up. Note that this "cache" is totally different 840 concept from the directory index. Also this option is not 841 implemented yet. 842 843[^]<commit> 844 The commit id to trace (a leading caret means to ignore this 845 commit-id and below) 846 847Output: 848<date> <commit>:<flags> [<parent-commit>:<flags> ]* 849 850<date> 851 Date in 'seconds since epoch' 852 853<commit> 854 id of commit object 855 856<parent-commit> 857 id of each parent commit object (>1 indicates a merge) 858 859<flags> 860 861 The flags are read as a bitmask representing each commit 862 provided on the commandline. eg: given the command: 863 864 $ git-rev-tree <com1> <com2> <com3> 865 866 The output: 867 868 <date> <commit>:5 869 870 means that <commit> is reachable from <com1>(1) and <com3>(4) 871 872A revtree can get quite large. git-rev-tree will eventually allow you to 873cache previous state so that you don't have to follow the whole thing 874down. 875 876So the change difference between two commits is literally 877 878 git-rev-tree [commit-id1] > commit1-revtree 879 git-rev-tree [commit-id2] > commit2-revtree 880 join -t : commit1-revtree commit2-revtree > common-revisions 881 882(this is also how to find the most common parent - you'd look at just 883the head revisions - the ones that aren't referred to by other 884revisions - in "common-revision", and figure out the best one. I 885think.) 886 887 888################################################################ 889git-rpull 890 891Pulls from a remote repository over ssh connection, invoking git-rpush on 892the other end. 893 894 895################################################################ 896git-rpush 897 898Helper "server-side" program used by git-rpull. 899 900 901################################################################ 902git-diff-files 903 git-diff-files [-p] [-q] [-r] [-z] [<pattern>...] 904 905Compares the files in the working tree and the cache. When paths 906are specified, compares only those named paths. Otherwise all 907entries in the cache are compared. The output format is the 908same as git-diff-cache and git-diff-tree. 909 910-p 911 generate patch (see section on generating patches). 912 913-q 914 Remain silent even on nonexisting files 915 916-r 917 This flag does not mean anything. It is there only to match 918 git-diff-tree. Unlike git-diff-tree, git-diff-files always looks 919 at all the subdirectories. 920 921 922Output format: 923 924See "Output format from git-diff-cache, git-diff-tree and git-diff-files" 925section. 926 927 928################################################################ 929git-tag-script 930 931This is an example script that uses git-mktag to create a tag object 932signed with GPG. 933 934 935################################################################ 936git-tar-tree 937 938 git-tar-tree <tree-ish> [ <base> ] 939 940Creates a tar archive containing the tree structure for the named tree. 941When <base> is specified it is added as a leading path as the files in the 942generated tar archive. 943 944 945################################################################ 946git-ls-files 947 git-ls-files [-z] [-t] 948 (--[cached|deleted|others|ignored|stage|unmerged])* 949 (-[c|d|o|i|s|u])* 950 [-x <pattern>|--exclude=<pattern>] 951 [-X <file>|--exclude-from=<file>] 952 953This merges the file listing in the directory cache index with the 954actual working directory list, and shows different combinations of the 955two. 956 957One or more of the options below may be used to determine the files 958shown: 959 960-c|--cached 961 Show cached files in the output (default) 962 963-d|--deleted 964 Show deleted files in the output 965 966-o|--others 967 Show other files in the output 968 969-i|--ignored 970 Show ignored files in the output 971 Note the this also reverses any exclude list present. 972 973-s|--stage 974 Show stage files in the output 975 976-u|--unmerged 977 Show unmerged files in the output (forces --stage) 978 979-z 980 \0 line termination on output 981 982-x|--exclude=<pattern> 983 Skips files matching pattern. 984 Note that pattern is a shell wildcard pattern. 985 986-X|--exclude-from=<file> 987 exclude patterns are read from <file>; 1 per line. 988 Allows the use of the famous dontdiff file as follows to find 989 out about uncommitted files just as dontdiff is used with 990 the diff command: 991 git-ls-files --others --exclude-from=dontdiff 992 993Output 994show files just outputs the filename unless --stage is specified in 995which case it outputs: 996 997[<tag> ]<mode> <object> <stage> <file> 998 999git-ls-files --unmerged" and "git-ls-files --stage " can be used to examine1000detailed information on unmerged paths.10011002For an unmerged path, instead of recording a single mode/SHA1 pair,1003the dircache records up to three such pairs; one from tree O in stage10041, A in stage 2, and B in stage 3. This information can be used by1005the user (or Cogito) to see what should eventually be recorded at the1006path. (see read-cache for more information on state)10071008see also:1009read-cache101010111012################################################################1013git-unpack-file1014 git-unpack-file <blob>10151016Creates a file holding the contents of the blob specified by sha1. It1017returns the name of the temporary file in the following format:1018 .merge_file_XXXXX10191020<blob>1021 Must be a blob id10221023################################################################1024git-update-cache1025 git-update-cache1026 [--add] [--remove] [--refresh]1027 [--ignore-missing]1028 [--force-remove <file>]1029 [--cacheinfo <mode> <object> <file>]*1030 [--] [<file>]*10311032Modifies the index or directory cache. Each file mentioned is updated1033into the cache and any 'unmerged' or 'needs updating' state is1034cleared.10351036The way git-update-cache handles files it is told about can be modified1037using the various options:10381039--add1040 If a specified file isn't in the cache already then it's1041 added.1042 Default behaviour is to ignore new files.10431044--remove1045 If a specified file is in the cache but is missing then it's1046 removed.1047 Default behaviour is to ignore removed file.10481049--refresh1050 Looks at the current cache and checks to see if merges or1051 updates are needed by checking stat() information.10521053--ignore-missing1054 Ignores missing files during a --refresh10551056--cacheinfo <mode> <object> <path>1057 Directly insert the specified info into the cache.10581059--force-remove1060 Remove the file from the index even when the working directory1061 still has such a file.10621063--1064 Do not interpret any more arguments as options.10651066<file>1067 Files to act on.1068 Note that files begining with '.' are discarded. This includes1069 "./file" and "dir/./file". If you don't want this, then use 1070 cleaner names.1071 The same applies to directories ending '/' and paths with '//'10721073Using --refresh1074--refresh does not calculate a new sha1 file or bring the cache1075up-to-date for mode/content changes. But what it _does_ do is to1076"re-match" the stat information of a file with the cache, so that you1077can refresh the cache for a file that hasn't been changed but where1078the stat entry is out of date.10791080For example, you'd want to do this after doing a "git-read-tree", to link1081up the stat cache details with the proper files.10821083Using --cacheinfo1084--cacheinfo is used to register a file that is not in the current1085working directory. This is useful for minimum-checkout merging.10861087To pretend you have a file with mode and sha1 at path, say:10881089 $ git-update-cache --cacheinfo mode sha1 path10901091To update and refresh only the files already checked out:10921093 git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh109410951096################################################################1097git-write-blob10981099 git-write-blob <any-file-on-the-filesystem>11001101Writes the contents of the named file (which can be outside of the work1102tree) as a blob into the object database, and reports its object ID to its1103standard output. This is used by git-merge-one-file-script to update the1104cache without modifying files in the work tree.110511061107################################################################1108git-write-tree1109 git-write-tree11101111Creates a tree object using the current cache.11121113The cache must be merged.11141115Conceptually, git-write-tree sync()s the current directory cache contents1116into a set of tree files.1117In order to have that match what is actually in your directory right1118now, you need to have done a "git-update-cache" phase before you did the1119"git-write-tree".112011211122################################################################11231124Output format from git-diff-cache, git-diff-tree and git-diff-files.11251126These commands all compare two sets of things; what are1127compared are different:11281129 git-diff-cache <tree-ish>11301131 compares the <tree-ish> and the files on the filesystem.11321133 git-diff-cache --cached <tree-ish>11341135 compares the <tree-ish> and the cache.11361137 git-diff-tree [-r] <tree-ish-1> <tree-ish-2> [<pattern>...]11381139 compares the trees named by the two arguments.11401141 git-diff-files [<pattern>...]11421143 compares the cache and the files on the filesystem.11441145The following desription uses "old" and "new" to mean those1146compared entities.11471148For files in old but not in new (i.e. removed):1149-<mode> \t <type> \t <object> \t <path>11501151For files not in old but in new (i.e. added):1152+<mode> \t <type> \t <object> \t <path>11531154For files that differ:1155*<old-mode>-><new-mode> \t <type> \t <old-sha1>-><new-sha1> \t <path>11561157<new-sha1> is shown as all 0's if new is a file on the1158filesystem and it is out of sync with the cache. Example:11591160 *100644->100644 blob 5be4a4.......->000000....... file.c11611162################################################################11631164Generating patches11651166When git-diff-cache, git-diff-tree, or git-diff-files are run with a -p1167option, they do not produce the output described in "Output format from1168git-diff-cache, git-diff-tree and git-diff-files" section. It instead1169produces a patch file.11701171The patch generation can be customized at two levels. This1172customization also applies to git-diff-tree-helper.117311741. When the environment variable GIT_EXTERNAL_DIFF is not set,1175 these commands internally invoke diff like this:11761177 diff -L a/<path> -L a/<path> -pu <old> <new>11781179 For added files, /dev/null is used for <old>. For removed1180 files, /dev/null is used for <new>11811182 The diff formatting options can be customized via the1183 environment variable GIT_DIFF_OPTS. For example, if you1184 prefer context diff:11851186 GIT_DIFF_OPTS=-c git-diff-cache -p $(cat .git/HEAD)1187118811892. When the environment variable GIT_EXTERNAL_DIFF is set, the1190 program named by it is called, instead of the diff invocation1191 described above.11921193 For a path that is added, removed, or modified,1194 GIT_EXTERNAL_DIFF is called with 7 parameters:11951196 path old-file old-hex old-mode new-file new-hex new-mode11971198 where1199 <old|new>-file are files GIT_EXTERNAL_DIFF can use to read the1200 contents of <old|ne>,1201 <old|new>-hex are the 40-hexdigit SHA1 hashes,1202 <old|new>-mode are the octal representation of the file modes.12031204 The file parameters can point at the user's working file (e.g. new-file1205 in git-diff-files), /dev/null (e.g. old-file when a new file is added),1206 or a temporary file (e.g. old-file in the cache). GIT_EXTERNAL_DIFF1207 should not worry about unlinking the temporary file --- it is removed1208 when GIT_EXTERNAL_DIFF exits.12091210 For a path that is unmerged, GIT_EXTERNAL_DIFF is called with1211 1 parameter, path.12121213################################################################12141215Terminology: - see README for description1216Each line contains terms used interchangeably12171218object database, .git directory1219directory cache, index1220id, sha1, sha1-id, sha1 hash1221type, tag1222blob, blob object1223tree, tree object1224commit, commit object1225parent1226root object1227changeset122812291230git Environment Variables1231AUTHOR_NAME1232AUTHOR_EMAIL1233AUTHOR_DATE1234COMMIT_AUTHOR_NAME1235COMMIT_AUTHOR_EMAIL1236GIT_DIFF_OPTS1237GIT_EXTERNAL_DIFF1238GIT_INDEX_FILE1239SHA1_FILE_DIRECTORY