{"thread":{"id":"249","subject":"[PATCH] More docs","startedAt":"2005-04-22T19:50:20Z","lastAt":"2021-01-21T03:51:06Z","messageCount":7,"participants":["David Greaves","Junio C Hamano","Ævar Arnfjörð Bjarmason","Taylor Blau"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"1314","messageId":"4269557C.1050606@dgreaves.com","threadId":"249","inReplyTo":null,"subject":"[PATCH] More docs","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-04-22T19:50:20Z","receivedAt":"2005-04-22T19:50:20Z","isPatch":true,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"Removed Cogito stuff\n\nUpdated:\n checkout-cache\n commit-tree\n diff-cache\n diff-tree\n fsck-cache\n git-export\n init-db\n read-tree\n show-files\n update-cache\n write-tree\n\nThanks also to Junio C Hamano \nMore eyes please :)\n\nThere are ???s where I'd _especially_ appreciate comments\n\nAlso note that much of this is simply edited emails from the list or \ncomments cross checked with the source.\n\n\nSigned-off-by: David Greaves \n---\n\n\n\n\n\n\nIndex: README.reference\n===================================================================\n--- 5f61aecb06c2f2579bbb5951b1b53e0dedc434eb/README.reference (mode:100644 sha1:8186a561108d3c62625614272bd5e2f7d5826b4b)\n+++ bc80a76ad52f0cdf28c4e10a2490da3558f5def6/README.reference (mode:100644 sha1:810f4990448fbee57490a945d03a5e8a3eaadec0)\n@@ -53,7 +53,7 @@\n \n ################################################################\n checkout-cache\n-\tcheckout-cache [-q] [-a] [-f] [--] ...\n+\tcheckout-cache [-q] [-a] [-f] [--prefix=] [--] ...\n \n Will copy all files listed from the cache to the working directory\n (not overwriting existing files). Note that the file contents are\n@@ -69,6 +69,13 @@\n \tchecks out all files in the cache before processing listed\n \tfiles.\n \n+--prefix=\n+\tWhen creating files, prepend this (usually a\n+\tdirectory including a trailing /)\n+\n+--\n+\tDo not interpret any more arguments as options.\n+\n Note that the order of the flags matters:\n \n \tcheckout-cache -a -f file.c\n@@ -96,6 +103,22 @@\n problems (not possible in the above example, but get used to it in\n scripting!).\n \n+The prefix ability basically makes it trivial to use checkout-cache as\n+a \"export as tree\" function. Just read the desired tree into the\n+index, and do a\n+ \n+ checkout-cache --prefix=export-dir/ -a\n+ \n+and checkout-cache will \"export\" the cache into the specified\n+directory.\n+ \n+NOTE! The final \"/\" is important. The exported name is literally just\n+prefixed with the specified string, so you can also do something like\n+ \n+ checkout-cache --prefix=.merged- Makefile\n+ \n+to check out the currently cached copy of \"Makefile\" into the file\n+\".merged-Makefile\".\n \n ################################################################\n commit-id\n@@ -109,12 +132,340 @@\n \n ################################################################\n commit-tree\n-\tcommit-tree [-p ]* < changelog\n+\tcommit-tree [-p ]* < changelog\n+\n+Creates a new commit object based on the provided tree object and\n+emits the new commit object id on stdout. If no parent is given then\n+it is considered to be an initial tree.\n+\n+A commit object usually has 1 parent (a commit after a change) or up\n+to 16 parents. More than one parent represents merge of branches that\n+led to them.\n+\n+While a tree represents a particular directory state of a working\n+directory, a commit represents that state in \"time\", and explains how\n+to get there.\n+\n+Normally a commit would identify a new \"HEAD\" state, and while git\n+doesn't care where you save the note about that state, in practice we\n+tend to just write the result to the file \".git/HEAD\", so that we can\n+always see what the last committed state was.\n+\n+Options\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+\n+Commit Information\n+\n+A commit encapsulates:\n+\tall parent object ids\n+\tauthor name, email and date\n+\tcommitter name and email and the commit time.\n+\n+If not provided, commit-tree uses your name, hostname and domain to\n+provide author and committer info. This can be overridden using the\n+following 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+\n+A commit comment is read from stdin (max 999 chars)\n+\n+see also: write-tree\n \n \n ################################################################\n+diff-cache\n+\tdiff-cache [-r] [-z] [--cached] \n+\n+Compares the content and mode of the blobs found via a tree object\n+with the content of the current cache and, optionally ignoring the\n+stat state of the file on disk.\n+\n+(This is basically a special case of diff-tree that works with the\n+current 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+\n+Output format:\n+\n+For files in the tree but not in the cache\n+-\\t \\t\t\\t\t\n+\n+For files in the cache but not in the tree\n++\\t \\t\t\\t\t\n+\n+For files that differ:\n+*->\\t \\t\t->\\t\t\n+\n+In the special case of the file being changed on disk and out of sync\n+with the cache, the sha1 is all 0's. Example:\n+\n+\t*100644->100660 blob 5be4a414b32cf4204f889469942986d3d783da84->0000000000000000000000000000000000000000 file.c\n+\t\n+\n+Operating Modes\n+You 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\n+that don't match the stat state as being \"tentatively changed\". Both\n+of these operations are very useful indeed.\n+\n+Cached Mode\n+If --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+\n+For example, let's say that you have worked on your index file, and are\n+ready to commit. You want to see eactly _what_ you are going to commit is\n+without having to write a new tree object and compare it that way, and to\n+do that, you just do\n+\n+\tdiff-cache --cached $(cat .git/HEAD)\n+\n+Example: let's say I had renamed \"commit.c\" to \"git-commit.c\", and I had \n+done 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 \n+my 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+\n+And as you can see, the output matches \"diff-tree -r\" output (we\n+always do \"-r\", since the index is always fully populated\n+??CHECK??).\n+You can trivially see that the above is a rename.\n+\n+In fact, \"diff-tree --cached\" _should_ always be entirely equivalent to\n+actually doing a \"write-tree\" and comparing that. Except this one is much\n+nicer for the case where you just want to check where you are.\n+\n+So doing a \"diff-cache --cached\" is basically very useful when you are \n+asking yourself \"what have I already marked for being committed, and \n+what's the difference to a previous tree\".\n+\n+Non-cached Mode\n+\n+The \"non-cached\" mode takes a different approach, and is potentially\n+the even more useful of the two in that what it does can't be emulated\n+with a \"write-tree + diff-tree\". Thus that's the default mode. The\n+non-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+\n+which is obviously a very useful question too, since that tells you what\n+you _could_ commit. Again, the output matches the \"diff-tree -r\" output to\n+a tee, but with a twist.\n+\n+The twist is that if some file doesn't match the cache, we don't have a\n+backing store thing for it, and we use the magic \"all-zero\" sha1 to show\n+that. So let's say that you have edited \"kernel/sched.c\", but have not\n+actually done an update-cache on it yet - there is no \"object\" associated\n+with 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+\n+ie it shows that the tree has changed, and that \"kernel/sched.c\" has is\n+not up-to-date and may contain new stuff. The all-zero sha1 means that to\n+get the real diff, you need to look at the object in the working directory\n+directly rather than do an object-to-object diff.\n+\n+NOTE! As with other commands of this type, \"diff-cache\" does not actually \n+look at the contents of the file at all. So maybe \"kernel/sched.c\" hasn't \n+actually changed, and it's just that you touched it. In either case, it's \n+a note that you need to upate-cache it to make the cache be in sync.\n+\n+NOTE 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\n+which file is in which state, since the \"has been updated\" ones show a\n+valid sha1, and the \"not in sync with the index\" ones will always have the\n+special all-zero sha1.\n+\n+################################################################\n diff-tree\n-\tdiff-tree [-r] [-z] \n+\tdiff-tree [-r] [-z] \n+\n+Compares the content and mode of the blobs found via two tree objects.\n+\n+Note 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+\n+--cached\n+\tCached only (private?)\n+\n+Output format:\n+\n+For files in tree1 but not in tree2\n+-\\t \\t\t\\t\t\n+\n+For files not in tree1 but in tree2\n++\\t \\t\t\\t\t\n+\n+For files that differ:\n+*->\\t \\t\t->\\t\t\n+\n+\n+An 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+\n+which tells you that the last commit changed just one file (it's from\n+this 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+\n+in case you care).\n+\n+\n+################################################################\n+fsck-cache\n+\tfsck-cache [[--unreachable] *]\n+\n+Verifies the connectivity and validity of the objects in the database.\n+\n+\n+\tA commit object to begin an unreachability trace\n+\n+--unreachable\n+\tprint out objects that exist but that aren't readable from any\n+\tof the specified root nodes\n+\n+It tests SHA1 and general object sanity, but it does full tracking of\n+the resulting reachability and everything else. It prints out any\n+corruption it finds (missing or bad objects), and if you use the\n+\"--unreachable\" flag it will also print out objects that exist but\n+that aren't readable from any of the specified root nodes.\n+\n+So for example\n+\n+\tfsck-cache --unreachable $(cat .git/HEAD)\n+\n+or, for Cogito users:\n+\n+\tfsck-cache --unreachable $(cat .git/heads/*)\n+\n+will do quite a _lot_ of verification on the tree. There are a few\n+extra validity tests to be added (make sure that tree objects are\n+sorted properly etc), but on the whole if \"fsck-cache\" is happy, you\n+do have a valid tree.\n+\n+Any 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\n+the hopes that somebody else has the object you have corrupted).\n+\n+Of course, \"valid tree\" doesn't mean that it wasn't generated by some\n+evil person, and the end result might be crap. Git is a revision\n+tracking system, not a quality assurance system ;)\n+\n+Extracted Diagnostics\n+expect 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+\n+missing sha1 directory ''\n+\tThe directory holding the sha1 objects is missing.\n+\n+unreachable \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+\n+missing \n+\tThe object , is referred to but isn't present in\n+\tthe database.\n+\n+dangling \n+\tThe object , is present in the database but never\n+\t_directly_ used. A dangling commit could be a root node.\n+\n+warning: fsck-cache: tree has full pathnames in it\n+\tAnd it shouldn't...\n+\n+sha1 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+\n+Environment Variables\n+\n+SHA1_FILE_DIRECTORY\n+\tused to specify the object database root (usually .git/objects)\n+\n+################################################################\n+git-export\n+\tgit-export top [base]\n+\n+probably deprecated:\n+On 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+\n+That's fine. It was a quick hack, just to show that if somebody wants to, \n+the data is trivially exportable.\n+\n+\t\tLinus\n+\n+\n+################################################################\n+init-db\n+\tinit-db\n+\n+This simply creates an empty git object database - basically a .git\n+directory.\n+\n+If the object storage directory is specified via the\n+SHA1_FILE_DIRECTORY environment variable then the sha1 directories are\n+created underneath - otherwise the default .git/objects directory is\n+used.\n+\n+init-db won't hurt an existing repository.\n \n \n ################################################################\n@@ -134,7 +485,108 @@\n \n ################################################################\n read-tree\n-\tread-tree [-m] \n+\tread-tree ( | -m [ ])\"\n+\n+Reads the tree information given by into the directory cache,\n+but does not actually _update_ any of the files it \"caches\". (see:\n+checkout-cache)\n+\n+Optionally, it can merge a tree into the cache or perform a 3-way\n+merge.\n+\n+Trivial merges are done by read-tree itself. Only conflicting paths\n+will be in unmerged state when read-tree returns.\n+\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+\n+Merging\n+Each \"index\" entry has two bits worth of \"stage\" state. stage 0 is the\n+normal one, and is the only one you'd see in any kind of normal use.\n+\n+However, when you do \"read-tree\" with multiple trees, the \"stage\"\n+starts out at 0, but increments for each tree you read. And in\n+particular, the old \"-m\" flag (which used to be \"merge with old\n+state\") has a new meaning: it now means \"start at stage 1\" instead.\n+\n+This means that you can do\n+\n+\tread-tree -m \n+\n+and 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+\n+Furthermore, \"read-tree\" has this special-case logic that says: if you\n+see a file that matches in all respects in all three states, it\n+\"collapses\" back to \"stage0\".\n+\n+Write-tree refuses to write a nonsensical tree, so write-tree will\n+complain about unmerged entries if it sees a single entry that is not\n+stage 0\".\n+\n+Ok, this all sounds like a collection of totally nonsensical rules,\n+but it's actually exactly what you want in order to do a fast\n+merge. The different stages represent the \"result tree\" (stage 0, aka\n+\"merged\"), the original tree (stage 1, aka \"orig\"), and the two trees\n+you are trying to merge (stage 2 and 3 respectively).\n+\n+In fact, the way \"read-tree\" works, it's entirely agnostic about how\n+you assign the stages, and you could really assign them any which way,\n+and the above is just a suggested way to do it (except since\n+\"write-tree\" refuses to write anything but stage0 entries, it makes\n+sense to always consider stage 0 to be the \"full merge\" state).\n+\n+So what happens? Try it out. Select the original tree, and two trees\n+to 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+\n+So 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+\n+NOTE NOTE NOTE! although read-tree coule do some of these nontrivial\n+merges, only the \"matches in all three states\" thing collapses by\n+default. This is because even though there are other trivial cases\n+(\"matches in both merge trees but not in the original one\"), those\n+cases might actually be interesting for the merge logic to know about,\n+so that information is left around. It should be fairly rare anyway,\n+so a few extra index entries are written out to disk so that the merge\n+can be annotated.\n+\n+Incidentally - it also means that you don't even have to have a separate \n+subdirectory for this. All the information literally is in the index file, \n+which is a temporary thing anyway. There is no need to worry about what is in \n+the working directory, since it is never shown and never used.\n+\n+see also:\n+write-tree\n+show-files\n \n \n ################################################################\n@@ -151,8 +603,145 @@\n show-files\n \tshow-files [-z] [-t] (--[cached|deleted|others|ignored|stage])*\n \n+This merges the file listing in the directory cache index with the\n+actual working directory list, and shows different combinations of the\n+two. \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+-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+\n+Output\n+show files just outputs the filename unless --stage is specified in\n+which case it outputs:\n+\n+[ ] \n+\n+show-files --unmerged\" and \"show-files --stage \" can be used to examine\n+detailed information on unmerged paths.\n+\n+For an unmerged path, instead of recording a single mode/SHA1 pair,\n+the dircache records up to three such pairs; one from tree O in stage\n+1, A in stage 2, and B in stage 3. This information can be used by\n+the user (or Cogito) to see what should eventually be recorded at the\n+path. (see read-cache for more information on state)\n+\n+see also:\n+read-cache\n+\n \n ################################################################\n unpack-file\n \tunpack-file.c \n \n+################################################################\n+update-cache\n+\tupdate-cache [--add] [--remove] [--refresh] [--cacheinfo ]* [--] []*\n+\n+Modifies the index or directory cache. Each file mentioned is updated\n+into the cache and any 'unmerged' or 'needs updating' state is\n+cleared.\n+\n+The way update-cache handles files it is told about can be modified\n+using 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+\n+Using --refresh\n+\n+--refresh\" does not calculate a new sha1 file or bring the cache\n+up-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\n+can refresh the cache for a file that hasn't been changed but where\n+the stat entry is out of date.\n+\n+For example, you'd want to do this after doing a \"read-tree\", to link\n+up the stat cache details with the proper files.\n+\n+Using --cacheinfo\n+--cacheinfo is used to register a file that is not in the current\n+working directory. This is useful for minimum-checkout merging.\n+\n+To pretend you have a file with mode and sha1 at path, say:\n+\n+ $ update-cache --cacheinfo mode sha1 path\n+\n+\n+################################################################\n+write-tree\n+\twrite-tree\n+\n+Creates a tree object using the current cache.\n+\n+The cache must be merged.\n+\n+Conceptually, write-tree sync()s the current directory cache contents\n+into a set of tree files.\n+In order to have that match what is actually in your directory right\n+now, you need to have done a \"update-cache\" phase before you did the\n+\"write-tree\".\n+\n+\n+################################################################\n+\n+\n+\n+git Environment Variables\n+AUTHOR_NAME\n+AUTHOR_EMAIL\n+AUTHOR_DATE\n+COMMIT_AUTHOR_NAME\n+COMMIT_AUTHOR_EMAIL\n+GIT_DIFF_CMD\n+GIT_DIFF_OPTS\n+GIT_INDEX_FILE\n+SHA1_FILE_DIRECTORY\n+\nIndex: contrib/gitfeedmaillist.sh\n===================================================================\n"},{"id":"1320","messageId":"7vwtqu5ymu.fsf@assigned-by-dhcp.cox.net","threadId":"249","inReplyTo":"4269557C.1050606@dgreaves.com","subject":"Re: [PATCH] More docs","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-04-22T20:45:29Z","receivedAt":"2005-04-22T20:45:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":">>>>> \"DG\" == David Greaves writes:\n\nDG> Removed Cogito stuff\n\nDG> commit-id\n\nThis is Cogito invention, not in the core. Neither is tree-id.\n\nDG> ################################################################\nDG> +diff-cache\nDG> ...\nDG> +-z\nDG> +\t/0 line termination on output\n\nWrite this either '\\0' (for C literate) or NUL (ASCII character\nname), please. The same for other commands with -z.\n\nDG> diff-tree\nDG> -\tdiff-tree [-r] [-z] \nDG> +\tdiff-tree [-r] [-z] \nDG> +...\nDG> +--cached\nDG> +\tCached only (private?)\n\nWhat? The beauty of diff-tree is it does not care about\ndircache at all. Maybe this is a Pasky addition, but I wonder\nwhat the semantics of this option and why it is here...\n\nDG> ################################################################\nDG> read-tree\nDG> -\tread-tree [-m] \nDG> +\tread-tree ( | -m [ ])\"\nDG> +\nDG> +Reads the tree information given by into the directory cache,\nDG> +but does not actually _update_ any of the files it \"caches\". (see:\nDG> +checkout-cache)\nDG> +\nDG> +Optionally, it can merge a tree into the cache or perform a 3-way\nDG> +merge.\nDG> +\nDG> +Trivial merges are done by read-tree itself. Only conflicting paths\nDG> +will be in unmerged state when read-tree returns.\nDG> +...\nDG> +NOTE NOTE NOTE! although read-tree coule do some of these nontrivial\nDG> +merges, only the \"matches in all three states\" thing collapses by\nDG> +default.\n\nThe above \"NOTE\" is taken from the initial message from Linus\nbut it is no longer true. These days, it merges when:\n\n - stage 2 and 3 are the same\n - stage 1 and stage 2 are the same and stage 3 is different\n - stage 1 and stage 3 are the same and stage 2 is different\n\nOriginally it merged only when all stages are the same.\n\nAlso you do not describe the single tree merge (\"read-tree -m\nsha1\"). Its semantics is:\n\n Operate as if the user did not specify \"-m\", but if the\n original cache had an entry for the same pathname already\n and the contents of the original matches with the tree being\n read, use the stat info from the original instead.\n\nThis is used to avoid unnecessary false hits when show-diff is\nrun after read-tree.\n\nDG> ################################################################\nDG> @@ -151,8 +603,145 @@\nDG> show-files\nDG> \tshow-files [-z] [-t] (--[cached|deleted|others|ignored|stage])*\n \nAlthough I like it, I do not think -t is in core. It is Pasky.\nAlso you missed \"show-files --unmerged\".\n\n \n\n"},{"id":"1328","messageId":"4269704A.9090503@dgreaves.com","threadId":"249","inReplyTo":"7vwtqu5ymu.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] More docs","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-04-22T21:44:42Z","receivedAt":"2005-04-22T21:44:42Z","isPatch":true,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"Junio C Hamano wrote:\n\nThanks for the comments Junio\n\n>>>>>>\"DG\" == David Greaves writes:\n> \n> This is Cogito invention, not in the core. Neither is tree-id.\nOK - hard to tell sometimes...\n\n> DG> +\t/0 line termination on output\n> \n> Write this either '\\0' (for C literate) or NUL (ASCII character\n> name), please. The same for other commands with -z.\nhmm, this...\n\n> DG> +--cached\n> DG> +\tCached only (private?)\n> \n> What? The beauty of diff-tree is it does not care about\n> dircache at all. Maybe this is a Pasky addition, but I wonder\n> what the semantics of this option and why it is here...\n...and this, are pre-final-polish\nI must have committed the wrong one - \n\n> DG> +NOTE NOTE NOTE! although read-tree coule do some of these nontrivial\n> DG> +merges, only the \"matches in all three states\" thing collapses by\n> DG> +default.\n> \n> The above \"NOTE\" is taken from the initial message from Linus\n> but it is no longer true. These days, it merges when:\nOK - will edit\n\nhow does this sound:\n\nMerging\nIf -m is specified, read-tree performs 2 kinds of merge, a subservient\ntree-read if only 1 tree is given or a 3-way merge if 3 trees are\nprovided.\n\nSubservient Tree Read\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 subservient tree's)\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 - stage 2 and 3 are the same\n - stage 1 and stage 2 are the same and stage 3 is different\n - stage 1 and stage 3 are the same and stage 2 is different\n\nNOTE NOTE NOTE para removed.\n\n> DG> ################################################################\n> DG> @@ -151,8 +603,145 @@\n> DG> show-files\n> DG> \tshow-files [-z] [-t] (--[cached|deleted|others|ignored|stage])*\n> \n> Although I like it, I do not think -t is in core. It is Pasky.\nWell, it says Copyright (C) Linus Torvalds, 2005 - and Linus describes \nit in his discussion so...\n\n> Also you missed \"show-files --unmerged\".\nI did - that's me using the usage() string!!\n\nDavid\n\n-- \n"},{"id":"1333","messageId":"7vacnq5u49.fsf@assigned-by-dhcp.cox.net","threadId":"249","inReplyTo":"4269704A.9090503@dgreaves.com","subject":"Re: [PATCH] More docs","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-04-22T22:23:02Z","receivedAt":"2005-04-22T22:23:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":">>>>> \"DG\" == David Greaves writes:\n\nDG> Merging\nDG> If -m is specified, read-tree performs 2 kinds of merge, a subservient\nDG> tree-read if only 1 tree is given or a 3-way merge if 3 trees are\nDG> provided.\n\nAFAICR Linus never used the word \"subservient\" to describe this\ncase [*R1*]. I do not know if the word is a good fit for\ndescribing what it does. Sorry, I cannot help you in deciding\nif this is the right word nor in picking a better word. I am\nnot a native speaker so I had to look it up in the dictionary.\n\nDG> Furthermore, \"read-tree\" has special-case logic that says: if you see\nDG> a file that matches in all respects in the following states, it\nDG> \"collapses\" back to \"stage0\":\nDG> - stage 2 and 3 are the same\nDG> - stage 1 and stage 2 are the same and stage 3 is different\nDG> - stage 1 and stage 3 are the same and stage 2 is different\n\nThat is what I wrote so I should say \"sounds good\", but after\nre-reading it I realize we should describe how these trivial\nones are resolved, like so:\n\n Furthermore, \"read-tree\" has special-case logic that says: if you see\n a 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;\n take one or the other (it does not make a difference)\n - stage 1 and stage 2 are the same and stage 3 is different;\n take stage 3\n - stage 1 and stage 3 are the same and stage 2 is different\n take stage 2\n \nDG> show-files\nDG> show-files [-z] [-t] (--[cached|deleted|others|ignored|stage])*\n>> Although I like it, I do not think -t is in core. It is Pasky.\nDG> Well, it says Copyright (C) Linus Torvalds, 2005 - and Linus describes\nDG> it in his discussion so...\n\nMy comment was only about the '-t' option. It is not one of the\noptions in the core. Pasky may want to feed the change to\nLinus.\n\n\n[References]\n*R1*\n\n Date:\tTue, 19 Apr 2005 11:27:34 -0700 (PDT)\n From:\tLinus Torvalds \n Subject: Re: naive question\n Message-ID: \n\n On Tue, 19 Apr 2005, Linus Torvalds wrote:\n > \n > The real expense right now of a merge is that we always forget all the\n > stat information when we do a merge (since it does a read-tree). I have a\n > cunning way to fix that, though, which is to make \"read-tree -m\" read in\n > the old index state like it used to, and then at the end just throw it\n > away except for the stat information.\n\n Ok, done. That was really the plan all along, it just got dropped in the \n excitement of trying to get the dang thing to _work_ in the first place ;)\n\n ... I'll also make it do the same for a \"single-tree merge\":\n\n read-tree -m \n\n so that you can basically say \"read a new tree, and merge the stat \n information from the current cache\". That means that if you do a\n \"read-tree -m \" followed by a \"checkout-cache -f -a\", the \n checkout-cache only checks out the stuff that really changed.\n\n"},{"id":"414511","messageId":"20210116171500.20092-1-avarab@gmail.com","threadId":"249","inReplyTo":"4269557C.1050606@dgreaves.com","subject":"[PATCH] fsck doc: remove ancient out-of-date diagnostics","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-01-16T17:15:00Z","receivedAt":"2021-01-16T17:17:56Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Remove diagnostics that haven't been emitted by \"fsck\" or its\npredecessors for around 15 years. This documentation was added in\nc64b9b88605 (Reference documentation for the core git commands.,\n2005-05-05), but was out-of-date quickly after that.\n\nNotes on individual diagnostics:\n\n - \"expect dangling commits\": Added in bcee6fd8e71 (Make 'fsck' able\n to[...], 2005-04-13), documented in c64b9b88605. Not emitted since\n 1024932f019 (fsck-cache: walk the 'refs' directory[...],\n 2005-05-18).\n\n - \"missing sha1 directory\": Added in 20222118ae4 (Add first cut at\n \"fsck-cache\"[...], 2005-04-08), documented in c64b9b88605. Not\n emitted since 230f13225df (Create object subdirectories on demand,\n 2005-10-08).\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-fsck.txt | 8 --------\n 1 file changed, 8 deletions(-)\n\ndiff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt\nindex d72d15be5b..bd596619c0 100644\n--- a/Documentation/git-fsck.txt\n+++ b/Documentation/git-fsck.txt\n@@ -129,14 +129,6 @@ using 'git commit-graph verify'. See linkgit:git-commit-graph[1].\n Extracted Diagnostics\n ---------------------\n \n-expect 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-\n-missing sha1 directory ''::\n-\tThe directory holding the sha1 objects is missing.\n-\n unreachable ::\n \tThe object , isn't actually referred to directly\n \tor indirectly in any of the trees or commits seen. This can\n-- \n2.29.2.222.g5d2a92d10f8\n\n"},{"id":"414736","messageId":"YAbtH5hSiRTwulGv@nand.local","threadId":"249","inReplyTo":"20210116171500.20092-1-avarab@gmail.com","subject":"Re: [PATCH] fsck doc: remove ancient out-of-date diagnostics","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2021-01-19T14:30:55Z","receivedAt":"2021-01-19T22:41:58Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Sat, Jan 16, 2021 at 06:15:00PM +0100, Ævar Arnfjörð Bjarmason wrote:\n> Remove diagnostics that haven't been emitted by \"fsck\" or its\n> predecessors for around 15 years. This documentation was added in\n> c64b9b88605 (Reference documentation for the core git commands.,\n> 2005-05-05), but was out-of-date quickly after that.\n>\n> Notes on individual diagnostics:\n>\n> - \"expect dangling commits\": Added in bcee6fd8e71 (Make 'fsck' able\n> to[...], 2005-04-13), documented in c64b9b88605. Not emitted since\n> 1024932f019 (fsck-cache: walk the 'refs' directory[...],\n> 2005-05-18).\n>\n> - \"missing sha1 directory\": Added in 20222118ae4 (Add first cut at\n> \"fsck-cache\"[...], 2005-04-08), documented in c64b9b88605. Not\n> emitted since 230f13225df (Create object subdirectories on demand,\n> 2005-10-08).\n\nThanks for digging on both of these. I checked independently and came to\nthe same conclusion that you did, so I agree that these can be safely\nremoved.\n\n Reviewed-by: Taylor Blau \n\nThanks,\nTaylor\n"},{"id":"414880","messageId":"xmqqwnw7c7cf.fsf@gitster.c.googlers.com","threadId":"249","inReplyTo":"YAbtH5hSiRTwulGv@nand.local","subject":"Re: [PATCH] fsck doc: remove ancient out-of-date diagnostics","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-01-21T03:11:12Z","receivedAt":"2021-01-21T03:51:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Taylor Blau writes:\n\n> On Sat, Jan 16, 2021 at 06:15:00PM +0100, Ævar Arnfjörð Bjarmason wrote:\n>> Remove diagnostics that haven't been emitted by \"fsck\" or its\n>> predecessors for around 15 years. This documentation was added in\n>> c64b9b88605 (Reference documentation for the core git commands.,\n>> 2005-05-05), but was out-of-date quickly after that.\n>>\n>> Notes on individual diagnostics:\n>>\n>> - \"expect dangling commits\": Added in bcee6fd8e71 (Make 'fsck' able\n>> to[...], 2005-04-13), documented in c64b9b88605. Not emitted since\n>> 1024932f019 (fsck-cache: walk the 'refs' directory[...],\n>> 2005-05-18).\n>>\n>> - \"missing sha1 directory\": Added in 20222118ae4 (Add first cut at\n>> \"fsck-cache\"[...], 2005-04-08), documented in c64b9b88605. Not\n>> emitted since 230f13225df (Create object subdirectories on demand,\n>> 2005-10-08).\n>\n> Thanks for digging on both of these. I checked independently and came to\n> the same conclusion that you did, so I agree that these can be safely\n> removed.\n>\n> Reviewed-by: Taylor Blau \n>\n> Thanks,\n> Taylor\n\nThanks, both.\n"}]}