{"thread":{"id":"174","subject":"[PATCH] Some documentation...","startedAt":"2005-04-20T17:08:29Z","lastAt":"2005-04-20T20:15:19Z","messageCount":4,"participants":["David Greaves","C. Scott Ananian","Linus Torvalds"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"1003","messageId":"42668C8D.3000209@dgreaves.com","threadId":"174","inReplyTo":null,"subject":"[PATCH] Some documentation...","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-04-20T17:08:29Z","receivedAt":"2005-04-20T17:08:29Z","isPatch":true,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"Hi\n\nI'm starting to write some docs...\nComments... even \"yep, looks OK, carry on\" :)\n\nI plan on putting the 'git command' ones into the 'git help ...' \nstructure once Petr accepts it.\nI guess the low level ones go into a README.reference until they \nstabilise and become man pages...\n\nIn doing this I noticed a couple of points:\n* update-cache won't accept ./file or fred/./file\n* checkout-cache doesn't seem to preserve mode\n\nAre these bugs or should they be documented?\nI've taken the approach of documenting behaviour for now.\n\nSigned-off-by: David Greaves \n---\n\n\n\n\nIndex: README.reference\n===================================================================\n--- /dev/null (tree:cf6a46a2199777c3dac32fa4479b97c0752cdf07)\n+++ 30de093673d44c7ea8c56a0194fb792e47225ac8/README.reference (mode:100644 sha1:2ec6683b22e5672ea46d27770fcb1a4b4c37aa0e)\n@@ -0,0 +1,158 @@\n+Terminology: - see README for description\n+Each line contains terms used interchangeably\n+\n+object database, .git directory\n+directory cache, index\n+id, sha1, sha1-id, sha1 hash\n+type, tag, tagname\n+blob, blob object\n+tree, tree object\n+commit, commit object\n+parent\n+root object\n+changeset\n+\n+################################################################\n+cat-file\n+\tcat-file <-t | tagname> \n+\n+Provide contents or type of objects in the repository. The tagname is\n+required if it is not being interrogated.\n+\n+\n+\n+\tThe sha1 identifier of the object.\n+\t(This is the sha1 of the uncompressed content.)\n+\n+-t\n+\tshow the object type identified by \n+\tOne of: blob/tree/commit\n+\n+\n+\tOne of: blob/tree/commit\n+\n+\n+################################################################\n+check-files\n+\tcheck-files ...\n+\n+Check that a list of files are up-to-date between the filesystem and\n+the cache. Used to verify a patch target before doing a patch.\n+\n+Files that do not exist on the filesystem are considered up-to-date\n+(whether or not they are in the cache).\n+\n+Emits an error message on failure.\n+\n+exits with a status code indicating success if all files are\n+up-to-date.\n+\n+\n+see also: update-cache\n+\n+\n+################################################################\n+checkout-cache\n+\tcheckout-cache [-q] [-a] [-f] [--] ...\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+restored - 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 before processing listed\n+\tfiles.\n+\n+Note that the order of the flags matters:\n+\n+\tcheckout-cache -a -f file.c\n+\n+will first check out all files listed in the cache (but not overwrite\n+any old ones), and then force-checkout file.c a second time (ie that\n+one _will_ overwrite any old contents with the same filename).\n+\n+Also, 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+\n+Intuitiveness is not the goal here. Repeatability is. The reason for\n+the \"no arguments means no work\" thing is that from scripts you are\n+supposed to be able to do things like\n+\n+\tfind . -name '*.h' -print0 | xargs -0 checkout-cache -f --\n+\n+which will force all existing *.h files to be replaced with their\n+cached copies. If an empty command line implied \"all\", then this would\n+force-refresh everything in the cache, which was not the point.\n+\n+Oh, and the \"--\" is just a good idea when you know the rest will be\n+filenames. Just so that you wouldn't have a filename of \"-a\" causing\n+problems (not possible in the above example, but get used to it in\n+scripting!).\n+\n+\n+################################################################\n+commit-id\n+\tcommit-id [tag]\n+\n+Returns the sha1-id of the commit object associated with given tag.\n+\n+tag\n+\ttag of commit object - defaults to the current HEAD.\n+\n+\n+################################################################\n+commit-tree\n+\tcommit-tree [-p ]* < changelog\n+\n+\n+################################################################\n+diff-tree\n+\tdiff-tree [-r] [-z] \n+\n+\n+################################################################\n+ls-tree\n+\tls-tree [-r] [-z] \n+\n+\n+################################################################\n+merge-base\n+\tmerge-base \n+\n+\n+################################################################\n+merge-cache\n+\tmerge-cache (-a | *)\n+\n+\n+################################################################\n+read-tree\n+\tread-tree [-m] \n+\n+\n+################################################################\n+rev-tree\n+\trev-tree [--edges] [--cache ] []\n+\n+\n+################################################################\n+show-diff\n+\tshow-diff [-q] [-s] [-z] [paths...]\n+\n+\n+################################################################\n+show-files\n+\tshow-files [-z] [-t] (--[cached|deleted|others|ignored|stage])*\n+\n+\n+################################################################\n+unpack-file\n+\tunpack-file.c \n+\n"},{"id":"1008","messageId":"Pine.LNX.4.61.0504201321380.2630@cag.csail.mit.edu","threadId":"174","inReplyTo":"42668C8D.3000209@dgreaves.com","subject":"Re: [PATCH] Some documentation...","fromName":"C. Scott Ananian","fromEmail":"cscott@cscott.net","sentAt":"2005-04-20T17:24:18Z","receivedAt":"2005-04-20T17:24:18Z","isPatch":true,"sender":{"key":"cscott@cscott.net","avatar":"https://gravatar.com/avatar/3551c2aefb299a0c45807f7677f5b26d8a5be4a4af359b4bf4fabbdd1f2b990e?d=mp&s=160"},"body":"On Wed, 20 Apr 2005, David Greaves wrote:\n\n> In doing this I noticed a couple of points:\n> * update-cache won't accept ./file or fred/./file\n\nThe comment in update-cache.c reads:\n/*\n * We fundamentally don't like some paths: we don't want\n * dot or dot-dot anywhere, and in fact, we don't even want\n * any other dot-files (.git or anything else). They\n * are hidden, for chist sake.\n *\n * Also, we don't want double slashes or slashes at the\n * end that can make pathnames ambiguous.\n */\n\nIt could be argued that './' is a special case... but at the moment this \nis definitely a designed 'feature' not a 'bug'.\n --scott\n\nBLUEBIRD SEQUIN SECANT Waihopai Honduras KUDOVE genetic KUJUMP SCRANTON \nDES AMLASH Indonesia SLINC cracking ESMERALDITE mustard Uzi KUSODA\n ( http://cscott.net/ )\n"},{"id":"1012","messageId":"426692D1.20304@dgreaves.com","threadId":"174","inReplyTo":"Pine.LNX.4.61.0504201321380.2630@cag.csail.mit.edu","subject":"Re: [PATCH] Some documentation...","fromName":"David Greaves","fromEmail":"david@dgreaves.com","sentAt":"2005-04-20T17:35:13Z","receivedAt":"2005-04-20T17:35:13Z","isPatch":true,"sender":{"key":"david@dgreaves.com","avatar":"https://gravatar.com/avatar/ca67bad50999edcdd137c9a65da2381557d175bea99ae956afdabc5785e42b79?d=mp&s=160"},"body":"C. Scott Ananian wrote:\n> On Wed, 20 Apr 2005, David Greaves wrote:\n> \n>> In doing this I noticed a couple of points:\n>> * update-cache won't accept ./file or fred/./file\n> \n> \n> The comment in update-cache.c reads:\n> /*\n> * We fundamentally don't like some paths: we don't want\n> * dot or dot-dot anywhere, and in fact, we don't even want\n> * any other dot-files (.git or anything else). They\n> * are hidden, for chist sake.\n> *\n> * Also, we don't want double slashes or slashes at the\n> * end that can make pathnames ambiguous.\n> */\n> \n> It could be argued that './' is a special case... but at the moment this \n> is definitely a designed 'feature' not a 'bug'.\n\nIndeed - I've been reading the code to document it as correctly as possible.\n\nBut I actually found this by running:\n\n find . -type f | xargs git add\n\nfor a new project - so I'd class it as user unfriendly...\nYes, I know how to get round it :)\n\nI have ensured that my next perl version of gitadd.pl (that I submitted \nto Petr) doesn't allow these files to be added - and it could even \ncleanse leading ./ and any /./ constructs.\n\nSo maybe it's left as documented behaviour and higher level tools must \nmanage the data they feed to it...\n\nI hope it's useful to raise these niggles now before changing them is \ntoo hard.\n\nDavid\n\n-- \n"},{"id":"1024","messageId":"Pine.LNX.4.58.0504201311300.6467@ppc970.osdl.org","threadId":"174","inReplyTo":"426692D1.20304@dgreaves.com","subject":"Re: [PATCH] Some documentation...","fromName":"Linus Torvalds","fromEmail":"torvalds@osdl.org","sentAt":"2005-04-20T20:15:19Z","receivedAt":"2005-04-20T20:15:19Z","isPatch":true,"sender":{"key":"torvalds@linux-foundation.org","avatar":"https://avatars.githubusercontent.com/u/1024025?v=4"},"body":"\n\nOn Wed, 20 Apr 2005, David Greaves wrote:\n> \n> So maybe it's left as documented behaviour and higher level tools must \n> manage the data they feed to it...\n\nThat was the plan.\n\nI agree that \"find . -type f | xargs update-cache --add --\" in _theory_ is\na nice thing to do. But in practice, you want to make sure that find \ndoesn't incldue the \".git\" directory and that we always use the canonical \nnames for all files etc etc.\n\nI could do it in the low-level tools (ie do pathname cleanup there), and\nindeed I did exactly that in the original code sequence. However, it very\nquickly became obvious that the low-level code really doesn't want to\ncare, and that it's a lot easier to just do it at a higher level when \nnecessary.\n\nFor example, if you have to add a sed-script or something that just \nremoves '^./' and \"^.git/\", then that's trivial to do, and it leaves the \ncore tools with a very clear agenda in life.\n\n\t\tLinus\n"}]}