{"thread":{"id":"26515","subject":"Need help grasping some concepts","startedAt":"2011-02-16T00:19:27Z","lastAt":"2011-02-16T13:14:58Z","messageCount":4,"participants":["João P. Sampaio","Jeff King","david@lang.hm"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"161248","messageId":"AANLkTi=RfK13jUiu+tT21M-dm65tPrkr+s8asa+nZdak@mail.gmail.com","threadId":"26515","inReplyTo":null,"subject":"Need help grasping some concepts","fromName":"João P. Sampaio","fromEmail":"jpmelos@jpmelos.com","sentAt":"2011-02-16T00:19:27Z","receivedAt":"2011-02-16T00:19:27Z","isPatch":false,"sender":{"key":"jpmelos@jpmelos.com","avatar":"https://gravatar.com/avatar/368a5d2863df47838b2d07638023313133a3495266b986462ababa9c841efcf8?d=mp&s=160"},"body":"Hello, people.\n\nI've been reading this list for quite a while now, and trying to\nunderstand what's going on, and wandering around in the code.\n\nThere are some concepts I'd like you to help me understand better:\n\n1) What are plumbing and porcelain functions, methods, APIs... What's\nthe meaning of that classification and difference between the two?\n\n2) What's going on about cache-tree not being able to handle empty\ntrees, or something like that? You mean Git doesn't store empty\ndirectories in repositories?\n\n3) And what are symbolic references? Are they just an alias I can\nattach to branches and tags, like symbolic links in Linux that I can\nattach to folders and files?\n\nIf you prefer, just a link to some material I can read to understand\nthose concepts better would be great. :)\n\nThank you very much!\n\n-- \nJoão Paulo Melo de Sampaio\nComputer Engineering Student @ UFSCar\nWebsite: http://www.jpmelos.com\nTwitter: twitter.com/jpmelos (@jpmelos)\n"},{"id":"161251","messageId":"20110216024832.GB7085@sigill.intra.peff.net","threadId":"26515","inReplyTo":"AANLkTi=RfK13jUiu+tT21M-dm65tPrkr+s8asa+nZdak@mail.gmail.com","subject":"Re: Need help grasping some concepts","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-02-16T02:48:32Z","receivedAt":"2011-02-16T02:48:32Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Feb 15, 2011 at 10:19:27PM -0200, João P. Sampaio wrote:\n\n> 1) What are plumbing and porcelain functions, methods, APIs... What's\n> the meaning of that classification and difference between the two?\n\nGit doesn't provide a linkable C API. Instead, the only official API is\nthe interface provided by the commands, which often have options made\nfor scripting around them. In the beginning, this included all of the\ncommands known as \"git-core\", and it was assumed that people would\nscript around them to write a nice version control system. Git-core was\nto be the \"plumbing\", and the wrapper VCS would be the \"porcelain\", just\nas plumbing pipes in your bathroom do all the hardwork under the\nporcelain fixtures like your sink, tub, and toilet.\n\nOver time, git-core got more user-friendly and people decided to use it\ndirectly as a version control system. New commands were introduced that\nduplicated some functionality, but in a much easier way. For example,\nthere is nothing that \"git add\" can do that you can't do by scripting\n\"git update-index\". But its interface is much easier to use.\n\nThese new commands became known as porcelain commands, while the\nlow-level commands were marked as plumbing commands (and the \"git-core\"\nname was dropped to just \"git\"). Porcelain commands are generally used\nby users, and their interface is subject to change as we think of more\nconvenient ways for users to interact with them. Plumbing commands\npromise to have a stable interface, making them safer to use in scripts.\n\n> 2) What's going on about cache-tree not being able to handle empty\n> trees, or something like that? You mean Git doesn't store empty\n> directories in repositories?\n\nNo, it doesn't. The git data structure can conceptually handle it pretty\neasily, but there is some work to be done to handle it in the index.\nPlus there are some corner cases about when to create and destroy such\ndirectories (e.g., you may switch from a commit with an empty directory\nto a commit without it, but there are untracked files in the directory.\nWhat should happen to those files?).\n\n> 3) And what are symbolic references? Are they just an alias I can\n> attach to branches and tags, like symbolic links in Linux that I can\n> attach to folders and files?\n\nSometimes we want to make a reference not to a particular sha1, but to\nanother reference. The main example is the \"HEAD\" reference. It is a\npointer to a reference which contains the branch tip, and when we update\nHEAD via \"git commit\", we are actually updating the pointed-to branch\ntip.\n\nEarly on, this was done using a symbolic link in the .git directory. But\nnot all platforms have symbolic links. So now we have symbolic refs,\nwhich are basically text files that work like symbolic links.\n\n-Peff\n\nPS Those answers are all off the top of my head without doing any\nresearch in the archive, and some of those things predate me working on\ngit. And I tried to explain them in a succint way that would make sense\nto a newer user. So please take the historical accuracy of my \"in the\nbeginning\" stories with a grain of salt.\n"},{"id":"161252","messageId":"alpine.DEB.2.00.1102151842210.9902@asgard.lang.hm","threadId":"26515","inReplyTo":"AANLkTi=RfK13jUiu+tT21M-dm65tPrkr+s8asa+nZdak@mail.gmail.com","subject":"Re: Need help grasping some concepts","fromName":"","fromEmail":"david@lang.hm","sentAt":"2011-02-16T02:50:28Z","receivedAt":"2011-02-16T02:50:28Z","isPatch":false,"sender":{"key":"david@lang.hm","avatar":null},"body":"On Tue, 15 Feb 2011, Jo?o P. Sampaio wrote:\n\n> I've been reading this list for quite a while now, and trying to\n> understand what's going on, and wandering around in the code.\n>\n> There are some concepts I'd like you to help me understand better:\n>\n> 1) What are plumbing and porcelain functions, methods, APIs... What's\n> the meaning of that classification and difference between the two?\n\n'plumbing' is the very low-level functionality, 'porcelain' makes use of \nthe plumbing to get the job done in a user friendly way.\n\nthis is not a hard and fast separation, it is a set of terminology that \ngrew because the initial git commands would do the jobe, but were ugly \n(and in some cases dangerous) to use. people wrote wrapper scripts that \ndid sanity checking, offered good defaults, error messages meaningful to \nnormal humans (as opposed to git developers), etc. There became a need to \ndifferentiate between the large population of wrappers and the underlying \ncommands that they called. using a bathroom analogy, the core commands are \nthe plumbing (it's there, but normally only experts understand it's care \nand feeding), and the things users are expected to use (the pretty, smooth \nfixtures that would be worthless without the plumbing under them)\n\n> 2) What's going on about cache-tree not being able to handle empty\n> trees, or something like that? You mean Git doesn't store empty\n> directories in repositories?\n\ngit doesn't store directories at all. Git stores file contents and some \nmetadata about the file (path, executable or not, but not ownership)\n\nAs such, if there is no file to store, git doesn't have anything to store.\n\nso yes, an empty directory will not exist in a git repository (the \nworkaround is to make a single, empty hidden file in that directory, \ntypically something like .gitignore so that now there is a file to track)\n\n> 3) And what are symbolic references? Are they just an alias I can\n> attach to branches and tags, like symbolic links in Linux that I can\n> attach to folders and files?\n\nyep.\n\nDavid Lang\n"},{"id":"161300","messageId":"AANLkTinyEa11BSB9SxrZL=qjNDGqS4FKH1mfGQwoEab1@mail.gmail.com","threadId":"26515","inReplyTo":"alpine.DEB.2.00.1102151842210.9902@asgard.lang.hm","subject":"Re: Need help grasping some concepts","fromName":"João P. Sampaio","fromEmail":"jpmelos@jpmelos.com","sentAt":"2011-02-16T13:14:58Z","receivedAt":"2011-02-16T13:14:58Z","isPatch":false,"sender":{"key":"jpmelos@jpmelos.com","avatar":"https://gravatar.com/avatar/368a5d2863df47838b2d07638023313133a3495266b986462ababa9c841efcf8?d=mp&s=160"},"body":"Thank you very much, Jeff and David. My problems are solved! :)\n\n-- \nJoão Paulo Melo de Sampaio\nComputer Engineering Student @ UFSCar\nWebsite: http://www.jpmelos.com\nTwitter: http://twitter.com/jpmelos (@jpmelos)\n"}]}