From: David Greaves Date: Fri, 6 May 2005 06:48:52 +0000 (-0700) Subject: Reference documentation for the core git commands. X-Git-Tag: v0.99~633 X-Git-Url: https://git.verplant.org/?a=commitdiff_plain;h=c64b9b88605f9d6824bf953a84d993c4a70fd759;p=git.git Reference documentation for the core git commands. Signed-off-by: David Greaves Signed-off-by: Junio C Hamano --- diff --git a/Documentation/core-git.txt b/Documentation/core-git.txt new file mode 100644 index 00000000..9b84a5e2 --- /dev/null +++ b/Documentation/core-git.txt @@ -0,0 +1,1128 @@ +This file contains reference information for the core git commands. +It is actually based on the source from Petr Baudis' tree and may +therefore contain a few 'extras' that may or may not make it upstream. + +The README contains much useful definition and clarification info - +read that first. And of the commands, I suggest reading +'update-cache' and 'read-tree' first - I wish I had! + +Thanks to original email authors and proof readers esp Junio C Hamano + + +David Greaves +24/4/05 + +Identifier terminology used: + + + Indicates any object sha1 identifier + + + Indicates a blob object sha1 identifier + + + Indicates a tree object sha1 identifier + + + Indicates a commit object sha1 identifier + + + Indicates a tree or commit object sha1 identifier (usually + because the command can read the a contains). + [Eventually may be replaced with if means + in all commands] + + + Indicates that an object type is required. + Currently one of: blob/tree/commit + + + Indicates a filename - often includes leading path + + + Indicates the path of a file (is this ever useful?) + + + +################################################################ +cat-file + cat-file (-t | ) + +Provide contents or type of objects in the repository. The type is +required if -t is not being used to find the object type. + + + The sha1 identifier of the object. + +-t + show the object type identified by + + + One of: blob/tree/commit + +Output + +If -t is specified, one of: + blob/tree/commit + +Otherwise the raw (though uncompressed) contents of the will +be returned. + + +################################################################ +check-files + check-files ... + +Check that a list of files are up-to-date between the filesystem and +the cache. Used to verify a patch target before doing a patch. + +Files that do not exist on the filesystem are considered up-to-date +(whether or not they are in the cache). + +Emits an error message on failure. +preparing to update existing file not in cache + exists but is not in the cache + +preparing to update file not uptodate in cache + on disk is not up-to-date with the cache + +exits with a status code indicating success if all files are +up-to-date. + +see also: update-cache + + +################################################################ +checkout-cache + checkout-cache [-q] [-a] [-f] [-n] [--prefix=] + [--] ... + +Will copy all files listed from the cache to the working directory +(not overwriting existing files). Note that the file contents are +restored - NOT the file permissions. +??? l 58 checkout-cache.c says restore executable bit. + +-q + be quiet if files exist or are not in the cache + +-f + forces overwrite of existing files + +-a + checks out all files in the cache (will then continue to + process listed files). +-n + Don't checkout new files, only refresh files already checked + out. + +--prefix= + When creating files, prepend (usually a directory + including a trailing /) + +-- + Do not interpret any more arguments as options. + +Note that the order of the flags matters: + + checkout-cache -a -f file.c + +will first check out all files listed in the cache (but not overwrite +any old ones), and then force-checkout file.c a second time (ie that +one _will_ overwrite any old contents with the same filename). + +Also, just doing "checkout-cache" does nothing. You probably meant +"checkout-cache -a". And if you want to force it, you want +"checkout-cache -f -a". + +Intuitiveness is not the goal here. Repeatability is. The reason for +the "no arguments means no work" thing is that from scripts you are +supposed to be able to do things like + + find . -name '*.h' -print0 | xargs -0 checkout-cache -f -- + +which will force all existing *.h files to be replaced with their +cached copies. If an empty command line implied "all", then this would +force-refresh everything in the cache, which was not the point. + +To update and refresh only the files already checked out: + + checkout-cache -n -f -a && update-cache --ignore-missing --refresh + +Oh, and the "--" is just a good idea when you know the rest will be +filenames. Just so that you wouldn't have a filename of "-a" causing +problems (not possible in the above example, but get used to it in +scripting!). + +The prefix ability basically makes it trivial to use checkout-cache as +a "export as tree" function. Just read the desired tree into the +index, and do a + + checkout-cache --prefix=export-dir/ -a + +and checkout-cache will "export" the cache into the specified +directory. + +NOTE! The final "/" is important. The exported name is literally just +prefixed with the specified string, so you can also do something like + + checkout-cache --prefix=.merged- Makefile + +to check out the currently cached copy of "Makefile" into the file +".merged-Makefile". + + +################################################################ +commit-tree + commit-tree [-p ]* < changelog + +Creates a new commit object based on the provided tree object and +emits the new commit object id on stdout. If no parent is given then +it is considered to be an initial tree. + +A commit object usually has 1 parent (a commit after a change) or up +to 16 parents. More than one parent represents a merge of branches +that led to them. + +While a tree represents a particular directory state of a working +directory, a commit represents that state in "time", and explains how +to get there. + +Normally a commit would identify a new "HEAD" state, and while git +doesn't care where you save the note about that state, in practice we +tend to just write the result to the file ".git/HEAD", so that we can +always see what the last committed state was. + +Options + + + An existing tree object + +-p + Each -p indicates a the id of a parent commit object. + + +Commit Information + +A commit encapsulates: + all parent object ids + author name, email and date + committer name and email and the commit time. + +If not provided, commit-tree uses your name, hostname and domain to +provide author and committer info. This can be overridden using the +following environment variables. + AUTHOR_NAME + AUTHOR_EMAIL + AUTHOR_DATE + COMMIT_AUTHOR_NAME + COMMIT_AUTHOR_EMAIL +(nb <,> and '\n's are stripped) + +A commit comment is read from stdin (max 999 chars). If a changelog +entry is not provided via '<' redirection, commit-tree will just wait +for one to be entered and terminated with ^D + +see also: write-tree + + +################################################################ +diff-cache + diff-cache [-p] [-r] [-z] [--cached] + +Compares the content and mode of the blobs found via a tree object +with the content of the current cache and, optionally ignoring the +stat state of the file on disk. + + + The id of a tree or commit object to diff against. + +-p + generate patch (see section on generating patches) + +-r + recurse + +-z + \0 line termination on output + +--cached + do not consider the on-disk file at all + +Output format: + +See "Output format from diff-cache, diff-tree and show-diff" section. + +Operating Modes + +You can choose whether you want to trust the index file entirely +(using the "--cached" flag) or ask the diff logic to show any files +that don't match the stat state as being "tentatively changed". Both +of these operations are very useful indeed. + +Cached Mode + +If --cached is specified, it allows you to ask: + show me the differences between HEAD and the current index + contents (the ones I'd write with a "write-tree") + +For example, let's say that you have worked on your index file, and are +ready to commit. You want to see eactly _what_ you are going to commit is +without having to write a new tree object and compare it that way, and to +do that, you just do + + diff-cache --cached $(cat .git/HEAD) + +Example: let's say I had renamed "commit.c" to "git-commit.c", and I had +done an "upate-cache" to make that effective in the index file. +"show-diff" wouldn't show anything at all, since the index file matches +my working directory. But doing a diff-cache does: + torvalds@ppc970:~/git> diff-cache --cached $(cat .git/HEAD) + -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c + +100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c + +And as you can see, the output matches "diff-tree -r" output (we +always do equivalent of "-r", since the index is flat). +You can trivially see that the above is a rename. + +In fact, "diff-cache --cached" _should_ always be entirely equivalent to +actually doing a "write-tree" and comparing that. Except this one is much +nicer for the case where you just want to check where you are. + +So doing a "diff-cache --cached" is basically very useful when you are +asking yourself "what have I already marked for being committed, and +what's the difference to a previous tree". + +Non-cached Mode + +The "non-cached" mode takes a different approach, and is potentially +the even more useful of the two in that what it does can't be emulated +with a "write-tree + diff-tree". Thus that's the default mode. The +non-cached version asks the question + + "show me the differences between HEAD and the currently checked out + tree - index contents _and_ files that aren't up-to-date" + +which is obviously a very useful question too, since that tells you what +you _could_ commit. Again, the output matches the "diff-tree -r" output to +a tee, but with a twist. + +The twist is that if some file doesn't match the cache, we don't have a +backing store thing for it, and we use the magic "all-zero" sha1 to show +that. So let's say that you have edited "kernel/sched.c", but have not +actually done an update-cache on it yet - there is no "object" associated +with the new state, and you get: + + torvalds@ppc970:~/v2.6/linux> diff-cache $(cat .git/HEAD ) + *100644->100664 blob 7476bbcfe5ef5a1dd87d745f298b831143e4d77e->0000000000000000000000000000000000000000 kernel/sched.c + +ie it shows that the tree has changed, and that "kernel/sched.c" has is +not up-to-date and may contain new stuff. The all-zero sha1 means that to +get the real diff, you need to look at the object in the working directory +directly rather than do an object-to-object diff. + +NOTE! As with other commands of this type, "diff-cache" does not actually +look at the contents of the file at all. So maybe "kernel/sched.c" hasn't +actually changed, and it's just that you touched it. In either case, it's +a note that you need to upate-cache it to make the cache be in sync. + +NOTE 2! You can have a mixture of files show up as "has been updated" and +"is still dirty in the working directory" together. You can always tell +which file is in which state, since the "has been updated" ones show a +valid sha1, and the "not in sync with the index" ones will always have the +special all-zero sha1. + +################################################################ +diff-tree + diff-tree [-p] [-r] [-z] []* + +Compares the content and mode of the blobs found via two tree objects. + +Note that diff-tree can use the tree encapsulated in a commit object. + + + The id of a tree or commit object. + + + + If provided, the results are limited to a subset of files + matching one of these prefix strings. + ie file matches /^||.../ + Note that pattern does not provide any wildcard or regexp features. + +-p + generate patch (see section on generating patches) + +-r + recurse + +-z + \0 line termination on output + +Limiting Output + +If you're only interested in differences in a subset of files, for +example some architecture-specific files, you might do: + + diff-tree -r arch/ia64 include/asm-ia64 + +and it will only show you what changed in those two directories. + +Or if you are searching for what changed in just kernel/sched.c, just do + + diff-tree -r kernel/sched.c + +and it will ignore all differences to other files. + +The pattern is always the prefix, and is matched exactly (ie there are no +wildcards - although matching a directory, which it does support, can +obviously be seen as a "wildcard" for all the files under that directory). + +Output format: + +See "Output format from diff-cache, diff-tree and show-diff" section. + +An example of normal usage is: + + torvalds@ppc970:~/git> diff-tree 5319e4d609cdd282069cc4dce33c1db559539b03 b4e628ea30d5ab3606119d2ea5caeab141d38df7 + *100664->100664 blob ac348b7d5278e9d04e3a1cd417389379c32b014f->a01513ed4d4d565911a60981bfb4173311ba3688 fsck-cache.c + +which tells you that the last commit changed just one file (it's from +this one: + + commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8 + tree 5319e4d609cdd282069cc4dce33c1db559539b03 + parent b4e628ea30d5ab3606119d2ea5caeab141d38df7 + author Linus Torvalds Sat Apr 9 12:02:30 2005 + committer Linus Torvalds Sat Apr 9 12:02:30 2005 + + Make "fsck-cache" print out all the root commits it finds. + + Once I do the reference tracking, I'll also make it print out all the + HEAD commits it finds, which is even more interesting. + +in case you care). + +################################################################ +diff-tree-helper + diff-tree-helper [-z] + +Reads output from diff-cache, diff-tree and show-diff and +generates patch format output. + +-z + \0 line termination on input + +See also the section on generating patches. + +################################################################ +fsck-cache + fsck-cache [[--unreachable] *] + +Verifies the connectivity and validity of the objects in the database. + + + A commit object to treat as the head of an unreachability + trace + +--unreachable + print out objects that exist but that aren't readable from any + of the specified root nodes + +It tests SHA1 and general object sanity, but it does full tracking of +the resulting reachability and everything else. It prints out any +corruption it finds (missing or bad objects), and if you use the +"--unreachable" flag it will also print out objects that exist but +that aren't readable from any of the specified root nodes. + +So for example + + fsck-cache --unreachable $(cat .git/HEAD) + +or, for Cogito users: + + fsck-cache --unreachable $(cat .git/heads/*) + +will do quite a _lot_ of verification on the tree. There are a few +extra validity tests to be added (make sure that tree objects are +sorted properly etc), but on the whole if "fsck-cache" is happy, you +do have a valid tree. + +Any corrupt objects you will have to find in backups or other archives +(ie you can just remove them and do an "rsync" with some other site in +the hopes that somebody else has the object you have corrupted). + +Of course, "valid tree" doesn't mean that it wasn't generated by some +evil person, and the end result might be crap. Git is a revision +tracking system, not a quality assurance system ;) + +Extracted Diagnostics + +expect dangling commits - potential heads - due to lack of head information + You haven't specified any nodes as heads so it won't be + possible to differentiate between un-parented commits and + root nodes. + +missing sha1 directory '' + The directory holding the sha1 objects is missing. + +unreachable + The object , isn't actually referred to directly + or indirectly in any of the trees or commits seen. This can + mean that there's another root na SHA1_ode that you're not specifying + or that the tree is corrupt. If you haven't missed a root node + then you might as well delete unreachable nodes since they + can't be used. + +missing + The object , is referred to but isn't present in + the database. + +dangling + The object , is present in the database but never + _directly_ used. A dangling commit could be a root node. + +warning: fsck-cache: tree has full pathnames in it + And it shouldn't... + +sha1 mismatch + The database has an object who's sha1 doesn't match the + database value. + This indicates a ??serious?? data integrity problem. + (note: this error occured during early git development when + the database format changed.) + +Environment Variables + +SHA1_FILE_DIRECTORY + used to specify the object database root (usually .git/objects) + +################################################################ +git-export + git-export top [base] + +probably deprecated: +On Wed, 20 Apr 2005, Petr Baudis wrote: +>> I will probably not buy git-export, though. (That is, it is merged, but +>> I won't make git frontend for it.) My "git export" already does +>> something different, but more importantly, "git patch" of mine already +>> does effectively the same thing as you do, just for a single patch; so I +>> will probably just extend it to do it for an (a,b] range of patches. + + +That's fine. It was a quick hack, just to show that if somebody wants to, +the data is trivially exportable. + + Linus + +Although in Linus' distribution, git-export is not part of 'core' git. + +################################################################ +init-db + init-db + +This simply creates an empty git object database - basically a .git +directory. + +If the object storage directory is specified via the +SHA1_FILE_DIRECTORY environment variable then the sha1 directories are +created underneath - otherwise the default .git/objects directory is +used. + +init-db won't hurt an existing repository. + + +################################################################ +ls-tree + ls-tree [-r] [-z] + +convert the tree object to a human readable (and script +processable) form. + + + Id of a tree or commit object. +-r + recurse into sub-trees + +-z + \0 line termination on output + +Output Format +\t \t \t + + +################################################################ +merge-base + merge-base + +merge-base finds as good a common ancestor as possible. Given a +selection of equally good common ancestors it should not be relied on +to decide in any particular way. + +The merge-base algorithm is still in flux - use the source... + + +################################################################ +merge-cache + merge-cache (-a | -- | *) + +This looks up the (s) in the cache and, if there are any merge +entries, unpacks all of them (which may be just one file, of course) +into up to three separate temporary files, and then executes the +supplied with those three files as arguments 1,2,3 +(empty argument if no file), and as argument 4. + +-- + Interpret all future arguments as filenames + +-a + Run merge against all files in the cache that need merging. + +If merge-cache is called with multiple s (or -a) then it +processes them in turn only stopping if merge returns a non-zero exit +code. + +Typically this is run with the a script calling the merge command from +the RCS package. + +A sample script called git-merge-one-file-script is included in the +ditribution. + +ALERT ALERT ALERT! The git "merge object order" is different from the +RCS "merge" program merge object order. In the above ordering, the +original is first. But the argument order to the 3-way merge program +"merge" is to have the original in the middle. Don't ask me why. + +Examples: + + torvalds@ppc970:~/merge-test> merge-cache cat MM + This is MM from the original tree. # original + This is modified MM in the branch A. # merge1 + This is modified MM in the branch B. # merge2 + This is modified MM in the branch B. # current contents + +or + + torvalds@ppc970:~/merge-test> merge-cache cat AA MM + cat: : No such file or directory + This is added AA in the branch A. + This is added AA in the branch B. + This is added AA in the branch B. + fatal: merge program failed + +where the latter example shows how "merge-cache" will stop trying to +merge once anything has returned an error (ie "cat" returned an error +for the AA file, because it didn't exist in the original, and thus +"merge-cache" didn't even try to merge the MM thing). + + +################################################################ +read-tree + read-tree ( | -m [ ])" + +Reads the tree information given by into the directory cache, +but does not actually _update_ any of the files it "caches". (see: +checkout-cache) + +Optionally, it can merge a tree into the cache or perform a 3-way +merge. + +Trivial merges are done by read-tree itself. Only conflicting paths +will be in unmerged state when read-tree returns. + +-m + Perform a merge, not just a read + + + The id of the tree object(s) to be read/merged. + + +Merging +If -m is specified, read-tree performs 2 kinds of merge, a single tree +merge if only 1 tree is given or a 3-way merge if 3 trees are +provided. + +Single Tree Merge +If only 1 tree is specified, read-tree operates as if the user did not +specify "-m", except that if the original cache has an entry for a +given pathname; and the contents of the path matches with the tree +being read, the stat info from the cache is used. (In other words, the +cache's stat()s take precedence over the merged tree's) + +That means that if you do a "read-tree -m " followed by a +"checkout-cache -f -a", the checkout-cache only checks out the stuff +that really changed. + +This is used to avoid unnecessary false hits when show-diff is +run after read-tree. + +3-Way Merge +Each "index" entry has two bits worth of "stage" state. stage 0 is the +normal one, and is the only one you'd see in any kind of normal use. + +However, when you do "read-tree" with multiple trees, the "stage" +starts out at 0, but increments for each tree you read. And in +particular, the "-m" flag means "start at stage 1" instead. + +This means that you can do + + read-tree -m + +and you will end up with an index with all of the entries in +"stage1", all of the entries in "stage2" and all of the + entries in "stage3". + +Furthermore, "read-tree" has special-case logic that says: if you see +a file that matches in all respects in the following states, it +"collapses" back to "stage0": + + - stage 2 and 3 are the same; take one or the other (it makes no + difference - the same work has been done on stage 2 and 3) + + - stage 1 and stage 2 are the same and stage 3 is different; take + stage 3 (some work has been done on stage 3) + + - stage 1 and stage 3 are the same and stage 2 is different take + stage 2 (some work has been done on stage 2) + +Write-tree refuses to write a nonsensical tree, so write-tree will +complain about unmerged entries if it sees a single entry that is not +stage 0". + +Ok, this all sounds like a collection of totally nonsensical rules, +but it's actually exactly what you want in order to do a fast +merge. The different stages represent the "result tree" (stage 0, aka +"merged"), the original tree (stage 1, aka "orig"), and the two trees +you are trying to merge (stage 2 and 3 respectively). + +In fact, the way "read-tree" works, it's entirely agnostic about how +you assign the stages, and you could really assign them any which way, +and the above is just a suggested way to do it (except since +"write-tree" refuses to write anything but stage0 entries, it makes +sense to always consider stage 0 to be the "full merge" state). + +So what happens? Try it out. Select the original tree, and two trees +to merge, and look how it works: + + - if a file exists in identical format in all three trees, it will + automatically collapse to "merged" state by the new read-tree. + + - a file that has _any_ difference what-so-ever in the three trees + will stay as separate entries in the index. It's up to "script + policy" to determine how to remove the non-0 stages, and insert a + merged version. But since the index is always sorted, they're easy + to find: they'll be clustered together. + + - the index file saves and restores with all this information, so you + can merge things incrementally, but as long as it has entries in + stages 1/2/3 (ie "unmerged entries") you can't write the result. + +So now the merge algorithm ends up being really simple: + + - you walk the index in order, and ignore all entries of stage 0, + since they've already been done. + + - if you find a "stage1", but no matching "stage2" or "stage3", you + know it's been removed from both trees (it only existed in the + original tree), and you remove that entry. - if you find a + matching "stage2" and "stage3" tree, you remove one of them, and + turn the other into a "stage0" entry. Remove any matching "stage1" + entry if it exists too. .. all the normal trivial rules .. + +Incidentally - it also means that you don't even have to have a separate +subdirectory for this. All the information literally is in the index file, +which is a temporary thing anyway. There is no need to worry about what is in +the working directory, since it is never shown and never used. + +see also: +write-tree +show-files + + +################################################################ +rev-list + +Lists commit objects in reverse chronological order starting at the +given commit, taking ancestry relationship into account. This is +useful to produce human-readable log output. + + +################################################################ +rev-tree + rev-tree [--edges] [--cache ] [^] [[^]] + +Provides the revision tree for one or more commits. + +--edges + Show edges (ie places where the marking changes between parent + and child) + +--cache + Use the specified file as a cache. [Not implemented yet] + +[^] + The commit id to trace (a leading caret means to ignore this + commit-id and below) + +Output: + : [: ]* + + + Date in 'seconds since epoch' + + + id of commit object + + + id of each parent commit object (>1 indicates a merge) + + + + The flags are read as a bitmask representing each commit + provided on the commandline. eg: given the command: + + $ rev-tree + + The output: + + :5 + + means that is reachable from (1) and (4) + +A revtree can get quite large. rev-tree will eventually allow you to +cache previous state so that you don't have to follow the whole thing +down. + +So the change difference between two commits is literally + + rev-tree [commit-id1] > commit1-revtree + rev-tree [commit-id2] > commit2-revtree + join -t : commit1-revtree commit2-revtree > common-revisions + +(this is also how to find the most common parent - you'd look at just +the head revisions - the ones that aren't referred to by other +revisions - in "common-revision", and figure out the best one. I +think.) + + +################################################################ +show-diff + show-diff [-p] [-q] [-s] [-z] [paths...] + +Compares the files in the working tree and the cache. When paths +are specified, compares only those named paths. Otherwise all +entries in the cache are compared. The output format is the +same as diff-cache and diff-tree. + +-p + generate patch (see section on generating patches) + +-q + Remain silent even on nonexisting files + +-s + Does not do anything other than what -q does. + +Output format: + +See "Output format from diff-cache, diff-tree and show-diff" section. + +################################################################ +show-files + show-files [-z] [-t] + (--[cached|deleted|others|ignored|stage|unmerged])* + (-[c|d|o|i|s|u])* + [-x |--exclude=] + [-X |--exclude-from=] + +This merges the file listing in the directory cache index with the +actual working directory list, and shows different combinations of the +two. + +One or more of the options below may be used to determine the files +shown: + +-c|--cached + Show cached files in the output (default) + +-d|--deleted + Show deleted files in the output + +-o|--others + Show other files in the output + +-i|--ignored + Show ignored files in the output + Note the this also reverses any exclude list present. + +-s|--stage + Show stage files in the output + +-u|--unmerged + Show unmerged files in the output (forces --stage) + +#-t [not in Linus' tree (yet?)] +# Identify the file status with the following tags (followed by +# a space) at the start of each line: +# H cached +# M unmerged +# R removed/deleted +# ? other + +-z + \0 line termination on output + +-x|--exclude= + Skips files matching pattern. + Note that pattern is a shell wildcard pattern. + +-X|--exclude-from= + exclude patterns are read from ; 1 per line. + Allows the use of the famous dontdiff file as follows to find + out about uncommitted files just as dontdiff is used with + the diff command: + show-files --others --exclude-from=dontdiff + +Output +show files just outputs the filename unless --stage is specified in +which case it outputs: + +[ ] + +show-files --unmerged" and "show-files --stage " can be used to examine +detailed information on unmerged paths. + +For an unmerged path, instead of recording a single mode/SHA1 pair, +the dircache records up to three such pairs; one from tree O in stage +1, A in stage 2, and B in stage 3. This information can be used by +the user (or Cogito) to see what should eventually be recorded at the +path. (see read-cache for more information on state) + +see also: +read-cache + + +################################################################ +unpack-file + unpack-file + +Creates a file holding the contents of the blob specified by sha1. It +returns the name of the temporary file in the following format: + .merge_file_XXXXX + + + Must be a blob id + +################################################################ +update-cache + update-cache [--add] [--remove] [--refresh [--ignore-missing]] + [--cacheinfo ]* + [--] []* + +Modifies the index or directory cache. Each file mentioned is updated +into the cache and any 'unmerged' or 'needs updating' state is +cleared. + +The way update-cache handles files it is told about can be modified +using the various options: + +--add + If a specified file isn't in the cache already then it's + added. + Default behaviour is to ignore new files. + +--remove + If a specified file is in the cache but is missing then it's + removed. + Default behaviour is to ignore removed file. + +--refresh + Looks at the current cache and checks to see if merges or + updates are needed by checking stat() information. + +--ignore-missing + Ignores missing files during a --refresh + +--cacheinfo + Directly insert the specified info into the cache. + +-- + Do not interpret any more arguments as options. + + + Files to act on. + Note that files begining with '.' are discarded. This includes + "./file" and "dir/./file". If you don't want this, then use + cleaner names. + The same applies to directories ending '/' and paths with '//' + + +Using --refresh + +--refresh does not calculate a new sha1 file or bring the cache +up-to-date for mode/content changes. But what it _does_ do is to +"re-match" the stat information of a file with the cache, so that you +can refresh the cache for a file that hasn't been changed but where +the stat entry is out of date. + +For example, you'd want to do this after doing a "read-tree", to link +up the stat cache details with the proper files. + +Using --cacheinfo +--cacheinfo is used to register a file that is not in the current +working directory. This is useful for minimum-checkout merging. + +To pretend you have a file with mode and sha1 at path, say: + + $ update-cache --cacheinfo mode sha1 path + +To update and refresh only the files already checked out: + + checkout-cache -n -f -a && update-cache --ignore-missing --refresh + + +################################################################ +write-tree + write-tree + +Creates a tree object using the current cache. + +The cache must be merged. + +Conceptually, write-tree sync()s the current directory cache contents +into a set of tree files. +In order to have that match what is actually in your directory right +now, you need to have done a "update-cache" phase before you did the +"write-tree". + + +################################################################ + +Output format from diff-cache, diff-tree and show-diff. + +These commands all compare two sets of things; what are +compared are different: + + diff-cache + + compares the and the files on the filesystem. + + diff-cache --cached + + compares the and the cache. + + diff-tree [-r] [paths...] + + compares the trees named by the two arguments. + + show-diff [paths...] + + compares the cache and the files on the filesystem. + +The following desription uses "old" and "new" to mean those +compared entities. + +For files in old but not in new (i.e. removed): +- \t \t \t + +For files not in old but in new (i.e. added): ++ \t \t \t + +For files that differ: +*-> \t \t -> \t + + is shown as all 0's if new is a file on the +filesystem and it is out of sync with the cache. Example: + + *100644->100660 blob 5be4a414b32cf4204f889469942986d3d783da84->0000000000000000000000000000000000000000 file.c + +################################################################ + +Generating patches + +When diff-cache, diff-tree, or show-diff are run with a -p +option, they do not produce the output described in "Output +format from diff-cache, diff-tree and show-diff" section. It +instead produces a patch file. + +The patch generation can be customized at two levels. This +customization also applies to diff-tree-helper. + +1. When the environment variable GIT_EXTERNAL_DIFF is not set, + these commands internally invoke diff like this: + + diff -L k/ -L l/ -pu + + For added files, /dev/null is used for . For removed + files, /dev/null is used for + + The first part of the above command-line can be customized via + the environment variable GIT_DIFF_CMD. For example, if you + do not want to show the extra level of leading path, you can + say this: + + GIT_DIFF_CMD="diff -L'%s' -L'%s'" show-diff -p + + Caution: Do not use more than two '%s' in GIT_DIFF_CMD. + + The diff formatting options can be customized via the + environment variable GIT_DIFF_OPTS. For example, if you + prefer context diff: + + GIT_DIFF_OPTS=-c diff-cache -p $(cat .git/HEAD) + + +2. When the environment variable GIT_EXTERNAL_DIFF is set, the + program named by it is called, instead of the diff invocation + described above. + + For a path that is added, removed, or modified, + GIT_EXTERNAL_DIFF is called with 7 parameters: + + path old-file old-hex old-mode new-file new-hex new-mode + + where + -file are files GIT_EXTERNAL_DIFF can use to read the + contents of , + -hex are the 40-hexdigit SHA1 hashes, + -mode are the octal representation of the file modes. + + The file parameters can point at the user's working file + (e.g. new-file in show-diff), /dev/null (e.g. old-file when a + new file is added), or a temporary file (e.g. old-file in the + cache). GIT_EXTERNAL_DIFF should not worry about + unlinking the temporary file --- it is removed when + GIT_EXTERNAL_DIFF exits. + + For a path that is unmerged, GIT_EXTERNAL_DIFF is called with + 1 parameter, path. + +################################################################ + +Terminology: - see README for description +Each line contains terms used interchangeably + +object database, .git directory +directory cache, index +id, sha1, sha1-id, sha1 hash +type, tag +blob, blob object +tree, tree object +commit, commit object +parent +root object +changeset + + +git Environment Variables +AUTHOR_NAME +AUTHOR_EMAIL +AUTHOR_DATE +COMMIT_AUTHOR_NAME +COMMIT_AUTHOR_EMAIL +GIT_DIFF_CMD +GIT_DIFF_OPTS +GIT_EXTERNAL_DIFF +GIT_INDEX_FILE +SHA1_FILE_DIRECTORY + +