{"thread":{"id":"230","subject":"[PATCH] Docs update","startedAt":"2005-04-21T20:40:44Z","lastAt":"2005-04-21T23:10:23Z","messageCount":6,"participants":["David Greaves","Petr Baudis","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"1191","messageId":"42680FCC.6030901@dgreaves.com","threadId":"230","inReplyTo":null,"subject":"[PATCH] Docs update","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-04-21T20:40:44Z","receivedAt":"2005-04-21T20:40:44Z","isPatch":true,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"Added commit-tree, diff-cache and environment info\n\n\nSigned-off-by: David Greaves \n---\n\n\n\nIndex: README.reference\n===================================================================\n--- c0260bfb82da04aeff4e598ced5295d6ae2e262d/README.reference (mode:100644 sha1:8186a561108d3c62625614272bd5e2f7d5826b4b)\n+++ 5f204110aef2538fdc512e09e4a075b3afac8eff/README.reference (mode:100644 sha1:b5fc4fb969ec3f52877408c8df4ba131a8c4a7b2)\n@@ -109,12 +109,173 @@\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 2\n+parents (a merge) although there is no reason it cannot have more than\n+2 parents.\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 CRs 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] \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, the stat state\n+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 termintation 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\n+\n+For files in the cache but not in the tree\n++ \t\t\n+\n+For files that differ:\n+*-> \t->\tpath/\n+\n+In the special case of the file being changed on disk and out of sync with the cache, the sha1\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 \n ################################################################\n@@ -156,3 +317,23 @@\n unpack-file\n \tunpack-file.c \n \n+\n+\n+git Environment Variables\n+GIT_CACHE_DIRECTORY\n+AUTHOR_NAME\n+AUTHOR_EMAIL\n+AUTHOR_DATE\n+RSYNC_FLAGS\n+GIT_INDEX_FILE\n+\n+\n+.git Repository Files\n+\n+.git/HEAD\n+This file always contains the last (head) commit object created for this branch of the repository.\n+(Usually symlinked to a file in .git/heads/)\n+\n+.git/heads/\n+This directory contains a file for each branch of the .git repository.\n+The name of the file is the friendly name of the branch (eg pasky)\n"},{"id":"1192","messageId":"20050421204348.GJ7443@pasky.ji.cz","threadId":"230","inReplyTo":"42680FCC.6030901@dgreaves.com","subject":"Re: [PATCH] Docs update","fromName":"Petr Baudis","fromEmail":"pasky@ucw.cz","sentAt":"2005-04-21T20:43:49Z","receivedAt":"2005-04-21T20:43:49Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"Dear diary, on Thu, Apr 21, 2005 at 10:40:44PM CEST, I got a letter\nwhere David Greaves told me that...\n> @@ -156,3 +317,23 @@\n> unpack-file\n> \tunpack-file.c \n> \n> +\n> +\n> +git Environment Variables\n> +GIT_CACHE_DIRECTORY\n> +AUTHOR_NAME\n> +AUTHOR_EMAIL\n> +AUTHOR_DATE\n> +RSYNC_FLAGS\n> +GIT_INDEX_FILE\n> +\n> +\n> +.git Repository Files\n> +\n> +.git/HEAD\n> +This file always contains the last (head) commit object created for this branch of the repository.\n> +(Usually symlinked to a file in .git/heads/)\n> +\n> +.git/heads/\n> +This directory contains a file for each branch of the .git repository.\n> +The name of the file is the friendly name of the branch (eg pasky)\n\nMake a choice - either you are describing git or Cogito. The frmer has\nno RSYNC_FLAGS and does not care about any heads or anything at all (you\nmight mention it as a recommended convention, though).\n\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\nC++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor\n"},{"id":"1195","messageId":"4268181B.6050906@dgreaves.com","threadId":"230","inReplyTo":"20050421204348.GJ7443@pasky.ji.cz","subject":"Re: [PATCH] Docs update","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-04-21T21:16:11Z","receivedAt":"2005-04-21T21:16:11Z","isPatch":true,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"Petr Baudis wrote:\n> \n> Make a choice - either you are describing git or Cogito. The frmer has\n> no RSYNC_FLAGS and does not care about any heads or anything at all (you\n> might mention it as a recommended convention, though).\n\nI was going to do both - surely that's OK?\n\nThe only reason it's core so far is that I started working my way \nthrough the code alphabetically (having no other clue where to start!)\n\nAs it turns out it will probably make sense to do all the core first - \nbut I don't want to miss things so as I read through all the mails and \nextract content, I make a note of things like environment variables \nwhich I'll bulk up and cross reference later.\n\nI may even change my mind and make notes on Cogito if that takes my \nfancy too ;)\n\nI know it's not polished yet - but I'd rather publish it and have people \ncatch mistakes.\n\nDavid\n\n\n\n"},{"id":"1196","messageId":"20050421212602.GL7443@pasky.ji.cz","threadId":"230","inReplyTo":"4268181B.6050906@dgreaves.com","subject":"Re: [PATCH] Docs update","fromName":"Petr Baudis","fromEmail":"pasky@ucw.cz","sentAt":"2005-04-21T21:26:02Z","receivedAt":"2005-04-21T21:26:02Z","isPatch":true,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"Dear diary, on Thu, Apr 21, 2005 at 11:16:11PM CEST, I got a letter\nwhere David Greaves told me that...\n> Petr Baudis wrote:\n> >\n> >Make a choice - either you are describing git or Cogito. The frmer has\n> >no RSYNC_FLAGS and does not care about any heads or anything at all (you\n> >might mention it as a recommended convention, though).\n> \n> I was going to do both - surely that's OK?\n\nI thought the original goal for README.reference was to be git-specific,\nand I planned to therefore push it to the core git at some point.\n\nI actually probably don't mind as long as you keep the two separated\ncleanly inside of the file, so if we shall want to include it in git,\nthe trimming of the docs to only relevant parts is simple enough.\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nStuff: http://pasky.or.cz/\nC++: an octopus made by nailing extra legs onto a dog. -- Steve Taylor\n"},{"id":"1211","messageId":"7vy8bbd9n4.fsf@assigned-by-dhcp.cox.net","threadId":"230","inReplyTo":"42680FCC.6030901@dgreaves.com","subject":"Re: [PATCH] Docs update","fromName":"Junio C Hamano","fromEmail":"junio@siamese.dyndns.org","sentAt":"2005-04-21T22:53:35Z","receivedAt":"2005-04-21T22:53:35Z","isPatch":true,"sender":{"key":"junio@siamese.dyndns.org","avatar":null},"body":">>>>> \"DG\" == David Greaves writes:\n\nLooks nice. I agree with Petr's comment that separating core part\nand Cogito part would be good, and I would appreciate if you\npushed the core part documentation to Linus as well.\n\nSome nitpicks and notes on your core part description.\n\nDG> commit-tree\nDG> -\tcommit-tree [-p ]* < changelog\nDG> +\tcommit-tree [-p ...] < changelog\n \nThe above does not describe what commit-tree expects. It wants\n\n commit-tree [-p ]* +A commit object usually has 1 parent (a commit after a change) or 2\nDG> +parents (a merge) although there is no reason it cannot have more than\nDG> +2 parents.\n\nI'd rewrite the \"or 2 parents...\" part to \"up to 16 parents. More\nthan one parent represents merge of branches that led to them.\"\n\nDG> +If not provided, commit-tree uses your name, hostname and domain to\nDG> +provide author and committer info. This can be overridden using the\nDG> +following environment variables.\nDG> +\t...\nDG> +(nb <,> and CRs are stripped)\n\nCRs are kept. It removes '\\n' (which is not necessarily LF).\n\nDG> +diff-cache\nDG> +\tdiff-cache [-r] [-z] \nDG> +\nDG> +Compares the content and mode of the blobs found via a tree object\nDG> +with the content of the current cache and, optionally, the stat state\nDG> +of the file on disk.\n\nAnd the option to use working tree is not having the --cached\nflag you describe later. Please also update the usage at the\ntop as well:\n\n\tdiff-cache [-r] [-z] [--cached] \n\nDG> +In the special case of the file being changed on disk and out of sync with the cache, the sha1\nDG> +\nDG> +Operating Modes\n\nIs the description truncated after \"the sha1\"???\n\nDG> ################################################################\nDG> diff-tree\nDG> -\tdiff-tree [-r] [-z] \nDG> +\tdiff-tree [-r] [-z] \n\nThis command can take commit ID in place of tree ID.\n \n\n"},{"id":"1218","messageId":"426832DF.4090909@dgreaves.com","threadId":"230","inReplyTo":"7vy8bbd9n4.fsf@assigned-by-dhcp.cox.net","subject":"Re: [PATCH] Docs update","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-04-21T23:10:23Z","receivedAt":"2005-04-21T23:10:23Z","isPatch":true,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"Junio C Hamano wrote:\n>>>>>>\"DG\" == David Greaves writes:\n> Looks nice. I agree with Petr's comment that separating core part\n> and Cogito part would be good\nOK\n\n\n> And the option to use working tree is not having the --cached\n> flag you describe later. Please also update the usage at the\n> top as well:\n\n> This command can take commit ID in place of tree ID.\n\nYep, the intention is to do all the core docs, get consistent use of \n or or etc etc and then patch all the usage()s at once.\n\nThanks for the comments - will edit in the am.\n\nDavid\n"}]}