{"thread":{"id":"293","subject":"[FILE] Docs update","startedAt":"2005-04-24T19:46:24Z","lastAt":"2005-04-27T11:46:04Z","messageCount":5,"participants":["David Greaves","Junio C Hamano","Linus Torvalds","Daniel Barkalow"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"1539","messageId":"426BF790.9070406@dgreaves.com","threadId":"293","inReplyTo":null,"subject":"[FILE] Docs update","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-04-24T19:46:24Z","receivedAt":"2005-04-24T19:46:24Z","isPatch":false,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"Now contains strawman reference documentation for all the core git commands\n\nIt would probably be a good idea for people who know what's going on to \nvalidate these docs lest the partially sighted author unwittingly leads \ntoo many potential gitters over conceptual cliffs...\n\nAnd I've attached this as a file rather than a patch to make it easier \nfor people to read.\n\nSigned-off-by: David Greaves \n---\n\n\nThis file contains reference information for the core git commands.\nIt is actually based on the source from Petr Baudis' tree and may\ntherefore contain a few 'extras' that may or may not make it upstream.\n\nThe README contains much useful definition and clarification info -\nread that first. And of the commands, I suggest reading\n'update-cache' and 'read-tree' first - I wish I had!\n\nDavid Greaves - 24/4/05\n\n\nIdentifier terminology used:\n\n\n\tIndicates any object sha1 identifier\n\n\n\tIndicates a blob object sha1 identifier\n\n\n\tIndicates a tree object sha1 identifier\n\n\n\tIndicates a commit object sha1 identifier\n\n\n\tIndicates a tree or commit object sha1 identifier (usually\n\tbecause the command can read the a contains).\n\t[Eventually may be replaced with if means\n\t in all commands]\n\n\n\tIndicates that an object type is required.\n\tCurrently one of: blob/tree/commit\n\n\n\tIndicates a filename - often includes leading path\n\n\n\tIndicates the path of a file (is this ever useful?)\n\n\n\n################################################################\ncat-file\n\tcat-file (-t | ) \n\nProvide contents or type of objects in the repository. The type is\nrequired if -t is not being used to find the object type.\n\n\n\tThe sha1 identifier of the object.\n\n-t\n\tshow the object type identified by \n\n\n\tOne of: blob/tree/commit\n\nOutput\n\nIf -t is specified, one of:\n blob/tree/commit\n\nOtherwise the raw (though uncompressed) contents of the will\nbe returned.\n\n\n################################################################\ncheck-files\n\tcheck-files ...\n\nCheck that a list of files are up-to-date between the filesystem and\nthe cache. Used to verify a patch target before doing a patch.\n\nFiles that do not exist on the filesystem are considered up-to-date\n(whether or not they are in the cache).\n\nEmits an error message on failure.\npreparing to update existing file not in cache\n\t exists but is not in the cache\n\npreparing to update file not uptodate in cache\n\t on disk is not up-to-date with the cache\n\nexits with a status code indicating success if all files are\nup-to-date.\n\nsee also: update-cache\n\n\n################################################################\ncheckout-cache\n\tcheckout-cache [-q] [-a] [-f] [--prefix=] [--] ...\n\nWill copy all files listed from the cache to the working directory\n(not overwriting existing files). Note that the file contents are\nrestored - NOT the file permissions.\n\n-q\n\tbe quiet if files exist or are not in the cache\n\n-f\n\tforces overwrite of existing files\n\n-a\n\tchecks out all files in the cache (will then continue to\n\tprocess listed files).\n\n--prefix=\n\tWhen creating files, prepend (usually a directory\n\tincluding a trailing /)\n\n--\n\tDo not interpret any more arguments as options.\n\nNote that the order of the flags matters:\n\n\tcheckout-cache -a -f file.c\n\nwill first check out all files listed in the cache (but not overwrite\nany old ones), and then force-checkout file.c a second time (ie that\none _will_ overwrite any old contents with the same filename).\n\nAlso, just doing \"checkout-cache\" does nothing. You probably meant\n\"checkout-cache -a\". And if you want to force it, you want\n\"checkout-cache -f -a\".\n\nIntuitiveness is not the goal here. Repeatability is. The reason for\nthe \"no arguments means no work\" thing is that from scripts you are\nsupposed to be able to do things like\n\n\tfind . -name '*.h' -print0 | xargs -0 checkout-cache -f --\n\nwhich will force all existing *.h files to be replaced with their\ncached copies. If an empty command line implied \"all\", then this would\nforce-refresh everything in the cache, which was not the point.\n\nOh, and the \"--\" is just a good idea when you know the rest will be\nfilenames. Just so that you wouldn't have a filename of \"-a\" causing\nproblems (not possible in the above example, but get used to it in\nscripting!).\n\nThe prefix ability basically makes it trivial to use checkout-cache as\na \"export as tree\" function. Just read the desired tree into the\nindex, and do a\n \n checkout-cache --prefix=export-dir/ -a\n \nand checkout-cache will \"export\" the cache into the specified\ndirectory.\n \nNOTE! The final \"/\" is important. The exported name is literally just\nprefixed with the specified string, so you can also do something like\n \n checkout-cache --prefix=.merged- Makefile\n \nto check out the currently cached copy of \"Makefile\" into the file\n\".merged-Makefile\".\n\n\n################################################################\ncommit-tree\n\tcommit-tree [-p ]* < changelog\n\nCreates a new commit object based on the provided tree object and\nemits the new commit object id on stdout. If no parent is given then\nit is considered to be an initial tree.\n\nA commit object usually has 1 parent (a commit after a change) or up\nto 16 parents. More than one parent represents merge of branches that\nled to them.\n\nWhile a tree represents a particular directory state of a working\ndirectory, a commit represents that state in \"time\", and explains how\nto get there.\n\nNormally a commit would identify a new \"HEAD\" state, and while git\ndoesn't care where you save the note about that state, in practice we\ntend to just write the result to the file \".git/HEAD\", so that we can\nalways see what the last committed state was.\n\nOptions\n\n\n\tAn existing tree object\n\n-p \n\tEach -p indicates a the id of a parent commit object.\n\t\n\nCommit Information\n\nA commit encapsulates:\n\tall parent object ids\n\tauthor name, email and date\n\tcommitter name and email and the commit time.\n\nIf not provided, commit-tree uses your name, hostname and domain to\nprovide author and committer info. This can be overridden using the\nfollowing environment variables.\n\tAUTHOR_NAME\n\tAUTHOR_EMAIL\n\tAUTHOR_DATE\n\tCOMMIT_AUTHOR_NAME\n\tCOMMIT_AUTHOR_EMAIL\n(nb <,> and '\\n's are stripped)\n\nA commit comment is read from stdin (max 999 chars). If a changelog\nentry is not provided via '<' redirection, commit-tree will just wait\nfor one to be entered and terminated with ^D\n\nsee also: write-tree\n\n\n################################################################\ndiff-cache\n\tdiff-cache [-r] [-z] [--cached] \n\nCompares the content and mode of the blobs found via a tree object\nwith the content of the current cache and, optionally ignoring the\nstat state of the file on disk.\n\n(This is basically a special case of diff-tree that works with the\ncurrent cache as the first tree.)\n\n\n\tThe id of a tree or commit object to diff against.\n\n-r\n\trecurse\n\n-z\n\t\\0 line termination on output\n\n--cached\n\tdo not consider the on-disk file at all\n\nOutput format:\n\nFor files in the tree but not in the cache\n-\\t \\t\t\\t\t\n\nFor files in the cache but not in the tree\n+\\t \\t\t\\t\t\n\nFor files that differ:\n*->\\t \\t\t->\\t\t\n\nIn the special case of the file being changed on disk and out of sync\nwith the cache, the sha1 is all 0's. Example:\n\n\t*100644->100660 blob 5be4a414b32cf4204f889469942986d3d783da84->0000000000000000000000000000000000000000 file.c\n\t\n\nOperating Modes\n\nYou can choose whether you want to trust the index file entirely\n(using the \"--cached\" flag) or ask the diff logic to show any files\nthat don't match the stat state as being \"tentatively changed\". Both\nof these operations are very useful indeed.\n\nCached Mode\n\nIf --cached is specified, it allows you to ask:\n\tshow me the differences between HEAD and the current index\n\tcontents (the ones I'd write with a \"write-tree\")\n\nFor example, let's say that you have worked on your index file, and are\nready to commit. You want to see eactly _what_ you are going to commit is\nwithout having to write a new tree object and compare it that way, and to\ndo that, you just do\n\n\tdiff-cache --cached $(cat .git/HEAD)\n\nExample: let's say I had renamed \"commit.c\" to \"git-commit.c\", and I had \ndone an \"upate-cache\" to make that effective in the index file. \n\"show-diff\" wouldn't show anything at all, since the index file matches \nmy working directory. But doing a diff-cache does:\n\ttorvalds@ppc970:~/git> diff-cache --cached $(cat .git/HEAD)\n\t-100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c\n\t+100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c\n\nAnd as you can see, the output matches \"diff-tree -r\" output (we\nalways do \"-r\", since the index is always fully populated\n??CHECK??).\nYou can trivially see that the above is a rename.\n\nIn fact, \"diff-cache --cached\" _should_ always be entirely equivalent to\nactually doing a \"write-tree\" and comparing that. Except this one is much\nnicer for the case where you just want to check where you are.\n\nSo doing a \"diff-cache --cached\" is basically very useful when you are \nasking yourself \"what have I already marked for being committed, and \nwhat's the difference to a previous tree\".\n\nNon-cached Mode\n\nThe \"non-cached\" mode takes a different approach, and is potentially\nthe even more useful of the two in that what it does can't be emulated\nwith a \"write-tree + diff-tree\". Thus that's the default mode. The\nnon-cached version asks the question\n\n \"show me the differences between HEAD and the currently checked out \n tree - index contents _and_ files that aren't up-to-date\"\n\nwhich is obviously a very useful question too, since that tells you what\nyou _could_ commit. Again, the output matches the \"diff-tree -r\" output to\na tee, but with a twist.\n\nThe twist is that if some file doesn't match the cache, we don't have a\nbacking store thing for it, and we use the magic \"all-zero\" sha1 to show\nthat. So let's say that you have edited \"kernel/sched.c\", but have not\nactually done an update-cache on it yet - there is no \"object\" associated\nwith the new state, and you get:\n\n\ttorvalds@ppc970:~/v2.6/linux> diff-cache $(cat .git/HEAD )\n\t*100644->100664 blob 7476bbcfe5ef5a1dd87d745f298b831143e4d77e->0000000000000000000000000000000000000000 kernel/sched.c\n\nie it shows that the tree has changed, and that \"kernel/sched.c\" has is\nnot up-to-date and may contain new stuff. The all-zero sha1 means that to\nget the real diff, you need to look at the object in the working directory\ndirectly rather than do an object-to-object diff.\n\nNOTE! As with other commands of this type, \"diff-cache\" does not actually \nlook at the contents of the file at all. So maybe \"kernel/sched.c\" hasn't \nactually changed, and it's just that you touched it. In either case, it's \na note that you need to upate-cache it to make the cache be in sync.\n\nNOTE 2! You can have a mixture of files show up as \"has been updated\" and\n\"is still dirty in the working directory\" together. You can always tell\nwhich file is in which state, since the \"has been updated\" ones show a\nvalid sha1, and the \"not in sync with the index\" ones will always have the\nspecial all-zero sha1.\n\n################################################################\ndiff-tree\n\tdiff-tree [-r] [-z] \n\nCompares the content and mode of the blobs found via two tree objects.\n\nNote that diff-tree can use the tree encapsulated in a commit object.\n\n\n\tThe id of a tree or commit object.\n\n-r\n\trecurse\n\n-z\n\t\\0 line termination on output\n\nOutput format:\n\nFor files in tree1 but not in tree2\n-\\t \\t\t\\t\t\n\nFor files not in tree1 but in tree2\n+\\t \\t\t\\t\t\n\nFor files that differ:\n*->\\t \\t\t->\\t\t\n\n\nAn example of normal usage is:\n\n\ttorvalds@ppc970:~/git> diff-tree 5319e4d609cdd282069cc4dce33c1db559539b03 b4e628ea30d5ab3606119d2ea5caeab141d38df7\n\t*100664->100664 blob ac348b7d5278e9d04e3a1cd417389379c32b014f->a01513ed4d4d565911a60981bfb4173311ba3688 fsck-cache.c\n\nwhich tells you that the last commit changed just one file (it's from\nthis one:\n\n\tcommit 3c6f7ca19ad4043e9e72fa94106f352897e651a8\n\ttree 5319e4d609cdd282069cc4dce33c1db559539b03\n\tparent b4e628ea30d5ab3606119d2ea5caeab141d38df7\n\tauthor Linus Torvalds Sat Apr 9 12:02:30 2005\n\tcommitter Linus Torvalds Sat Apr 9 12:02:30 2005\n\n\tMake \"fsck-cache\" print out all the root commits it finds.\n\n\tOnce I do the reference tracking, I'll also make it print out all the\n\tHEAD commits it finds, which is even more interesting.\n\nin case you care).\n\n\n################################################################\nfsck-cache\n\tfsck-cache [[--unreachable] *]\n\nVerifies the connectivity and validity of the objects in the database.\n\n\n\tA commit object to treat as the head of an unreachability\n\ttrace\n\n--unreachable\n\tprint out objects that exist but that aren't readable from any\n\tof the specified root nodes\n\nIt tests SHA1 and general object sanity, but it does full tracking of\nthe resulting reachability and everything else. It prints out any\ncorruption it finds (missing or bad objects), and if you use the\n\"--unreachable\" flag it will also print out objects that exist but\nthat aren't readable from any of the specified root nodes.\n\nSo for example\n\n\tfsck-cache --unreachable $(cat .git/HEAD)\n\nor, for Cogito users:\n\n\tfsck-cache --unreachable $(cat .git/heads/*)\n\nwill do quite a _lot_ of verification on the tree. There are a few\nextra validity tests to be added (make sure that tree objects are\nsorted properly etc), but on the whole if \"fsck-cache\" is happy, you\ndo have a valid tree.\n\nAny corrupt objects you will have to find in backups or other archives\n(ie you can just remove them and do an \"rsync\" with some other site in\nthe hopes that somebody else has the object you have corrupted).\n\nOf course, \"valid tree\" doesn't mean that it wasn't generated by some\nevil person, and the end result might be crap. Git is a revision\ntracking system, not a quality assurance system ;)\n\nExtracted Diagnostics\n\nexpect dangling commits - potential heads - due to lack of head information\n\tYou haven't specified any nodes as heads so it won't be\n\tpossible to differentiate between un-parented commits and\n\troot nodes.\n\nmissing sha1 directory ''\n\tThe directory holding the sha1 objects is missing.\n\nunreachable \n\tThe object , isn't actually referred to directly\n\tor indirectly in any of the trees or commits seen. This can\n\tmean that there's another root na SHA1_ode that you're not specifying\n\tor that the tree is corrupt. If you haven't missed a root node\n\tthen you might as well delete unreachable nodes since they\n\tcan't be used.\n\nmissing \n\tThe object , is referred to but isn't present in\n\tthe database.\n\ndangling \n\tThe object , is present in the database but never\n\t_directly_ used. A dangling commit could be a root node.\n\nwarning: fsck-cache: tree has full pathnames in it\n\tAnd it shouldn't...\n\nsha1 mismatch \n\tThe database has an object who's sha1 doesn't match the\n\tdatabase value.\n\tThis indicates a ??serious?? data integrity problem.\n\t(note: this error occured during early git development when\n\tthe database format changed.)\n\nEnvironment Variables\n\nSHA1_FILE_DIRECTORY\n\tused to specify the object database root (usually .git/objects)\n\n################################################################\ngit-export\n\tgit-export top [base]\n\nprobably deprecated:\nOn Wed, 20 Apr 2005, Petr Baudis wrote:\n>> I will probably not buy git-export, though. (That is, it is merged, but\n>> I won't make git frontend for it.) My \"git export\" already does\n>> something different, but more importantly, \"git patch\" of mine already\n>> does effectively the same thing as you do, just for a single patch; so I\n>> will probably just extend it to do it for an (a,b] range of patches.\n\n\nThat's fine. It was a quick hack, just to show that if somebody wants to, \nthe data is trivially exportable.\n\n\t\tLinus\n\nAlthough in Linus' distribution show-diff is not part of 'core' git.\n\n################################################################\ninit-db\n\tinit-db\n\nThis simply creates an empty git object database - basically a .git\ndirectory.\n\nIf the object storage directory is specified via the\nSHA1_FILE_DIRECTORY environment variable then the sha1 directories are\ncreated underneath - otherwise the default .git/objects directory is\nused.\n\ninit-db won't hurt an existing repository.\n\n\n################################################################\nls-tree\n\tls-tree [-r] [-z] \n\nconvert the tree object to a human readable (and script\nprocessable) form.\n\n\n\tId of a tree or commit object.\n-r\n\trecurse into sub-trees\n\n-z\n\t\\0 line termination on output\n\nOutput Format\n\\t\t\\t\t\\t\t\t\n\n\n################################################################\nmerge-base\n\tmerge-base \n\nmerge-base finds one of the best common ancestors of a pair of commits. In\nparticular, it finds one of the ones which is fewest commits away from the\nfurther of the heads.\n\nWhen it has a tree with equally likely common ancestors like this:\n\n A -- C\n \\/ \\\n /\\ /\n B -- D\n\nIt essentially returns either A or B randomly.\n\nThe merge-base algorithm is still in flux.\n\n\n################################################################\nmerge-cache\n\tmerge-cache (-a | -- | *) \n\nThis looks up the (s) in the cache and, if there are any merge\nentries, unpacks all of them (which may be just one file, of course)\ninto up to three separate temporary files, and then executes the\nsupplied with those three files as arguments 1,2,3\n(empty argument if no file), and as argument 4.\n\n--\n\tInterpret all future arguments as filenames\n\n-a\n\tRun merge against all files in the cache that need merging.\n\nIf merge-cache is called with multiple s (or -a) then it\nprocesses them in turn only stopping if merge returns a non-zero exit\ncode.\n\nTypically this is run with the a script calling the merge command from\nthe RCS package.\n\nExample script:\n\n\t#!/bin/sh\n\t#\n\t# This is the git merge script, called with\n\t#\n\t# $1 - original file (or empty string)\n\t# $2 - file in branch1 (or empty string)\n\t# $3 - file in branch2 (or empty string)\n\t# $4 - pathname in repository\n\t#\n\t#\n\t# Case 1: file removed in both\n\t#\n\tif [ -z \"$2\" && -z \"$3\" ]; then\n\t\trm -- \"$4\"\n\t\tupdate-cache --remove -- \"$4\"\n\t\texit 0\n\tfi\n\t#\n\t# Case 2: file exists in just one\n\t#\n\tif [ -z \"$2\" || -z \"$3\" ] then\n\t\tcat \"$2\"\"$3\" > \"$4\"\n\t\tupdate-cache --add -- \"$4\"\n\t\texit 0\n\tfi\n\t#\n\t# Case 3: file exists in both\n\t#\n\tsrc=\"$1\"\n\tif [ -z \"$1\" ]; then\n\t\tsrc=/den/null\n\tfi\t\n\tmerge \"$3\" \"$src\" \"$2\" && cp \"$3\" \"$4\" && update-cache --add -- \"$4\"\n\nALERT ALERT ALERT! The git \"merge object order\" is different from the\nRCS \"merge\" program merge object order. In the above ordering, the\noriginal is first. But the argument order to the 3-way merge program\n\"merge\" is to have the original in the middle. Don't ask me why.\n\nExamples:\n\n\ttorvalds@ppc970:~/merge-test> merge-cache cat MM\n\tThis is MM from the original tree.\t\t\t# original\n\tThis is modified MM in the branch A.\t\t\t# merge1\n\tThis is modified MM in the branch B.\t\t\t# merge2\n\tThis is modified MM in the branch B.\t\t\t# current contents\n\nor \n\n\ttorvalds@ppc970:~/merge-test> merge-cache cat AA MM\n\tcat: : No such file or directory\n\tThis is added AA in the branch A.\n\tThis is added AA in the branch B.\n\tThis is added AA in the branch B.\n\tfatal: merge program failed\n\nwhere the latter example shows how \"merge-cache\" will stop trying to\nmerge once anything has returned an error (ie \"cat\" returned an error\nfor the AA file, because it didn't exist in the original, and thus\n\"merge-cache\" didn't even try to merge the MM thing).\n\n\n################################################################\nread-tree\n\tread-tree ( | -m [ ])\"\n\nReads the tree information given by into the directory cache,\nbut does not actually _update_ any of the files it \"caches\". (see:\ncheckout-cache)\n\nOptionally, it can merge a tree into the cache or perform a 3-way\nmerge.\n\nTrivial merges are done by read-tree itself. Only conflicting paths\nwill be in unmerged state when read-tree returns.\n\n-m\n\tPerform a merge, not just a read\n\n\n\tThe id of the tree object(s) to be read/merged.\n\n\nMerging\nIf -m is specified, read-tree performs 2 kinds of merge, a single tree\nmerge if only 1 tree is given or a 3-way merge if 3 trees are\nprovided.\n\nSingle Tree Merge\nIf only 1 tree is specified, read-tree operates as if the user did not\nspecify \"-m\", except that if the original cache has an entry for a\ngiven pathname; and the contents of the path matches with the tree\nbeing read, the stat info from the cache is used. (In other words, the\ncache's stat()s take precedence over the merged tree's)\n\nThat means that if you do a \"read-tree -m \" followed by a\n\"checkout-cache -f -a\", the checkout-cache only checks out the stuff\nthat really changed.\n\nThis is used to avoid unnecessary false hits when show-diff is\nrun after read-tree.\n\n3-Way Merge\nEach \"index\" entry has two bits worth of \"stage\" state. stage 0 is the\nnormal one, and is the only one you'd see in any kind of normal use.\n\nHowever, when you do \"read-tree\" with multiple trees, the \"stage\"\nstarts out at 0, but increments for each tree you read. And in\nparticular, the \"-m\" flag means \"start at stage 1\" instead.\n\nThis means that you can do\n\n\tread-tree -m \n\nand you will end up with an index with all of the entries in\n\"stage1\", all of the entries in \"stage2\" and all of the\n entries in \"stage3\".\n\nFurthermore, \"read-tree\" has special-case logic that says: if you see\na file that matches in all respects in the following states, it\n\"collapses\" back to \"stage0\":\n\n - stage 2 and 3 are the same; take one or the other (it makes no\n difference - the same work has been done on stage 2 and 3)\n\n - stage 1 and stage 2 are the same and stage 3 is different; take\n stage 3 (some work has been done on stage 3)\n\n - stage 1 and stage 3 are the same and stage 2 is different take\n stage 2 (some work has been done on stage 2)\n\nWrite-tree refuses to write a nonsensical tree, so write-tree will\ncomplain about unmerged entries if it sees a single entry that is not\nstage 0\".\n\nOk, this all sounds like a collection of totally nonsensical rules,\nbut it's actually exactly what you want in order to do a fast\nmerge. The different stages represent the \"result tree\" (stage 0, aka\n\"merged\"), the original tree (stage 1, aka \"orig\"), and the two trees\nyou are trying to merge (stage 2 and 3 respectively).\n\nIn fact, the way \"read-tree\" works, it's entirely agnostic about how\nyou assign the stages, and you could really assign them any which way,\nand the above is just a suggested way to do it (except since\n\"write-tree\" refuses to write anything but stage0 entries, it makes\nsense to always consider stage 0 to be the \"full merge\" state).\n\nSo what happens? Try it out. Select the original tree, and two trees\nto merge, and look how it works:\n\n - if a file exists in identical format in all three trees, it will \n automatically collapse to \"merged\" state by the new read-tree.\n\n - a file that has _any_ difference what-so-ever in the three trees\n will stay as separate entries in the index. It's up to \"script\n policy\" to determine how to remove the non-0 stages, and insert a\n merged version. But since the index is always sorted, they're easy\n to find: they'll be clustered together.\n\n - the index file saves and restores with all this information, so you\n can merge things incrementally, but as long as it has entries in\n stages 1/2/3 (ie \"unmerged entries\") you can't write the result.\n\nSo now the merge algorithm ends up being really simple:\n\n - you walk the index in order, and ignore all entries of stage 0,\n since they've already been done.\n\n - if you find a \"stage1\", but no matching \"stage2\" or \"stage3\", you\n know it's been removed from both trees (it only existed in the\n original tree), and you remove that entry. - if you find a\n matching \"stage2\" and \"stage3\" tree, you remove one of them, and\n turn the other into a \"stage0\" entry. Remove any matching \"stage1\"\n entry if it exists too. .. all the normal trivial rules ..\n\nIncidentally - it also means that you don't even have to have a separate \nsubdirectory for this. All the information literally is in the index file, \nwhich is a temporary thing anyway. There is no need to worry about what is in \nthe working directory, since it is never shown and never used.\n\nsee also:\nwrite-tree\nshow-files\n\n\n################################################################\nrev-tree\n\trev-tree [--edges] [--cache ] [^] [[^]]\n\nProvides the revision tree for one or more commits.\n\n--edges\n\tShow edges (ie places where the marking changes between parent\n\tand child)\n\n--cache \n\tUse the specified file as a cache. [Not implemented yet]\n\n[^]\n\tThe commit id to trace (a leading caret means to ignore this\n\tcommit-id and below)\n\nOutput:\n : [: ]*\n\n\n\tDate in 'seconds since epoch'\n\n\n\tid of commit object\n\n\n\tid of each parent commit object (>1 indicates a merge)\n\n\n\n\tThe flags are read as a bitmask representing each commit\n\tprovided on the commandline. eg: given the command:\n\n\t\t $ rev-tree \n\n\tThe output:\n\n\t :5\n\n\t means that is reachable from (1) and (4)\n\t\nA revtree can get quite large. rev-tree will eventually allow you to\ncache previous state so that you don't have to follow the whole thing\ndown.\n\nSo the change difference between two commits is literally\n\n\trev-tree [commit-id1] > commit1-revtree\n\trev-tree [commit-id2] > commit2-revtree\n\tjoin -t : commit1-revtree commit2-revtree > common-revisions\n\n(this is also how to find the most common parent - you'd look at just\nthe head revisions - the ones that aren't referred to by other\nrevisions - in \"common-revision\", and figure out the best one. I\nthink.)\n\n\n################################################################\nshow-diff\n\tshow-diff [-R] [-q] [-s] [-z] [paths...]\n\nShows the difference between the version of the specified file on disk\nand the file in the cache.\n\n-R\n\tReverse the diff\n\n-q\n\tReduce verbosity\n\n-s\n\tRemain silent even on nonexisting files (forces -q)\n\n-z\n\tMachine readable (including \\0 line termination on output)\n\t\n\nEnvironment variables\nGIT_DIFF_CMD\tDefault=\"diff -L 'a/%s' -L 'b/%s'\"\n\t\tCommand used to generate diff\n\nGIT_DIFF_OPTS\tDefault=\"-p -u\"\n\t\tOptions passed to diff command\n\nAlthough in Linus' distribution show-diff is not part of 'core' git.\n\n################################################################\nshow-files\n\tshow-files [-z] [-t] (--[cached|deleted|others|ignored|stage|unmerged])*\n\nThis merges the file listing in the directory cache index with the\nactual working directory list, and shows different combinations of the\ntwo.\n\nOne or more of the options below may be used to determine the files\nshown:\n\n--cached\n\tShow cached files in the output (default)\n\n--deleted\n\tShow deleted files in the output\n\n--others\n\tShow other files in the output\n\n--ignored\n\tShow ignored files in the output\n\n--stage\n\tShow stage files in the output\n\n--unmerged\n\tShow unmerged files in the output (forces --staged)\n\n-t\n\tShow the following tags (followed by a space) at the start of\n\teach line:\n\tH\tcached\n\tM\tunmerged\n\tR\tremoved/deleted\n\t?\tother\n\n-z\n\t\\0 line termination on output\n\nOutput\nshow files just outputs the filename unless --stage is specified in\nwhich case it outputs:\n\n[ ] \n\nshow-files --unmerged\" and \"show-files --stage \" can be used to examine\ndetailed information on unmerged paths.\n\nFor an unmerged path, instead of recording a single mode/SHA1 pair,\nthe dircache records up to three such pairs; one from tree O in stage\n1, A in stage 2, and B in stage 3. This information can be used by\nthe user (or Cogito) to see what should eventually be recorded at the\npath. (see read-cache for more information on state)\n\nsee also:\nread-cache\n\n\n################################################################\nunpack-file\n\tunpack-file \n\nCreates a file holding the contents of the blob specified by sha1. It\nreturns the name of the temporary file in the following format:\n\t.merge_file_XXXXX\n\n\n\tMust be a blob id\n\n################################################################\nupdate-cache\n\tupdate-cache [--add] [--remove] [--refresh] [--cacheinfo ]* [--] []*\n\nModifies the index or directory cache. Each file mentioned is updated\ninto the cache and any 'unmerged' or 'needs updating' state is\ncleared.\n\nThe way update-cache handles files it is told about can be modified\nusing the various options:\n\n--add\n\tIf a specified file isn't in the cache already then it's\n\tadded.\n\tDefault behaviour is to ignore new files.\n\n--remove\n\tIf a specified file is in the cache but is missing then it's\n\tremoved.\n\tDefault behaviour is to ignore removed file.\n\n--refresh\n\tLooks at the current cache and checks to see if merges or\n\tupdates are needed by checking stat() information.\n\n--cacheinfo \n\tDirectly insert the specified info into the cache.\n\t\n--\n\tDo not interpret any more arguments as options.\n\n\n\tFiles to act on.\n\tNote that files begining with '.' are discarded. This includes\n\t\"./file\" and \"dir/./file\". If you don't want this, then use\t\n\tcleaner names.\n\tThe same applies to directories ending '/' and paths with '//'\n\n\nUsing --refresh\n\n--refresh\" does not calculate a new sha1 file or bring the cache\nup-to-date for mode/content changes. But what it _does_ do is to\n\"re-match\" the stat information of a file with the cache, so that you\ncan refresh the cache for a file that hasn't been changed but where\nthe stat entry is out of date.\n\nFor example, you'd want to do this after doing a \"read-tree\", to link\nup the stat cache details with the proper files.\n\nUsing --cacheinfo\n--cacheinfo is used to register a file that is not in the current\nworking directory. This is useful for minimum-checkout merging.\n\nTo pretend you have a file with mode and sha1 at path, say:\n\n $ update-cache --cacheinfo mode sha1 path\n\n\n################################################################\nwrite-tree\n\twrite-tree\n\nCreates a tree object using the current cache.\n\nThe cache must be merged.\n\nConceptually, write-tree sync()s the current directory cache contents\ninto a set of tree files.\nIn order to have that match what is actually in your directory right\nnow, you need to have done a \"update-cache\" phase before you did the\n\"write-tree\".\n\n\n################################################################\n\n\nTerminology: - see README for description\nEach line contains terms used interchangeably\n\nobject database, .git directory\ndirectory cache, index\nid, sha1, sha1-id, sha1 hash\ntype, tag\nblob, blob object\ntree, tree object\ncommit, commit object\nparent\nroot object\nchangeset\n\n\ngit Environment Variables\nAUTHOR_NAME\nAUTHOR_EMAIL\nAUTHOR_DATE\nCOMMIT_AUTHOR_NAME\nCOMMIT_AUTHOR_EMAIL\nGIT_DIFF_CMD\nGIT_DIFF_OPTS\nGIT_INDEX_FILE\nSHA1_FILE_DIRECTORY\n\n"},{"id":"1548","messageId":"7vsm1fswb4.fsf@assigned-by-dhcp.cox.net","threadId":"293","inReplyTo":"426BF790.9070406@dgreaves.com","subject":"Re: [FILE] Docs update","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-04-24T21:23:59Z","receivedAt":"2005-04-24T21:23:59Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":">>>>> \"DG\" == David Greaves writes:\n\nLooking much better than before.\n\nDG> ################################################################\nDG> commit-tree\nDG> \tcommit-tree [-p ]* < changelog\nDG> Options\nDG> ...\nDG> -p \nDG> \tEach -p indicates a the id of a parent commit object.\n\nJust for consistency:\n\n commit-tree [-p ]* < changelog\n -p \n\t\nDG> ################################################################\nDG> git-export\nDG> \tgit-export top [base]\n\nDG> probably deprecated:\nDG> ...\nDG> Although in Linus' distribution show-diff is not part of 'core' git.\n\nPerhaps:\n\n Although in Linus' distribution, git-export is not part of 'core' git.\n\nDG> ################################################################\nDG> merge-base\nDG> \tmerge-base \nDG> ...\nDG> It essentially returns either A or B randomly.\n\nYou may want to check this with Daniel Barkalow; the commit ID\n0345fb64d68ba9e1e853c0ee9526fa93c45a67f9 is the latest one that\ntouches merge-base.c which has an extensive rework [*1*].\n\nDG> ################################################################\nDG> merge-cache\nDG> \tmerge-cache (-a | -- | *) \n\nDG> Typically this is run with the a script calling the merge command from\nDG> the RCS package.\n\nDG> Example script:\n\nDrop example script and refer the reader to git-merge-one-file-script. \nThe one you attached is already old and missing the last three\nparameter.\n\nAddition before rev-tree:\n\n rev-list \n\n Lists commit objects in reverse chronological order starting\n at the given commit, taking ancestry relationship into\n account. This is useful to produce human-readable log output.\n\nDG> ################################################################\nDG> show-diff\nDG> \tshow-diff [-R] [-q] [-s] [-z] [paths...]\n\nDG> Shows the difference between the version of the specified file on disk\nDG> and the file in the cache.\n\nDG> -R\nDG> \tReverse the diff\n\nDG> -q\nDG> \tReduce verbosity\n\nThis flag means \"Do not complain on non-existent files (i.e. a\ndircache entry is found but corresponding file is not in the\nworking tree).\n\nDG> -s\nDG> \tRemain silent even on nonexisting files (forces -q)\n\nThis flag means \"Do not show the diff text. Just output SHA1\nand name for changed paths.\" You are correct that this implies -q. \n\nDG> -z\nDG> \tMachine readable (including \\0 line termination on output)\n\t\nThis flag changes the behaviour of the program in number of\nsubtle ways for script consumption:\n\n -z\n Machine readable.\n\n . Each output record has the path name at the end of the\n record, instead of the front.\n . Each record is terminated with a NUL '\\0' character.\n . For unchanged files, nothing is output.\n . For an unmerged file, the following is output:\n U name\n . For a deleted file, the following is output:\n X name\n . For a modified file, the following is output:\n SHA1 name\n where SHA1 is from the dircache entry.\n\nDG> Although in Linus' distribution show-diff is not part of 'core' git.\n\nPerhaps:\n\n Although in Linus' distribution, show-diff is not part of 'core' git.\n\n\n[Footnotes]\n\n*1* Here is the jit-trackdown script to help you find out this\nkind of thing. Sample usage:\n\n $ jit-trackdown $(cat .git/heads/linus) merge-base.c\n\nSigned-off-by: Junio C Hamano \n---\ncat >jit-trackdown <<\\EOF\n#!/bin/sh\n\n# Usage: jit-trackdown paths...\n\ntmp=.jit-trackdown.$$\nhits=$tmp-hits\n\ntrap 'rm -f $tmp-*' 0 1 2 3 15\n\ntty -s || to_tty=:\n\nhead=\"$1\"\nshift\nrev-list \"$head\" |\nwhile read commit\ndo\n for p in $(cat-file commit \"$commit\" | sed -ne 's/^parent //p;/^$/q')\n do\n $to_tty echo >&2 -n .\n diff-tree -r -z \"$p\" \"$commit\" \"$@\" | jit-diff-tree-helper \"$@\" >$hits\n test -s \"$hits\" || continue;\n {\n\t $to_tty echo >&2\n\t echo \"commit $commit\"\n\t cat-file commit \"$commit\"\n\t echo\n\t cat \"$hits\"\n } | ${PAGER-less}\n case \"$to_tty\" in\n '')\n\t echo >&2 -n \"Dig further [Y/n]? \"\n\t read next &2\n\nEOF\ncat >jit-diff-tree-helper <<\\EOF\n#!/usr/bin/perl -w\n\nuse strict;\nuse File::Temp qw(mkstemp);\nuse Getopt::Long;\n\nmy $reverse_diff;\nGetOptions('reverse' => \\$reverse_diff)\n or die \"usage: $0 [ --reverse ] [paths...]\";\n\nsub cat_file {\n my ($sha1, $file) = @_;\n unless (defined $sha1) {\n\treturn (0, \"/dev/null\");\n }\n if ($sha1 =~ /^0{40}$/) {\n\treturn (0, $file);\n }\n local $/; # slurp mode\n open I, \"-|\", \"cat-file\", \"blob\", $sha1\n\tor die \"$0: cannot read $sha1\";\n my ($o, $filename) = mkstemp(\",,jit-diff-tree-helperXXXXXX\");\n print $o join(\"\",);\n close I\n\tor die \"$0: closing cat-file pipe from $sha1\";\n close $o\n\tor die \"$0: closing write fd to $filename\";\n return (1, $filename);\n}\n$/ = \"\\0\";\nmy $rM = \"[0-7]+\";\nmy $rI = \"[0-9a-f]{40}\";\nwhile () {\n my ($old, $new, $file, $o_is_temp, $n_is_temp);\n chomp;\n if (/^\\+$rM\\tblob\\t($rI)\\t(.*)$/os) {\n\t($old, $new, $file) = (undef, $1, $2);\n }\n elsif (/^-$rM\\tblob\\t($rI)\\t(.*)$/os) {\n\t($old, $new, $file) = ($1, undef, $2);\n }\n elsif (/^\\*$rM->$rM\\tblob\\t($rI)->($rI)\\t(.*)$/os) {\n\t($old, $new, $file) = ($1, $2, $3);\n }\n else {\n\tchomp;\n\tprint STDERR \"warning: $0: ignoring $_\\n\";\n\tnext;\n }\n if (@ARGV) {\n\tmy $matches = 0;\n\tfor (@ARGV) {\n\t my $l = length($_);\n\t if ($file eq $_ ||\n\t\t(substr($file, 0, $l) eq $_ &&\n\t\t substr($file, $l, 1) eq \"/\")) {\n\t\t$matches = 1;\n\t\tlast;\n\t }\n\t}\n\tnext unless $matches;\n }\n ($o_is_temp, $old) = cat_file $old, $file;\n ($n_is_temp, $new) = cat_file $new, $file;\n my @a = ($reverse_diff) ? ($new, $old) : ($old, $new);\n system \"diff\", \"-L\", \"k/$file\", \"-L\", \"l/$file\", \"-pu\", @a;\n unlink $old if ($o_is_temp);\n unlink $new if ($n_is_temp);\n}\nEOF\nchmod +x jit-trackdown jit-diff-tree-helper\n\n\n"},{"id":"1552","messageId":"Pine.LNX.4.58.0504241438280.15879@ppc970.osdl.org","threadId":"293","inReplyTo":"426BF790.9070406@dgreaves.com","subject":"Re: [FILE] Docs update","fromName":"Linus Torvalds","fromEmail":"torvalds@osdl.org","sentAt":"2005-04-24T21:44:40Z","receivedAt":"2005-04-24T21:44:40Z","isPatch":false,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Sun, 24 Apr 2005, David Greaves wrote:\n> \n> And I've attached this as a file rather than a patch to make it easier \n> for people to read.\n\nSuggestion: move \"diff-tree\" up above \"diff-cache\", since as it is now, \nyou explain \"diff-cache\" in terms of diff-tree, before you've even \nexplained diff-tree in the first place.\n\nAlso, the current diff-tree has an extension:\n\n\t################################################################\n\tdiff-tree\n\t diff-tree [-r] [-z] [pattern]*\n\n\tCompares the content and mode of the blobs found via two tree objects.\n\nwhere the \"pattern\" arguments are the pathnames you are interested in \nseeing the differences of.\n\nFor example, if you're only interested in differences in some\narchitecture-specific files, you might do\n\n\tdiff-tree -r arch/ia64 include/asm-ia64\n\nand it will only show you what changed in those two directories.\n\nOr if you are searching for what changed in just kernel/sched.c, just do\n\n\tdiff-tree -r kernel/sched.c\n\nand it will ignore all differences to other files.\n\nThe pattern is always the prefix, and is matched exactly (ie there are no\nwildcards - although matching a directory, which it does support, can\nobviously be seen as a \"wildcard\" for all the files under that directory).\n\n\t\tLinus\n"},{"id":"1574","messageId":"Pine.LNX.4.21.0504242112190.30848-100000@iabervon.org","threadId":"293","inReplyTo":"426BF790.9070406@dgreaves.com","subject":"Re: [FILE] Docs update","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2005-04-25T01:34:54Z","receivedAt":"2005-04-25T01:34:54Z","isPatch":false,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"The current merge-base finds the common ancestor with the most recent\ndate. The old algorithm was giving some surprising results, where it\ndidn't always take advantage of a straight line from one side to the\nother. At some point, I'm going to try to have it find the ancestor with\nthe shortest shorter path, which I think should work best of all.\n\nIn any case, I think your documentation should just say it finds as good a\ncommon ancestor as possible, since that's what it's really for, regardless\nof the details of how it decides. Also, it shouldn't be depended on to\ndecide in any particular way.\n\n\t-Daniel\n*This .sig left intentionally blank*\n\n"},{"id":"1859","messageId":"426F7B7C.3060407@dgreaves.com","threadId":"293","inReplyTo":"Pine.LNX.4.58.0504241438280.15879@ppc970.osdl.org","subject":"Re: [FILE] Docs update","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-04-27T11:46:04Z","receivedAt":"2005-04-27T11:46:04Z","isPatch":false,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"Linus Torvalds wrote:\n\n>On Sun, 24 Apr 2005, David Greaves wrote:\n> \n>\n>>And I've attached this as a file rather than a patch to make it easier \n>>for people to read.\n>> \n>>\n>Suggestion: move \"diff-tree\" up above \"diff-cache\", since as it is now, \n>you explain \"diff-cache\" in terms of diff-tree, before you've even \n>explained diff-tree in the first place.\n> \n>\nYes, but this isn't a tutorial.\nIdeally it'll become man pages (the chatty kind)\nFor now keeping it in alphabetical order is probably easier for people \nlooking for info on a particular command - and I've updated the 'see \ndiff-tree' comment to point people forward. OK?\n\n>Also, the current diff-tree has an extension:\n> \n>\nadded.\nI've also incorporated comments from Junio and Daniel.\n\nI know pasky accepted an early version into his tree but now it's purely \ncore-git, it would be nice to get it into your tree.\n\nWhat I propose is that you accept it as-is and then it would seem \nreasonable for you to ask for relevant patches to include changes to the \ndocs before you finally push them.\n\nThey don't have to be perfect - no need to patch the synopsis or args \nspec; just some explanatory text - I'll keep an eye on it and fix up the \nediting. And if you're really lazy and just commit with a 'docs need \nupdating' or something then I guess I can catch that... eventually. And \nI'll take care of the rename too when it happens.\n\nAnd yes, I know it's now out-of-date (it is 3 days old!!) - so part 2 of \nmy proposal is that I'll continue to send more patches for the missing \ncommands and I'll also send patches to the code to bring the usage() \ntext in line with the consistent terminology used in the docs.\n\nAnd since it's not used, how would you feel about making all the \ncommands take a -h and returning the usage and possibly a synopsis?\nI could patch that in at the same time as I consistency-ise all the \nusage strings.\n\nDavid\n\n\nReference documentation for the core git commands.\n\nSigned-off-by: David Greaves \n---\n\n\n\nThis file contains reference information for the core git commands.\nIt is actually based on the source from Petr Baudis' tree and may\ntherefore contain a few 'extras' that may or may not make it upstream.\n\nThe README contains much useful definition and clarification info -\nread that first. And of the commands, I suggest reading\n'update-cache' and 'read-tree' first - I wish I had!\n\nThanks to original email authors and proof readers esp Junio C Hamano\n\n\nDavid Greaves \n24/4/05\n\nIdentifier terminology used:\n\n\n\tIndicates any object sha1 identifier\n\n\n\tIndicates a blob object sha1 identifier\n\n\n\tIndicates a tree object sha1 identifier\n\n\n\tIndicates a commit object sha1 identifier\n\n\n\tIndicates a tree or commit object sha1 identifier (usually\n\tbecause the command can read the a contains).\n\t[Eventually may be replaced with if means\n\t in all commands]\n\n\n\tIndicates that an object type is required.\n\tCurrently one of: blob/tree/commit\n\n\n\tIndicates a filename - often includes leading path\n\n\n\tIndicates the path of a file (is this ever useful?)\n\n\n\n################################################################\ncat-file\n\tcat-file (-t | ) \n\nProvide contents or type of objects in the repository. The type is\nrequired if -t is not being used to find the object type.\n\n\n\tThe sha1 identifier of the object.\n\n-t\n\tshow the object type identified by \n\n\n\tOne of: blob/tree/commit\n\nOutput\n\nIf -t is specified, one of:\n blob/tree/commit\n\nOtherwise the raw (though uncompressed) contents of the will\nbe returned.\n\n\n################################################################\ncheck-files\n\tcheck-files ...\n\nCheck that a list of files are up-to-date between the filesystem and\nthe cache. Used to verify a patch target before doing a patch.\n\nFiles that do not exist on the filesystem are considered up-to-date\n(whether or not they are in the cache).\n\nEmits an error message on failure.\npreparing to update existing file not in cache\n\t exists but is not in the cache\n\npreparing to update file not uptodate in cache\n\t on disk is not up-to-date with the cache\n\nexits with a status code indicating success if all files are\nup-to-date.\n\nsee also: update-cache\n\n\n################################################################\ncheckout-cache\n\tcheckout-cache [-q] [-a] [-f] [-n] [--prefix=]\n\t\t [--] ...\n\nWill copy all files listed from the cache to the working directory\n(not overwriting existing files). Note that the file contents are\nrestored - NOT the file permissions.\n\n-q\n\tbe quiet if files exist or are not in the cache\n\n-f\n\tforces overwrite of existing files\n\n-a\n\tchecks out all files in the cache (will then continue to\n\tprocess listed files).\n-n\n\tDon't checkout new files, only refresh files already checked\n\tout.\n\n--prefix=\n\tWhen creating files, prepend (usually a directory\n\tincluding a trailing /)\n\n--\n\tDo not interpret any more arguments as options.\n\nNote that the order of the flags matters:\n\n\tcheckout-cache -a -f file.c\n\nwill first check out all files listed in the cache (but not overwrite\nany old ones), and then force-checkout file.c a second time (ie that\none _will_ overwrite any old contents with the same filename).\n\nAlso, just doing \"checkout-cache\" does nothing. You probably meant\n\"checkout-cache -a\". And if you want to force it, you want\n\"checkout-cache -f -a\".\n\nIntuitiveness is not the goal here. Repeatability is. The reason for\nthe \"no arguments means no work\" thing is that from scripts you are\nsupposed to be able to do things like\n\n\tfind . -name '*.h' -print0 | xargs -0 checkout-cache -f --\n\nwhich will force all existing *.h files to be replaced with their\ncached copies. If an empty command line implied \"all\", then this would\nforce-refresh everything in the cache, which was not the point.\n\nTo update and refresh only the files already checked out:\n\n checkout-cache -n -f -a && update-cache --ignore-missing --refresh\n\nOh, and the \"--\" is just a good idea when you know the rest will be\nfilenames. Just so that you wouldn't have a filename of \"-a\" causing\nproblems (not possible in the above example, but get used to it in\nscripting!).\n\nThe prefix ability basically makes it trivial to use checkout-cache as\na \"export as tree\" function. Just read the desired tree into the\nindex, and do a\n \n checkout-cache --prefix=export-dir/ -a\n \nand checkout-cache will \"export\" the cache into the specified\ndirectory.\n \nNOTE! The final \"/\" is important. The exported name is literally just\nprefixed with the specified string, so you can also do something like\n \n checkout-cache --prefix=.merged- Makefile\n \nto check out the currently cached copy of \"Makefile\" into the file\n\".merged-Makefile\".\n\n\n################################################################\ncommit-tree\n\tcommit-tree [-p ]* < changelog\n\nCreates a new commit object based on the provided tree object and\nemits the new commit object id on stdout. If no parent is given then\nit is considered to be an initial tree.\n\nA commit object usually has 1 parent (a commit after a change) or up\nto 16 parents. More than one parent represents a merge of branches\nthat led to them.\n\nWhile a tree represents a particular directory state of a working\ndirectory, a commit represents that state in \"time\", and explains how\nto get there.\n\nNormally a commit would identify a new \"HEAD\" state, and while git\ndoesn't care where you save the note about that state, in practice we\ntend to just write the result to the file \".git/HEAD\", so that we can\nalways see what the last committed state was.\n\nOptions\n\n\n\tAn existing tree object\n\n-p \n\tEach -p indicates a the id of a parent commit object.\n\t\n\nCommit Information\n\nA commit encapsulates:\n\tall parent object ids\n\tauthor name, email and date\n\tcommitter name and email and the commit time.\n\nIf not provided, commit-tree uses your name, hostname and domain to\nprovide author and committer info. This can be overridden using the\nfollowing environment variables.\n\tAUTHOR_NAME\n\tAUTHOR_EMAIL\n\tAUTHOR_DATE\n\tCOMMIT_AUTHOR_NAME\n\tCOMMIT_AUTHOR_EMAIL\n(nb <,> and '\\n's are stripped)\n\nA commit comment is read from stdin (max 999 chars). If a changelog\nentry is not provided via '<' redirection, commit-tree will just wait\nfor one to be entered and terminated with ^D\n\nsee also: write-tree\n\n\n################################################################\ndiff-cache\n\tdiff-cache [-r] [-z] [--cached] \n\nCompares the content and mode of the blobs found via a tree object\nwith the content of the current cache and, optionally ignoring the\nstat state of the file on disk.\n\n(This is basically a special case of diff-tree that works with the\ncurrent cache as the first tree - see diff-tree for more details)\n\n\n\tThe id of a tree or commit object to diff against.\n\n-r\n\trecurse\n\n-z\n\t\\0 line termination on output\n\n--cached\n\tdo not consider the on-disk file at all\n\nOutput format:\n\nFor files in the tree but not in the cache\n-\\t \\t\t\\t\t\n\nFor files in the cache but not in the tree\n+\\t \\t\t\\t\t\n\nFor files that differ:\n*->\\t \\t\t->\\t\t\n\nIn the special case of the file being changed on disk and out of sync\nwith the cache, the sha1 is all 0's. Example:\n\n\t*100644->100660 blob 5be4a414b32cf4204f889469942986d3d783da84->0000000000000000000000000000000000000000 file.c\n\t\n\nOperating Modes\n\nYou can choose whether you want to trust the index file entirely\n(using the \"--cached\" flag) or ask the diff logic to show any files\nthat don't match the stat state as being \"tentatively changed\". Both\nof these operations are very useful indeed.\n\nCached Mode\n\nIf --cached is specified, it allows you to ask:\n\tshow me the differences between HEAD and the current index\n\tcontents (the ones I'd write with a \"write-tree\")\n\nFor example, let's say that you have worked on your index file, and are\nready to commit. You want to see eactly _what_ you are going to commit is\nwithout having to write a new tree object and compare it that way, and to\ndo that, you just do\n\n\tdiff-cache --cached $(cat .git/HEAD)\n\nExample: let's say I had renamed \"commit.c\" to \"git-commit.c\", and I had \ndone an \"upate-cache\" to make that effective in the index file. \n\"show-diff\" wouldn't show anything at all, since the index file matches \nmy working directory. But doing a diff-cache does:\n\ttorvalds@ppc970:~/git> diff-cache --cached $(cat .git/HEAD)\n\t-100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c\n\t+100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 git-commit.c\n\nAnd as you can see, the output matches \"diff-tree -r\" output (we\nalways do \"-r\", since the index is always fully populated\n??CHECK??).\nYou can trivially see that the above is a rename.\n\nIn fact, \"diff-cache --cached\" _should_ always be entirely equivalent to\nactually doing a \"write-tree\" and comparing that. Except this one is much\nnicer for the case where you just want to check where you are.\n\nSo doing a \"diff-cache --cached\" is basically very useful when you are \nasking yourself \"what have I already marked for being committed, and \nwhat's the difference to a previous tree\".\n\nNon-cached Mode\n\nThe \"non-cached\" mode takes a different approach, and is potentially\nthe even more useful of the two in that what it does can't be emulated\nwith a \"write-tree + diff-tree\". Thus that's the default mode. The\nnon-cached version asks the question\n\n \"show me the differences between HEAD and the currently checked out \n tree - index contents _and_ files that aren't up-to-date\"\n\nwhich is obviously a very useful question too, since that tells you what\nyou _could_ commit. Again, the output matches the \"diff-tree -r\" output to\na tee, but with a twist.\n\nThe twist is that if some file doesn't match the cache, we don't have a\nbacking store thing for it, and we use the magic \"all-zero\" sha1 to show\nthat. So let's say that you have edited \"kernel/sched.c\", but have not\nactually done an update-cache on it yet - there is no \"object\" associated\nwith the new state, and you get:\n\n\ttorvalds@ppc970:~/v2.6/linux> diff-cache $(cat .git/HEAD )\n\t*100644->100664 blob 7476bbcfe5ef5a1dd87d745f298b831143e4d77e->0000000000000000000000000000000000000000 kernel/sched.c\n\nie it shows that the tree has changed, and that \"kernel/sched.c\" has is\nnot up-to-date and may contain new stuff. The all-zero sha1 means that to\nget the real diff, you need to look at the object in the working directory\ndirectly rather than do an object-to-object diff.\n\nNOTE! As with other commands of this type, \"diff-cache\" does not actually \nlook at the contents of the file at all. So maybe \"kernel/sched.c\" hasn't \nactually changed, and it's just that you touched it. In either case, it's \na note that you need to upate-cache it to make the cache be in sync.\n\nNOTE 2! You can have a mixture of files show up as \"has been updated\" and\n\"is still dirty in the working directory\" together. You can always tell\nwhich file is in which state, since the \"has been updated\" ones show a\nvalid sha1, and the \"not in sync with the index\" ones will always have the\nspecial all-zero sha1.\n\n################################################################\ndiff-tree\n\tdiff-tree [-r] [-z] []*\n\nCompares the content and mode of the blobs found via two tree objects.\n\nNote that diff-tree can use the tree encapsulated in a commit object.\n\n\n\tThe id of a tree or commit object.\n\n\n\n\tIf provided, the results are limited to a subset of files\n\tmatching one of these prefix strings.\n\tie file matches /^||.../\n\tNote that pattern does not provide any wildcard or regexp features.\n\n-r\n\trecurse\n\n-z\n\t\\0 line termination on output\n\nLimiting Output\n\nIf you're only interested in differences in a subset of files, for\nexample some architecture-specific files, you might do:\n\n\tdiff-tree -r arch/ia64 include/asm-ia64\n\nand it will only show you what changed in those two directories.\n\nOr if you are searching for what changed in just kernel/sched.c, just do\n\n\tdiff-tree -r kernel/sched.c\n\nand it will ignore all differences to other files.\n\nThe pattern is always the prefix, and is matched exactly (ie there are no\nwildcards - although matching a directory, which it does support, can\nobviously be seen as a \"wildcard\" for all the files under that directory).\n\nOutput format:\n\nFor files in tree1 but not in tree2\n-\\t \\t\t\\t\t\n\nFor files not in tree1 but in tree2\n+\\t \\t\t\\t\t\n\nFor files that differ:\n*->\\t \\t\t->\\t\t\n\n\nAn example of normal usage is:\n\n\ttorvalds@ppc970:~/git> diff-tree 5319e4d609cdd282069cc4dce33c1db559539b03 b4e628ea30d5ab3606119d2ea5caeab141d38df7\n\t*100664->100664 blob ac348b7d5278e9d04e3a1cd417389379c32b014f->a01513ed4d4d565911a60981bfb4173311ba3688 fsck-cache.c\n\nwhich tells you that the last commit changed just one file (it's from\nthis one:\n\n\tcommit 3c6f7ca19ad4043e9e72fa94106f352897e651a8\n\ttree 5319e4d609cdd282069cc4dce33c1db559539b03\n\tparent b4e628ea30d5ab3606119d2ea5caeab141d38df7\n\tauthor Linus Torvalds Sat Apr 9 12:02:30 2005\n\tcommitter Linus Torvalds Sat Apr 9 12:02:30 2005\n\n\tMake \"fsck-cache\" print out all the root commits it finds.\n\n\tOnce I do the reference tracking, I'll also make it print out all the\n\tHEAD commits it finds, which is even more interesting.\n\nin case you care).\n\n\n################################################################\nfsck-cache\n\tfsck-cache [[--unreachable] *]\n\nVerifies the connectivity and validity of the objects in the database.\n\n\n\tA commit object to treat as the head of an unreachability\n\ttrace\n\n--unreachable\n\tprint out objects that exist but that aren't readable from any\n\tof the specified root nodes\n\nIt tests SHA1 and general object sanity, but it does full tracking of\nthe resulting reachability and everything else. It prints out any\ncorruption it finds (missing or bad objects), and if you use the\n\"--unreachable\" flag it will also print out objects that exist but\nthat aren't readable from any of the specified root nodes.\n\nSo for example\n\n\tfsck-cache --unreachable $(cat .git/HEAD)\n\nor, for Cogito users:\n\n\tfsck-cache --unreachable $(cat .git/heads/*)\n\nwill do quite a _lot_ of verification on the tree. There are a few\nextra validity tests to be added (make sure that tree objects are\nsorted properly etc), but on the whole if \"fsck-cache\" is happy, you\ndo have a valid tree.\n\nAny corrupt objects you will have to find in backups or other archives\n(ie you can just remove them and do an \"rsync\" with some other site in\nthe hopes that somebody else has the object you have corrupted).\n\nOf course, \"valid tree\" doesn't mean that it wasn't generated by some\nevil person, and the end result might be crap. Git is a revision\ntracking system, not a quality assurance system ;)\n\nExtracted Diagnostics\n\nexpect dangling commits - potential heads - due to lack of head information\n\tYou haven't specified any nodes as heads so it won't be\n\tpossible to differentiate between un-parented commits and\n\troot nodes.\n\nmissing sha1 directory ''\n\tThe directory holding the sha1 objects is missing.\n\nunreachable \n\tThe object , isn't actually referred to directly\n\tor indirectly in any of the trees or commits seen. This can\n\tmean that there's another root na SHA1_ode that you're not specifying\n\tor that the tree is corrupt. If you haven't missed a root node\n\tthen you might as well delete unreachable nodes since they\n\tcan't be used.\n\nmissing \n\tThe object , is referred to but isn't present in\n\tthe database.\n\ndangling \n\tThe object , is present in the database but never\n\t_directly_ used. A dangling commit could be a root node.\n\nwarning: fsck-cache: tree has full pathnames in it\n\tAnd it shouldn't...\n\nsha1 mismatch \n\tThe database has an object who's sha1 doesn't match the\n\tdatabase value.\n\tThis indicates a ??serious?? data integrity problem.\n\t(note: this error occured during early git development when\n\tthe database format changed.)\n\nEnvironment Variables\n\nSHA1_FILE_DIRECTORY\n\tused to specify the object database root (usually .git/objects)\n\n################################################################\ngit-export\n\tgit-export top [base]\n\nprobably deprecated:\nOn Wed, 20 Apr 2005, Petr Baudis wrote:\n>> I will probably not buy git-export, though. (That is, it is merged, but\n>> I won't make git frontend for it.) My \"git export\" already does\n>> something different, but more importantly, \"git patch\" of mine already\n>> does effectively the same thing as you do, just for a single patch; so I\n>> will probably just extend it to do it for an (a,b] range of patches.\n\n\nThat's fine. It was a quick hack, just to show that if somebody wants to, \nthe data is trivially exportable.\n\n\t\tLinus\n\nAlthough in Linus' distribution, git-export is not part of 'core' git.\n\n################################################################\ninit-db\n\tinit-db\n\nThis simply creates an empty git object database - basically a .git\ndirectory.\n\nIf the object storage directory is specified via the\nSHA1_FILE_DIRECTORY environment variable then the sha1 directories are\ncreated underneath - otherwise the default .git/objects directory is\nused.\n\ninit-db won't hurt an existing repository.\n\n\n################################################################\nls-tree\n\tls-tree [-r] [-z] \n\nconvert the tree object to a human readable (and script\nprocessable) form.\n\n\n\tId of a tree or commit object.\n-r\n\trecurse into sub-trees\n\n-z\n\t\\0 line termination on output\n\nOutput Format\n\\t\t\\t\t\\t\t\t\n\n\n################################################################\nmerge-base\n\tmerge-base \n\nmerge-base finds as good a common ancestor as possible. Given a\nselection of equally good common ancestors it should not be relied on\nto decide in any particular way.\n\nThe merge-base algorithm is still in flux - use the source...\n\n\n################################################################\nmerge-cache\n\tmerge-cache (-a | -- | *) \n\nThis looks up the (s) in the cache and, if there are any merge\nentries, unpacks all of them (which may be just one file, of course)\ninto up to three separate temporary files, and then executes the\nsupplied with those three files as arguments 1,2,3\n(empty argument if no file), and as argument 4.\n\n--\n\tInterpret all future arguments as filenames\n\n-a\n\tRun merge against all files in the cache that need merging.\n\nIf merge-cache is called with multiple s (or -a) then it\nprocesses them in turn only stopping if merge returns a non-zero exit\ncode.\n\nTypically this is run with the a script calling the merge command from\nthe RCS package.\n\nA sample script called git-merge-one-file-script is included in the\nditribution.\n\nALERT ALERT ALERT! The git \"merge object order\" is different from the\nRCS \"merge\" program merge object order. In the above ordering, the\noriginal is first. But the argument order to the 3-way merge program\n\"merge\" is to have the original in the middle. Don't ask me why.\n\nExamples:\n\n\ttorvalds@ppc970:~/merge-test> merge-cache cat MM\n\tThis is MM from the original tree.\t\t\t# original\n\tThis is modified MM in the branch A.\t\t\t# merge1\n\tThis is modified MM in the branch B.\t\t\t# merge2\n\tThis is modified MM in the branch B.\t\t\t# current contents\n\nor \n\n\ttorvalds@ppc970:~/merge-test> merge-cache cat AA MM\n\tcat: : No such file or directory\n\tThis is added AA in the branch A.\n\tThis is added AA in the branch B.\n\tThis is added AA in the branch B.\n\tfatal: merge program failed\n\nwhere the latter example shows how \"merge-cache\" will stop trying to\nmerge once anything has returned an error (ie \"cat\" returned an error\nfor the AA file, because it didn't exist in the original, and thus\n\"merge-cache\" didn't even try to merge the MM thing).\n\n\n################################################################\nread-tree\n\tread-tree ( | -m [ ])\"\n\nReads the tree information given by into the directory cache,\nbut does not actually _update_ any of the files it \"caches\". (see:\ncheckout-cache)\n\nOptionally, it can merge a tree into the cache or perform a 3-way\nmerge.\n\nTrivial merges are done by read-tree itself. Only conflicting paths\nwill be in unmerged state when read-tree returns.\n\n-m\n\tPerform a merge, not just a read\n\n\n\tThe id of the tree object(s) to be read/merged.\n\n\nMerging\nIf -m is specified, read-tree performs 2 kinds of merge, a single tree\nmerge if only 1 tree is given or a 3-way merge if 3 trees are\nprovided.\n\nSingle Tree Merge\nIf only 1 tree is specified, read-tree operates as if the user did not\nspecify \"-m\", except that if the original cache has an entry for a\ngiven pathname; and the contents of the path matches with the tree\nbeing read, the stat info from the cache is used. (In other words, the\ncache's stat()s take precedence over the merged tree's)\n\nThat means that if you do a \"read-tree -m \" followed by a\n\"checkout-cache -f -a\", the checkout-cache only checks out the stuff\nthat really changed.\n\nThis is used to avoid unnecessary false hits when show-diff is\nrun after read-tree.\n\n3-Way Merge\nEach \"index\" entry has two bits worth of \"stage\" state. stage 0 is the\nnormal one, and is the only one you'd see in any kind of normal use.\n\nHowever, when you do \"read-tree\" with multiple trees, the \"stage\"\nstarts out at 0, but increments for each tree you read. And in\nparticular, the \"-m\" flag means \"start at stage 1\" instead.\n\nThis means that you can do\n\n\tread-tree -m \n\nand you will end up with an index with all of the entries in\n\"stage1\", all of the entries in \"stage2\" and all of the\n entries in \"stage3\".\n\nFurthermore, \"read-tree\" has special-case logic that says: if you see\na file that matches in all respects in the following states, it\n\"collapses\" back to \"stage0\":\n\n - stage 2 and 3 are the same; take one or the other (it makes no\n difference - the same work has been done on stage 2 and 3)\n\n - stage 1 and stage 2 are the same and stage 3 is different; take\n stage 3 (some work has been done on stage 3)\n\n - stage 1 and stage 3 are the same and stage 2 is different take\n stage 2 (some work has been done on stage 2)\n\nWrite-tree refuses to write a nonsensical tree, so write-tree will\ncomplain about unmerged entries if it sees a single entry that is not\nstage 0\".\n\nOk, this all sounds like a collection of totally nonsensical rules,\nbut it's actually exactly what you want in order to do a fast\nmerge. The different stages represent the \"result tree\" (stage 0, aka\n\"merged\"), the original tree (stage 1, aka \"orig\"), and the two trees\nyou are trying to merge (stage 2 and 3 respectively).\n\nIn fact, the way \"read-tree\" works, it's entirely agnostic about how\nyou assign the stages, and you could really assign them any which way,\nand the above is just a suggested way to do it (except since\n\"write-tree\" refuses to write anything but stage0 entries, it makes\nsense to always consider stage 0 to be the \"full merge\" state).\n\nSo what happens? Try it out. Select the original tree, and two trees\nto merge, and look how it works:\n\n - if a file exists in identical format in all three trees, it will \n automatically collapse to \"merged\" state by the new read-tree.\n\n - a file that has _any_ difference what-so-ever in the three trees\n will stay as separate entries in the index. It's up to \"script\n policy\" to determine how to remove the non-0 stages, and insert a\n merged version. But since the index is always sorted, they're easy\n to find: they'll be clustered together.\n\n - the index file saves and restores with all this information, so you\n can merge things incrementally, but as long as it has entries in\n stages 1/2/3 (ie \"unmerged entries\") you can't write the result.\n\nSo now the merge algorithm ends up being really simple:\n\n - you walk the index in order, and ignore all entries of stage 0,\n since they've already been done.\n\n - if you find a \"stage1\", but no matching \"stage2\" or \"stage3\", you\n know it's been removed from both trees (it only existed in the\n original tree), and you remove that entry. - if you find a\n matching \"stage2\" and \"stage3\" tree, you remove one of them, and\n turn the other into a \"stage0\" entry. Remove any matching \"stage1\"\n entry if it exists too. .. all the normal trivial rules ..\n\nIncidentally - it also means that you don't even have to have a separate \nsubdirectory for this. All the information literally is in the index file, \nwhich is a temporary thing anyway. There is no need to worry about what is in \nthe working directory, since it is never shown and never used.\n\nsee also:\nwrite-tree\nshow-files\n\n\n################################################################\nrev-list \n\nLists commit objects in reverse chronological order starting at the\ngiven commit, taking ancestry relationship into account. This is\nuseful to produce human-readable log output.\n\n\n################################################################\nrev-tree\n\trev-tree [--edges] [--cache ] [^] [[^]]\n\nProvides the revision tree for one or more commits.\n\n--edges\n\tShow edges (ie places where the marking changes between parent\n\tand child)\n\n--cache \n\tUse the specified file as a cache. [Not implemented yet]\n\n[^]\n\tThe commit id to trace (a leading caret means to ignore this\n\tcommit-id and below)\n\nOutput:\n : [: ]*\n\n\n\tDate in 'seconds since epoch'\n\n\n\tid of commit object\n\n\n\tid of each parent commit object (>1 indicates a merge)\n\n\n\n\tThe flags are read as a bitmask representing each commit\n\tprovided on the commandline. eg: given the command:\n\n\t\t $ rev-tree \n\n\tThe output:\n\n\t :5\n\n\t means that is reachable from (1) and (4)\n\t\nA revtree can get quite large. rev-tree will eventually allow you to\ncache previous state so that you don't have to follow the whole thing\ndown.\n\nSo the change difference between two commits is literally\n\n\trev-tree [commit-id1] > commit1-revtree\n\trev-tree [commit-id2] > commit2-revtree\n\tjoin -t : commit1-revtree commit2-revtree > common-revisions\n\n(this is also how to find the most common parent - you'd look at just\nthe head revisions - the ones that aren't referred to by other\nrevisions - in \"common-revision\", and figure out the best one. I\nthink.)\n\n\n################################################################\nshow-diff\n\tshow-diff [-R] [-q] [-s] [-z] [paths...]\n\nShows the difference between the version of the specified file on disk\nand the file in the cache.\n\n-R\n\tReverse the diff\n\n-q\n\tRemain silent even on nonexisting files\n\n-s\n\tDo not show the diff text. Just output SHA1 and name for\n\tchanged paths (forces -q)\n\n-z\n\tMachine readable output: \n . Each output record has the path name at the end of the\n record, instead of the front.\n . Each record is terminated with a NUL '\\0' character.\n . For unchanged files, nothing is output.\n . For an unmerged file, the following is output:\n U name\n . For a deleted file, the following is output:\n X name\n . For a modified file, the following is output:\n SHA1 name\n where SHA1 is from the dircache entry.\n\nEnvironment variables\nGIT_DIFF_CMD\tDefault=\"diff -L 'a/%s' -L 'b/%s'\"\n\t\tCommand used to generate diff\n\nGIT_DIFF_OPTS\tDefault=\"-p -u\"\n\t\tOptions passed to diff command\n\nAlthough in Linus' distribution, show-diff is not part of 'core' git.\n\n################################################################\nshow-files\n\tshow-files [-z] [-t] (--[cached|deleted|others|ignored|stage|unmerged])*\n\nThis merges the file listing in the directory cache index with the\nactual working directory list, and shows different combinations of the\ntwo.\n\nOne or more of the options below may be used to determine the files\nshown:\n\n--cached\n\tShow cached files in the output (default)\n\n--deleted\n\tShow deleted files in the output\n\n--others\n\tShow other files in the output\n\n--ignored\n\tShow ignored files in the output\n\n--stage\n\tShow stage files in the output\n\n--unmerged\n\tShow unmerged files in the output (forces --stage)\n\n-t\n\tShow the following tags (followed by a space) at the start of\n\teach line:\n\tH\tcached\n\tM\tunmerged\n\tR\tremoved/deleted\n\t?\tother\n\n-z\n\t\\0 line termination on output\n\nOutput\nshow files just outputs the filename unless --stage is specified in\nwhich case it outputs:\n\n[ ] \n\nshow-files --unmerged\" and \"show-files --stage \" can be used to examine\ndetailed information on unmerged paths.\n\nFor an unmerged path, instead of recording a single mode/SHA1 pair,\nthe dircache records up to three such pairs; one from tree O in stage\n1, A in stage 2, and B in stage 3. This information can be used by\nthe user (or Cogito) to see what should eventually be recorded at the\npath. (see read-cache for more information on state)\n\nsee also:\nread-cache\n\n\n################################################################\nunpack-file\n\tunpack-file \n\nCreates a file holding the contents of the blob specified by sha1. It\nreturns the name of the temporary file in the following format:\n\t.merge_file_XXXXX\n\n\n\tMust be a blob id\n\n################################################################\nupdate-cache\n\tupdate-cache [--add] [--remove] [--refresh [--ignore-missing]]\n\t\t [--cacheinfo ]*\n\t\t [--] []*\n\nModifies the index or directory cache. Each file mentioned is updated\ninto the cache and any 'unmerged' or 'needs updating' state is\ncleared.\n\nThe way update-cache handles files it is told about can be modified\nusing the various options:\n\n--add\n\tIf a specified file isn't in the cache already then it's\n\tadded.\n\tDefault behaviour is to ignore new files.\n\n--remove\n\tIf a specified file is in the cache but is missing then it's\n\tremoved.\n\tDefault behaviour is to ignore removed file.\n\n--refresh\n\tLooks at the current cache and checks to see if merges or\n\tupdates are needed by checking stat() information.\n\n--ignore-missing\n\tIgnores missing files during a --refresh\n\n--cacheinfo \n\tDirectly insert the specified info into the cache.\n\t\n--\n\tDo not interpret any more arguments as options.\n\n\n\tFiles to act on.\n\tNote that files begining with '.' are discarded. This includes\n\t\"./file\" and \"dir/./file\". If you don't want this, then use\t\n\tcleaner names.\n\tThe same applies to directories ending '/' and paths with '//'\n\n\nUsing --refresh\n\n--refresh does not calculate a new sha1 file or bring the cache\nup-to-date for mode/content changes. But what it _does_ do is to\n\"re-match\" the stat information of a file with the cache, so that you\ncan refresh the cache for a file that hasn't been changed but where\nthe stat entry is out of date.\n\nFor example, you'd want to do this after doing a \"read-tree\", to link\nup the stat cache details with the proper files.\n\nUsing --cacheinfo\n--cacheinfo is used to register a file that is not in the current\nworking directory. This is useful for minimum-checkout merging.\n\nTo pretend you have a file with mode and sha1 at path, say:\n\n $ update-cache --cacheinfo mode sha1 path\n\nTo update and refresh only the files already checked out:\n\n checkout-cache -n -f -a && update-cache --ignore-missing --refresh\n\n\n################################################################\nwrite-tree\n\twrite-tree\n\nCreates a tree object using the current cache.\n\nThe cache must be merged.\n\nConceptually, write-tree sync()s the current directory cache contents\ninto a set of tree files.\nIn order to have that match what is actually in your directory right\nnow, you need to have done a \"update-cache\" phase before you did the\n\"write-tree\".\n\n\n################################################################\n\n\nTerminology: - see README for description\nEach line contains terms used interchangeably\n\nobject database, .git directory\ndirectory cache, index\nid, sha1, sha1-id, sha1 hash\ntype, tag\nblob, blob object\ntree, tree object\ncommit, commit object\nparent\nroot object\nchangeset\n\n\ngit Environment Variables\nAUTHOR_NAME\nAUTHOR_EMAIL\nAUTHOR_DATE\nCOMMIT_AUTHOR_NAME\nCOMMIT_AUTHOR_EMAIL\nGIT_DIFF_CMD\nGIT_DIFF_OPTS\nGIT_INDEX_FILE\nSHA1_FILE_DIRECTORY\n\n"}]}