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- 'AUTHOR_NAME' 214- 'AUTHOR_EMAIL' 215- 'AUTHOR_DATE' 216- 'COMMIT_AUTHOR_NAME' 217- 'COMMIT_AUTHOR_EMAIL' 218- 'GIT_DIFF_OPTS' 219- 'GIT_EXTERNAL_DIFF' 220- 'GIT_INDEX_FILE' 221- 'SHA1_FILE_DIRECTORY' 222 223 224NAME 225---- 226git-apply-patch-script - Sample script to apply the diffs from git-diff-* 227 228SYNOPSIS 229-------- 230'git-apply-patch-script' 231 232DESCRIPTION 233----------- 234This is a sample script to be used via the 'GIT_EXTERNAL_DIFF' 235environment variable to apply the differences that the "git-diff-*" 236family of commands report to the current work tree. 237 238 239NAME 240---- 241git-cat-file - Provide content or type information for repository objects 242 243SYNOPSIS 244-------- 245'git-cat-file' (-t | <type>) <object> 246 247DESCRIPTION 248----------- 249Provides content or type of objects in the repository. The type 250is required if '-t' is not being used to find the object type. 251 252OPTIONS 253------- 254<object>:: 255 The sha1 identifier of the object. 256 257-t:: 258 Instead of the content, show the object type identified by 259 <object>. 260 261<type>:: 262 Typically this matches the real type of <object> but asking 263 for a type that can trivially dereferenced from the given 264 <object> is also permitted. An example is to ask for a 265 "tree" with <object> being a commit object that contains it, 266 or to ask for a "blob" with <object> being a tag object that 267 points at it. 268 269OUTPUT 270------ 271If '-t' is specified, one of the <type>. 272 273Otherwise the raw (though uncompressed) contents of the <object> will 274be returned. 275 276 277NAME 278---- 279git-check-files - Verify a list of files are up-to-date 280 281 282SYNOPSIS 283-------- 284'git-check-files' <file>... 285 286DESCRIPTION 287----------- 288Check that a list of files are up-to-date between the filesystem and 289the cache. Used to verify a patch target before doing a patch. 290 291Files that do not exist on the filesystem are considered up-to-date 292(whether or not they are in the cache). 293 294Emits an error message on failure: 295 296preparing to update existing file <file> not in cache:: 297 <file> exists but is not in the cache 298 299preparing to update file <file> not uptodate in cache:: 300 <file> on disk is not up-to-date with the cache 301 302Exits with a status code indicating success if all files are 303up-to-date. 304 305see also: link:git-update-cache.html[git-update-cache] 306 307 308NAME 309---- 310git-checkout-cache - Copy files from the cache to the working directory 311 312SYNOPSIS 313-------- 314'git-checkout-cache' [-q] [-a] [-f] [-n] [--prefix=<string>] 315 [--] <file>... 316 317DESCRIPTION 318----------- 319Will copy all files listed from the cache to the working directory 320(not overwriting existing files). 321 322OPTIONS 323------- 324-q:: 325 be quiet if files exist or are not in the cache 326 327-f:: 328 forces overwrite of existing files 329 330-a:: 331 checks out all files in the cache (will then continue to 332 process listed files). 333 334-n:: 335 Don't checkout new files, only refresh files already checked 336 out. 337 338--prefix=<string>:: 339 When creating files, prepend <string> (usually a directory 340 including a trailing /) 341 342--:: 343 Do not interpret any more arguments as options. 344 345Note that the order of the flags matters: 346 347 git-checkout-cache -a -f file.c 348 349will first check out all files listed in the cache (but not overwrite 350any old ones), and then force-checkout `file.c` a second time (ie that 351one *will* overwrite any old contents with the same filename). 352 353Also, just doing "git-checkout-cache" does nothing. You probably meant 354"git-checkout-cache -a". And if you want to force it, you want 355"git-checkout-cache -f -a". 356 357Intuitiveness is not the goal here. Repeatability is. The reason for 358the "no arguments means no work" thing is that from scripts you are 359supposed to be able to do things like: 360 361 find . -name '*.h' -print0 | xargs -0 git-checkout-cache -f -- 362 363which will force all existing `*.h` files to be replaced with their 364cached copies. If an empty command line implied "all", then this would 365force-refresh everything in the cache, which was not the point. 366 367To update and refresh only the files already checked out: 368 369 git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh 370 371Oh, and the "--" is just a good idea when you know the rest will be 372filenames. Just so that you wouldn't have a filename of "-a" causing 373problems (not possible in the above example, but get used to it in 374scripting!). 375 376The prefix ability basically makes it trivial to use 377git-checkout-cache as an "export as tree" function. Just read the 378desired tree into the index, and do a 379 380 git-checkout-cache --prefix=git-export-dir/ -a 381 382and git-checkout-cache will "export" the cache into the specified 383directory. 384 385NOTE The final "/" is important. The exported name is literally just 386prefixed with the specified string, so you can also do something like 387 388 git-checkout-cache --prefix=.merged- Makefile 389 390to check out the currently cached copy of `Makefile` into the file 391`.merged-Makefile` 392 393NAME 394---- 395git-commit-tree - Creates a new commit object 396 397SYNOPSIS 398-------- 399'git-commit-tree' <tree> [-p <parent commit>]\ < changelog 400 401DESCRIPTION 402----------- 403Creates a new commit object based on the provided tree object and 404emits the new commit object id on stdout. If no parent is given then 405it is considered to be an initial tree. 406 407A commit object usually has 1 parent (a commit after a change) or up 408to 16 parents. More than one parent represents a merge of branches 409that led to them. 410 411While a tree represents a particular directory state of a working 412directory, a commit represents that state in "time", and explains how 413to get there. 414 415Normally a commit would identify a new "HEAD" state, and while git 416doesn't care where you save the note about that state, in practice we 417tend to just write the result to the file `.git/HEAD`, so that we can 418always see what the last committed state was. 419 420OPTIONS 421------- 422<tree>:: 423 An existing tree object 424 425-p <parent commit>:: 426 Each '-p' indicates a the id of a parent commit object. 427 428 429Commit Information 430------------------ 431 432A commit encapsulates: 433 434- all parent object ids 435- author name, email and date 436- committer name and email and the commit time. 437 438If not provided, "git-commit-tree" uses your name, hostname and domain to 439provide author and committer info. This can be overridden using the 440following environment variables. 441 442 AUTHOR_NAME 443 AUTHOR_EMAIL 444 AUTHOR_DATE 445 COMMIT_AUTHOR_NAME 446 COMMIT_AUTHOR_EMAIL 447 448(nb <,> and '\n's are stripped) 449 450A commit comment is read from stdin (max 999 chars). If a changelog 451entry is not provided via '<' redirection, "git-commit-tree" will just wait 452for one to be entered and terminated with ^D 453 454see also: link:git-write-tree.html[git-write-tree] 455 456 457NAME 458---- 459git-convert-cache - Converts old-style GIT repository 460 461SYNOPSIS 462-------- 463'git-convert-cache' 464 465DESCRIPTION 466----------- 467Converts old-style GIT repository to the latest format 468 469 470NAME 471---- 472git-diff-cache - Compares content and mode of blobs between the cache and repository 473 474SYNOPSIS 475-------- 476'git-diff-cache' [-p] [-r] [-z] [-m] [--cached] <tree-ish> 477 478DESCRIPTION 479----------- 480Compares the content and mode of the blobs found via a tree object 481with the content of the current cache and, optionally ignoring the 482stat state of the file on disk. 483 484OPTIONS 485------- 486<tree-ish>:: 487 The id of a tree object to diff against. 488 489-p:: 490 Generate patch (see section on generating patches) 491 492-r:: 493 This flag does not mean anything. It is there only to match 494 "git-diff-tree". Unlike "git-diff-tree", "git-diff-cache" 495 always looks at all the subdirectories. 496 497-z:: 498 \0 line termination on output 499 500--cached:: 501 do not consider the on-disk file at all 502 503-m:: 504 By default, files recorded in the index but not checked 505 out are reported as deleted. This flag makes 506 "git-diff-cache" say that all non-checked-out files are up 507 to date. 508 509Output format 510------------- 511include::diff-format.txt[] 512 513Operating Modes 514--------------- 515You can choose whether you want to trust the index file entirely 516(using the '--cached' flag) or ask the diff logic to show any files 517that don't match the stat state as being "tentatively changed". Both 518of these operations are very useful indeed. 519 520Cached Mode 521----------- 522If '--cached' is specified, it allows you to ask: 523 524 show me the differences between HEAD and the current index 525 contents (the ones I'd write with a "git-write-tree") 526 527For example, let's say that you have worked on your index file, and are 528ready to commit. You want to see eactly *what* you are going to commit is 529without having to write a new tree object and compare it that way, and to 530do that, you just do 531 532 git-diff-cache --cached $(cat .git/HEAD) 533 534Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had 535done an "git-update-cache" to make that effective in the index file. 536"git-diff-files" wouldn't show anything at all, since the index file 537matches my working directory. But doing a "git-diff-cache" does: 538 539 torvalds@ppc970:~/git> git-diff-cache --cached $(cat .git/HEAD) 540 -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c 541 +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c 542 543You can trivially see that the above is a rename. 544 545In fact, "git-diff-cache --cached" *should* always be entirely equivalent to 546actually doing a "git-write-tree" and comparing that. Except this one is much 547nicer for the case where you just want to check where you are. 548 549So doing a "git-diff-cache --cached" is basically very useful when you are 550asking yourself "what have I already marked for being committed, and 551what's the difference to a previous tree". 552 553Non-cached Mode 554--------------- 555The "non-cached" mode takes a different approach, and is potentially 556the more useful of the two in that what it does can't be emulated with 557a "git-write-tree" + "git-diff-tree". Thus that's the default mode. 558The non-cached version asks the question: 559 560 show me the differences between HEAD and the currently checked out 561 tree - index contents _and_ files that aren't up-to-date 562 563which is obviously a very useful question too, since that tells you what 564you *could* commit. Again, the output matches the "git-diff-tree -r" 565output to a tee, but with a twist. 566 567The twist is that if some file doesn't match the cache, we don't have 568a backing store thing for it, and we use the magic "all-zero" sha1 to 569show that. So let's say that you have edited `kernel/sched.c`, but 570have not actually done a "git-update-cache" on it yet - there is no 571"object" associated with the new state, and you get: 572 573 torvalds@ppc970:~/v2.6/linux> git-diff-cache $(cat .git/HEAD ) 574 *100644->100664 blob 7476bb......->000000...... kernel/sched.c 575 576ie it shows that the tree has changed, and that `kernel/sched.c` has is 577not up-to-date and may contain new stuff. The all-zero sha1 means that to 578get the real diff, you need to look at the object in the working directory 579directly rather than do an object-to-object diff. 580 581NOTE! As with other commands of this type, "git-diff-cache" does not 582actually look at the contents of the file at all. So maybe 583`kernel/sched.c` hasn't actually changed, and it's just that you 584touched it. In either case, it's a note that you need to 585"git-upate-cache" it to make the cache be in sync. 586 587NOTE 2! You can have a mixture of files show up as "has been updated" 588and "is still dirty in the working directory" together. You can always 589tell which file is in which state, since the "has been updated" ones 590show a valid sha1, and the "not in sync with the index" ones will 591always have the special all-zero sha1. 592 593 594NAME 595---- 596git-diff-files - Compares files in the working tree and the cache 597 598SYNOPSIS 599-------- 600'git-diff-files' [-p] [-q] [-r] [-z] [<pattern>...] 601 602DESCRIPTION 603----------- 604Compares the files in the working tree and the cache. When paths 605are specified, compares only those named paths. Otherwise all 606entries in the cache are compared. The output format is the 607same as "git-diff-cache" and "git-diff-tree". 608 609OPTIONS 610------- 611-p:: 612 generate patch (see section on generating patches). 613 614-q:: 615 Remain silent even on nonexisting files 616 617-r:: 618 This flag does not mean anything. It is there only to match 619 git-diff-tree. Unlike git-diff-tree, git-diff-files always looks 620 at all the subdirectories. 621 622 623Output format 624------------- 625include::diff-format.txt[] 626 627 628NAME 629---- 630git-diff-tree - Compares the content and mode of blobs found via two tree objects 631 632SYNOPSIS 633-------- 634'git-diff-tree' [-p] [-r] [-z] [--stdin] [-m] [-s] [-v] <tree-ish> <tree-ish> [<pattern>]\* 635 636DESCRIPTION 637----------- 638Compares the content and mode of the blobs found via two tree objects. 639 640Note that "git-diff-tree" can use the tree encapsulated in a commit object. 641 642OPTIONS 643------- 644<tree-ish>:: 645 The id of a tree object. 646 647<pattern>:: 648 If provided, the results are limited to a subset of files 649 matching one of these prefix strings. 650 ie file matches `/^<pattern1>|<pattern2>|.../` 651 Note that pattern does not provide any wildcard or regexp 652 features. 653 654-p:: 655 generate patch (see section on generating patches). For 656 git-diff-tree, this flag implies '-r' as well. 657 658-r:: 659 recurse 660 661-z:: 662 \0 line termination on output 663 664--stdin:: 665 When '--stdin' is specified, the command does not take 666 <tree-ish> arguments from the command line. Instead, it 667 reads either one <commit> or a pair of <tree-ish> 668 separated with a single space from its standard input. 669+ 670When a single commit is given on one line of such input, it compares 671the commit with its parents. The following flags further affects its 672behaviour. This does not apply to the case where two <tree-ish> 673separated with a single space are given. 674 675-m:: 676 By default, "git-diff-tree --stdin" does not show 677 differences for merge commits. With this flag, it shows 678 differences to that commit from all of its parents. 679 680-s:: 681 By default, "git-diff-tree --stdin" shows differences, 682 either in machine-readable form (without '-p') or in patch 683 form (with '-p'). This output can be supressed. It is 684 only useful with '-v' flag. 685 686-v:: 687 This flag causes "git-diff-tree --stdin" to also show 688 the commit message before the differences. 689 690 691Limiting Output 692--------------- 693If you're only interested in differences in a subset of files, for 694example some architecture-specific files, you might do: 695 696 git-diff-tree -r <tree-ish> <tree-ish> arch/ia64 include/asm-ia64 697 698and it will only show you what changed in those two directories. 699 700Or if you are searching for what changed in just `kernel/sched.c`, just do 701 702 git-diff-tree -r <tree-ish> <tree-ish> kernel/sched.c 703 704and it will ignore all differences to other files. 705 706The pattern is always the prefix, and is matched exactly. There are no 707wildcards. Even stricter, it has to match complete path comonent. 708I.e. "foo" does not pick up `foobar.h`. "foo" does match `foo/bar.h` 709so it can be used to name subdirectories. 710 711An example of normal usage is: 712 713 torvalds@ppc970:~/git> git-diff-tree 5319e4...... 714 *100664->100664 blob ac348b.......->a01513....... git-fsck-cache.c 715 716which tells you that the last commit changed just one file (it's from 717this one: 718 719 commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8 720 tree 5319e4d609cdd282069cc4dce33c1db559539b03 721 parent b4e628ea30d5ab3606119d2ea5caeab141d38df7 722 author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005 723 committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005 724 725 Make "git-fsck-cache" print out all the root commits it finds. 726 727 Once I do the reference tracking, I'll also make it print out all the 728 HEAD commits it finds, which is even more interesting. 729 730in case you care). 731 732Output format 733------------- 734include::diff-format.txt[] 735 736 737NAME 738---- 739git-diff-tree-helper - Generates patch format output for git-diff-* 740 741SYNOPSIS 742-------- 743'git-diff-tree-helper' [-z] [-R] 744 745DESCRIPTION 746----------- 747Reads output from "git-diff-cache", "git-diff-tree" and "git-diff-files" and 748generates patch format output. 749 750OPTIONS 751------- 752-z:: 753 \0 line termination on input 754 755-R:: 756 Output diff in reverse. This is useful for displaying output from 757 "git-diff-cache" which always compares tree with cache or working 758 file. E.g. 759 760 git-diff-cache <tree> | git-diff-tree-helper -R file.c 761+ 762would show a diff to bring the working file back to what is in the <tree>. 763 764See also the section on generating patches in link:git-diff-cache.html[git-diff-cache] 765 766 767NAME 768---- 769git-export - Exports each commit and a diff against each of its parents 770 771SYNOPSIS 772-------- 773'git-export' top [base] 774 775DESCRIPTION 776----------- 777Exports each commit and diff against each of its parents, between 778top and base. If base is not specified it exports everything. 779 780 781NAME 782---- 783git-fsck-cache - Verifies the connectivity and validity of the objects in the database 784 785SYNOPSIS 786-------- 787'git-fsck-cache' [--tags] [--root] [[--unreachable] [--cache] <object>\*] 788 789DESCRIPTION 790----------- 791Verifies the connectivity and validity of the objects in the database. 792 793OPTIONS 794------- 795<object>:: 796 An object to treat as the head of an unreachability trace. 797 798--unreachable:: 799 Print out objects that exist but that aren't readable from any 800 of the specified head nodes. 801 802--root:: 803 Report root nodes. 804 805--tags:: 806 Report tags. 807 808--cache:: 809 Consider any object recorded in the cache also as a head node for 810 an unreachability trace. 811 812It tests SHA1 and general object sanity, and it does full tracking of 813the resulting reachability and everything else. It prints out any 814corruption it finds (missing or bad objects), and if you use the 815'--unreachable' flag it will also print out objects that exist but 816that aren't readable from any of the specified head nodes. 817 818So for example 819 820 git-fsck-cache --unreachable $(cat .git/HEAD) 821 822or, for Cogito users: 823 824 git-fsck-cache --unreachable $(cat .git/refs/heads/*) 825 826will do quite a _lot_ of verification on the tree. There are a few 827extra validity tests to be added (make sure that tree objects are 828sorted properly etc), but on the whole if "git-fsck-cache" is happy, you 829do have a valid tree. 830 831Any corrupt objects you will have to find in backups or other archives 832(ie you can just remove them and do an "rsync" with some other site in 833the hopes that somebody else has the object you have corrupted). 834 835Of course, "valid tree" doesn't mean that it wasn't generated by some 836evil person, and the end result might be crap. Git is a revision 837tracking system, not a quality assurance system ;) 838 839Extracted Diagnostics 840--------------------- 841 842expect dangling commits - potential heads - due to lack of head information:: 843 You haven't specified any nodes as heads so it won't be 844 possible to differentiate between un-parented commits and 845 root nodes. 846 847missing sha1 directory '<dir>':: 848 The directory holding the sha1 objects is missing. 849 850unreachable <type> <object>:: 851 The <type> object <object>, isn't actually referred to directly 852 or indirectly in any of the trees or commits seen. This can 853 mean that there's another root node that you're not specifying 854 or that the tree is corrupt. If you haven't missed a root node 855 then you might as well delete unreachable nodes since they 856 can't be used. 857 858missing <type> <object>:: 859 The <type> object <object>, is referred to but isn't present in 860 the database. 861 862dangling <type> <object>:: 863 The <type> object <object>, is present in the database but never 864 'directly' used. A dangling commit could be a root node. 865 866warning: git-fsck-cache: tree <tree> has full pathnames in it:: 867 And it shouldn't... 868 869sha1 mismatch <object>:: 870 The database has an object who's sha1 doesn't match the 871 database value. 872 This indicates a serious data integrity problem. 873 (note: this error occured during early git development when 874 the database format changed.) 875 876Environment Variables 877--------------------- 878 879SHA1_FILE_DIRECTORY:: 880 used to specify the object database root (usually .git/objects) 881 882GIT_INDEX_FILE:: 883 used to specify the cache 884 885 886NAME 887---- 888git-http-pull - Downloads a remote GIT repository via HTTP 889 890SYNOPSIS 891-------- 892'git-http-pull' [-c] [-t] [-a] [-v] commit-id url 893 894DESCRIPTION 895----------- 896Downloads a remote GIT repository via HTTP. 897 898-c:: 899 Get the commit objects. 900-t:: 901 Get trees associated with the commit objects. 902-a:: 903 Get all the objects. 904-v:: 905 Report what is downloaded. 906 907 908NAME 909---- 910git-init-db - Creates an empty git object database 911 912SYNOPSIS 913-------- 914'git-init-db' 915 916DESCRIPTION 917----------- 918This simply creates an empty git object database - basically a `.git` 919directory and `.git/object/??/` directories. 920 921If the object storage directory is specified via the 'SHA1_FILE_DIRECTORY' 922environment variable then the sha1 directories are created underneath - 923otherwise the default `.git/objects` directory is used. 924 925"git-init-db" won't hurt an existing repository. 926 927 928NAME 929---- 930git-local-pull - Duplicates another GIT repository on a local system 931 932SYNOPSIS 933-------- 934'git-local-pull' [-c] [-t] [-a] [-l] [-s] [-n] [-v] commit-id path 935 936DESCRIPTION 937----------- 938Duplicates another GIT repository on a local system. 939 940OPTIONS 941------- 942-c:: 943 Get the commit objects. 944-t:: 945 Get trees associated with the commit objects. 946-a:: 947 Get all the objects. 948-v:: 949 Report what is downloaded. 950 951NAME 952---- 953git-ls-files - Information about files in the cache/working directory 954 955SYNOPSIS 956-------- 957'git-ls-files' [-z] [-t] 958 (--[cached|deleted|others|ignored|stage|unmerged])\* 959 (-[c|d|o|i|s|u])\* 960 [-x <pattern>|--exclude=<pattern>] 961 [-X <file>|--exclude-from=<file>] 962 963DESCRIPTION 964----------- 965This merges the file listing in the directory cache index with the 966actual working directory list, and shows different combinations of the 967two. 968 969One or more of the options below may be used to determine the files 970shown: 971 972OPTIONS 973------- 974-c|--cached:: 975 Show cached files in the output (default) 976 977-d|--deleted:: 978 Show deleted files in the output 979 980-o|--others:: 981 Show other files in the output 982 983-i|--ignored:: 984 Show ignored files in the output 985 Note the this also reverses any exclude list present. 986 987-s|--stage:: 988 Show stage files in the output 989 990-u|--unmerged:: 991 Show unmerged files in the output (forces --stage) 992 993-z:: 994 \0 line termination on output 995 996-x|--exclude=<pattern>:: 997 Skips files matching pattern. 998 Note that pattern is a shell wildcard pattern. 9991000-X|--exclude-from=<file>::1001 exclude patterns are read from <file>; 1 per line.1002 Allows the use of the famous dontdiff file as follows to find1003 out about uncommitted files just as dontdiff is used with1004 the diff command:1005 git-ls-files --others --exclude-from=dontdiff10061007-t::1008 Identify the file status with the following tags (followed by1009 a space) at the start of each line:1010 H cached1011 M unmerged1012 R removed/deleted1013 ? other10141015Output1016------1017show files just outputs the filename unless '--stage' is specified in1018which case it outputs:10191020 [<tag> ]<mode> <object> <stage> <file>10211022"git-ls-files --unmerged" and "git-ls-files --stage" can be used to examine1023detailed information on unmerged paths.10241025For an unmerged path, instead of recording a single mode/SHA1 pair,1026the dircache records up to three such pairs; one from tree O in stage10271, A in stage 2, and B in stage 3. This information can be used by1028the user (or Cogito) to see what should eventually be recorded at the1029path. (see read-cache for more information on state)10301031see also: link:read-cache.html[read-cache]103210331034NAME1035----1036git-ls-tree - Displays a tree object in human readable form10371038SYNOPSIS1039--------1040'git-ls-tree' [-r] [-z] <tree-ish>10411042DESCRIPTION1043-----------1044Converts the tree object to a human readable (and script processable)1045form.10461047OPTIONS1048-------1049<tree-ish>::1050 Id of a tree.10511052-r::1053 recurse into sub-trees10541055-z::1056 \0 line termination on output10571058Output Format1059-------------1060 <mode>\t <type>\t <object>\t <file>106110621063NAME1064----1065git-merge-base - Finds as good a common ancestor as possible for a merge10661067SYNOPSIS1068--------1069'git-merge-base' <commit> <commit>10701071DESCRIPTION1072-----------1073"git-merge-base" finds as good a common ancestor as possible. Given a1074selection of equally good common ancestors it should not be relied on1075to decide in any particular way.10761077The "git-merge-base" algorithm is still in flux - use the source...107810791080NAME1081----1082git-merge-cache - Runs a merge for files needing merging10831084SYNOPSIS1085--------1086'git-merge-cache' <merge-program> (-a | -- | <file>\*) 10871088DESCRIPTION1089-----------1090This looks up the <file>(s) in the cache and, if there are any merge1091entries, passes the SHA1 hash for those files as arguments 1, 2, 3 (empty1092argument if no file), and <file> as argument 4. File modes for the three1093files are passed as arguments 5, 6 and 7.10941095OPTIONS1096-------1097--::1098 Interpret all future arguments as filenames.10991100-a::1101 Run merge against all files in the cache that need merging.11021103If "git-merge-cache" is called with multiple <file>s (or -a) then it1104processes them in turn only stopping if merge returns a non-zero exit1105code.11061107Typically this is run with the a script calling the merge command from1108the RCS package.11091110A sample script called "git-merge-one-file-script" is included in the1111ditribution.11121113ALERT ALERT ALERT! The git "merge object order" is different from the1114RCS "merge" program merge object order. In the above ordering, the1115original is first. But the argument order to the 3-way merge program1116"merge" is to have the original in the middle. Don't ask me why.11171118Examples:11191120 torvalds@ppc970:~/merge-test> git-merge-cache cat MM1121 This is MM from the original tree. # original1122 This is modified MM in the branch A. # merge11123 This is modified MM in the branch B. # merge21124 This is modified MM in the branch B. # current contents11251126or 11271128 torvalds@ppc970:~/merge-test> git-merge-cache cat AA MM1129 cat: : No such file or directory1130 This is added AA in the branch A.1131 This is added AA in the branch B.1132 This is added AA in the branch B.1133 fatal: merge program failed11341135where the latter example shows how "git-merge-cache" will stop trying to1136merge once anything has returned an error (ie "cat" returned an error1137for the AA file, because it didn't exist in the original, and thus1138"git-merge-cache" didn't even try to merge the MM thing).11391140NAME1141----1142git-merge-one-file-script - The standard helper program to use with "git-merge-cache"11431144SYNOPSIS1145--------1146'git-merge-one-file-script'11471148DESCRIPTION1149-----------1150This is the standard helper program to use with "git-merge-cache"1151to resolve a merge after the trivial merge done with "git-read-tree -m".11521153NAME1154----1155git-mktag - Creates a tag object11561157SYNOPSIS1158--------1159'git-mktag'11601161DESCRIPTION1162-----------1163Reads a tag contents from its standard input and creates a tag object.1164The input must be a well formed tag object.116511661167NAME1168----1169git-prune-script - Prunes all unreachable objects from the object database11701171SYNOPSIS1172--------1173'git-prune-script'11741175DESCRIPTION1176-----------1177This runs "git-fsck-cache --unreachable" program using the heads specified1178on the command line (or `.git/refs/heads/\*` and `.git/refs/tags/\*` if none is1179specified), and prunes all unreachable objects from the object database.118011811182NAME1183----1184git-pull-script - Script used by Linus to pull and merge a remote repository11851186SYNOPSIS1187--------1188'git-pull-script'11891190DESCRIPTION1191-----------1192This script is used by Linus to pull from a remote repository and perform1193a merge.119411951196NAME1197----1198git-read-tree - Reads tree information into the directory cache11991200SYNOPSIS1201--------1202'git-read-tree' (<tree-ish> | -m <tree-ish1> [<tree-ish2> <tree-ish3>])"12031204DESCRIPTION1205-----------1206Reads the tree information given by <tree> into the directory cache,1207but does not actually _update_ any of the files it "caches". (see:1208git-checkout-cache)12091210Optionally, it can merge a tree into the cache or perform a 3-way1211merge.12121213Trivial merges are done by "git-read-tree" itself. Only conflicting paths1214will be in unmerged state when "git-read-tree" returns.12151216OPTIONS1217-------1218-m::1219 Perform a merge, not just a read12201221<tree-ish#>::1222 The id of the tree object(s) to be read/merged.122312241225Merging1226-------1227If '-m' is specified, "git-read-tree" performs 2 kinds of merge, a single tree1228merge if only 1 tree is given or a 3-way merge if 3 trees are1229provided.12301231Single Tree Merge1232~~~~~~~~~~~~~~~~~1233If only 1 tree is specified, git-read-tree operates as if the user did not1234specify '-m', except that if the original cache has an entry for a1235given pathname; and the contents of the path matches with the tree1236being read, the stat info from the cache is used. (In other words, the1237cache's stat()s take precedence over the merged tree's)12381239That means that if you do a "git-read-tree -m <newtree>" followed by a1240"git-checkout-cache -f -a", the "git-checkout-cache" only checks out1241the stuff that really changed.12421243This is used to avoid unnecessary false hits when "git-diff-files" is1244run after git-read-tree.124512463-Way Merge1247~~~~~~~~~~~1248Each "index" entry has two bits worth of "stage" state. stage 0 is the1249normal one, and is the only one you'd see in any kind of normal use.12501251However, when you do "git-read-tree" with three trees, the "stage"1252starts out at 1.12531254This means that you can do12551256 git-read-tree -m <tree1> <tree2> <tree3>12571258and you will end up with an index with all of the <tree1> entries in1259"stage1", all of the <tree2> entries in "stage2" and all of the1260<tree3> entries in "stage3".12611262Furthermore, "git-read-tree" has special-case logic that says: if you see1263a file that matches in all respects in the following states, it1264"collapses" back to "stage0":12651266 - stage 2 and 3 are the same; take one or the other (it makes no1267 difference - the same work has been done on stage 2 and 3)12681269 - stage 1 and stage 2 are the same and stage 3 is different; take1270 stage 3 (some work has been done on stage 3)12711272 - stage 1 and stage 3 are the same and stage 2 is different take1273 stage 2 (some work has been done on stage 2)12741275The "git-write-tree" command refuses to write a nonsensical tree, and it1276will complain about unmerged entries if it sees a single entry that is not1277stage 0.12781279Ok, this all sounds like a collection of totally nonsensical rules,1280but it's actually exactly what you want in order to do a fast1281merge. The different stages represent the "result tree" (stage 0, aka1282"merged"), the original tree (stage 1, aka "orig"), and the two trees1283you are trying to merge (stage 2 and 3 respectively).12841285In fact, the way "git-read-tree" works, it's entirely agnostic about how1286you assign the stages, and you could really assign them any which way,1287and the above is just a suggested way to do it (except since1288"git-write-tree" refuses to write anything but stage0 entries, it makes1289sense to always consider stage 0 to be the "full merge" state).12901291So what happens? Try it out. Select the original tree, and two trees1292to merge, and look how it works:12931294- if a file exists in identical format in all three trees, it will1295 automatically collapse to "merged" state by the new git-read-tree.12961297- a file that has _any_ difference what-so-ever in the three trees1298 will stay as separate entries in the index. It's up to "script1299 policy" to determine how to remove the non-0 stages, and insert a1300 merged version. But since the index is always sorted, they're easy1301 to find: they'll be clustered together.13021303- the index file saves and restores with all this information, so you1304 can merge things incrementally, but as long as it has entries in1305 stages 1/2/3 (ie "unmerged entries") you can't write the result. So1306 now the merge algorithm ends up being really simple:13071308 * you walk the index in order, and ignore all entries of stage 0,1309 since they've already been done.13101311 * if you find a "stage1", but no matching "stage2" or "stage3", you1312 know it's been removed from both trees (it only existed in the1313 original tree), and you remove that entry.13141315 * if you find a matching "stage2" and "stage3" tree, you remove one1316 of them, and turn the other into a "stage0" entry. Remove any1317 matching "stage1" entry if it exists too. .. all the normal1318 trivial rules ..13191320Incidentally - it also means that you don't even have to have a1321separate subdirectory for this. All the information literally is in1322the index file, which is a temporary thing anyway. There is no need to1323worry about what is in the working directory, since it is never shown1324and never used.13251326see also: link:git-write-tree.html[git-write-tree], link:git-ls-files.html[git-ls-files]132713281329NAME1330----1331git-resolve-script - Script used to merge two trees13321333SYNOPSIS1334--------1335'git-resolve-script'13361337DESCRIPTION1338-----------1339This script is used by Linus to merge two trees.134013411342NAME1343----1344git-rev-list - Lists commit objects in reverse chronological order13451346SYNOPSIS1347--------1348'git-rev-list' <commit>13491350DESCRIPTION1351-----------1352Lists commit objects in reverse chronological order starting at the1353given commit, taking ancestry relationship into account. This is1354useful to produce human-readable log output.135513561357NAME1358----1359git-rev-tree - Provides the revision tree for one or more commits13601361SYNOPSIS1362--------1363'git-rev-tree' [--edges] [--cache <cache-file>] [^]<commit> [[^]<commit>]13641365DESCRIPTION1366-----------1367Provides the revision tree for one or more commits.13681369OPTIONS1370-------1371--edges::1372 Show edges (ie places where the marking changes between parent1373 and child)13741375--cache <cache-file>::1376 Use the specified file as a cache from a previous git-rev-list run1377 to speed things up. Note that this "cache" is totally different1378 concept from the directory index. Also this option is not1379 implemented yet.13801381[^]<commit>::1382 The commit id to trace (a leading caret means to ignore this1383 commit-id and below)13841385Output1386------13871388 <date> <commit>:<flags> [<parent-commit>:<flags> ]\*13891390<date>::1391 Date in 'seconds since epoch'13921393<commit>::1394 id of commit object13951396<parent-commit>::1397 id of each parent commit object (>1 indicates a merge)13981399<flags>::14001401 The flags are read as a bitmask representing each commit1402 provided on the commandline. eg: given the command:14031404 $ git-rev-tree <com1> <com2> <com3>14051406 The output:14071408 <date> <commit>:514091410 means that <commit> is reachable from <com1>(1) and <com3>(4)14111412A revtree can get quite large. "git-rev-tree" will eventually allow1413you to cache previous state so that you don't have to follow the whole1414thing down.14151416So the change difference between two commits is literally14171418 git-rev-tree [commit-id1] > commit1-revtree1419 git-rev-tree [commit-id2] > commit2-revtree1420 join -t : commit1-revtree commit2-revtree > common-revisions14211422(this is also how to find the most common parent - you'd look at just1423the head revisions - the ones that aren't referred to by other1424revisions - in "common-revision", and figure out the best one. I1425think.)142614271428NAME1429----1430git-rpull - Pulls from a remote repository over ssh connection143114321433SYNOPSIS1434--------1435'git-rpull' [-c] [-t] [-a] [-v] commit-id url14361437DESCRIPTION1438-----------1439Pulls from a remote repository over ssh connection, invoking git-rpush on1440the other end.14411442OPTIONS1443-------1444-c::1445 Get the commit objects.1446-t::1447 Get trees associated with the commit objects.1448-a::1449 Get all the objects.1450-v::1451 Report what is downloaded.145214531454NAME1455----1456git-rpush - Helper "server-side" program used by git-rpull14571458SYNOPSIS1459--------1460'git-rpush'14611462DESCRIPTION1463-----------1464Helper "server-side" program used by git-rpull.146514661467NAME1468----1469git-tag-script - An example script to create a tag object signed with GPG147014711472SYNOPSIS1473--------1474'git-tag-script'14751476DESCRIPTION1477-----------1478This is an example script that uses "git-mktag" to create a tag object1479signed with GPG.148014811482NAME1483----1484git-tar-tree - Creates a tar archive of the files in the named tree14851486SYNOPSIS1487--------1488'git-tar-tree' <tree-ish> [ <base> ]14891490DESCRIPTION1491-----------1492Creates a tar archive containing the tree structure for the named tree.1493When <base> is specified it is added as a leading path as the files in the1494generated tar archive.149514961497NAME1498----1499git-unpack-file - Creates a temporary file with a blob's contents150015011502SYNOPSIS1503--------1504'git-unpack-file' <blob>15051506DESCRIPTION1507-----------1508Creates a file holding the contents of the blob specified by sha1. It1509returns the name of the temporary file in the following format:1510 .merge_file_XXXXX15111512OPTIONS1513-------1514<blob>::1515 Must be a blob id15161517NAME1518----1519git-update-cache - Modifies the index or directory cache15201521SYNOPSIS1522--------1523'git-update-cache'1524 [--add] [--remove] [--refresh] [--replace]1525 [--ignore-missing]1526 [--force-remove <file>]1527 [--cacheinfo <mode> <object> <file>]\*1528 [--] [<file>]\*15291530DESCRIPTION1531-----------1532Modifies the index or directory cache. Each file mentioned is updated1533into the cache and any 'unmerged' or 'needs updating' state is1534cleared.15351536The way "git-update-cache" handles files it is told about can be modified1537using the various options:15381539OPTIONS1540-------1541--add::1542 If a specified file isn't in the cache already then it's1543 added.1544 Default behaviour is to ignore new files.15451546--remove::1547 If a specified file is in the cache but is missing then it's1548 removed.1549 Default behaviour is to ignore removed file.15501551--refresh::1552 Looks at the current cache and checks to see if merges or1553 updates are needed by checking stat() information.15541555--ignore-missing::1556 Ignores missing files during a --refresh15571558--cacheinfo <mode> <object> <path>::1559 Directly insert the specified info into the cache.15601561--force-remove::1562 Remove the file from the index even when the working directory1563 still has such a file.15641565--replace::1566 By default, when a file `path` exists in the index,1567 git-update-cache refuses an attempt to add `path/file`.1568 Similarly if a file `path/file` exists, a file `path`1569 cannot be added. With --replace flag, existing entries1570 that conflicts with the entry being added are1571 automatically removed with warning messages.15721573--::1574 Do not interpret any more arguments as options.15751576<file>::1577 Files to act on.1578 Note that files begining with '.' are discarded. This includes1579 `./file` and `dir/./file`. If you don't want this, then use 1580 cleaner names.1581 The same applies to directories ending '/' and paths with '//'15821583Using --refresh1584---------------1585'--refresh' does not calculate a new sha1 file or bring the cache1586up-to-date for mode/content changes. But what it *does* do is to1587"re-match" the stat information of a file with the cache, so that you1588can refresh the cache for a file that hasn't been changed but where1589the stat entry is out of date.15901591For example, you'd want to do this after doing a "git-read-tree", to link1592up the stat cache details with the proper files.15931594Using --cacheinfo1595-----------------1596'--cacheinfo' is used to register a file that is not in the current1597working directory. This is useful for minimum-checkout merging.15981599To pretend you have a file with mode and sha1 at path, say:16001601 $ git-update-cache --cacheinfo mode sha1 path16021603To update and refresh only the files already checked out:16041605 git-checkout-cache -n -f -a && git-update-cache --ignore-missing --refresh160616071608NAME1609----1610git-write-blob - Creates a blob from a file16111612SYNOPSIS1613--------1614'git-write-blob' <any-file-on-the-filesystem>16151616DESCRIPTION1617-----------1618Writes the contents of the named file (which can be outside of the work1619tree) as a blob into the object database, and reports its object ID to its1620standard output. This is used by "git-merge-one-file-script" to update the1621cache without modifying files in the work tree.162216231624NAME1625----1626git-write-tree - Creates a tree from the current cache16271628SYNOPSIS1629--------1630'git-write-tree'16311632DESCRIPTION1633-----------1634Creates a tree object using the current cache.16351636The cache must be merged.16371638Conceptually, "git-write-tree" sync()s the current directory cache contents1639into a set of tree files.1640In order to have that match what is actually in your directory right1641now, you need to have done a "git-update-cache" phase before you did the1642"git-write-tree".16431644164516461647////////////////////////////////////////////////////////////////16481649Producing man pages and html16501651To create a set of html pages run:1652 perl split-docs.pl -html < core-git.txt16531654To create a set of man pages run:1655 perl split-docs.pl -man < core-git.txt165616571658////////////////////////////////////////////////////////////////1659