On Tue, Feb 15, 2011 at 10:19:27PM -0200, JoÃo P. Sampaio wrote: > 1) What are plumbing and porcelain functions, methods, APIs... What's > the meaning of that classification and difference between the two? Git doesn't provide a linkable C API. Instead, the only official API is the interface provided by the commands, which often have options made for scripting around them. In the beginning, this included all of the commands known as "git-core", and it was assumed that people would script around them to write a nice version control system. Git-core was to be the "plumbing", and the wrapper VCS would be the "porcelain", just as plumbing pipes in your bathroom do all the hardwork under the porcelain fixtures like your sink, tub, and toilet. Over time, git-core got more user-friendly and people decided to use it directly as a version control system. New commands were introduced that duplicated some functionality, but in a much easier way. For example, there is nothing that "git add" can do that you can't do by scripting "git update-index". But its interface is much easier to use. These new commands became known as porcelain commands, while the low-level commands were marked as plumbing commands (and the "git-core" name was dropped to just "git"). Porcelain commands are generally used by users, and their interface is subject to change as we think of more convenient ways for users to interact with them. Plumbing commands promise to have a stable interface, making them safer to use in scripts. > 2) What's going on about cache-tree not being able to handle empty > trees, or something like that? You mean Git doesn't store empty > directories in repositories? No, it doesn't. The git data structure can conceptually handle it pretty easily, but there is some work to be done to handle it in the index. Plus there are some corner cases about when to create and destroy such directories (e.g., you may switch from a commit with an empty directory to a commit without it, but there are untracked files in the directory. What should happen to those files?). > 3) And what are symbolic references? Are they just an alias I can > attach to branches and tags, like symbolic links in Linux that I can > attach to folders and files? Sometimes we want to make a reference not to a particular sha1, but to another reference. The main example is the "HEAD" reference. It is a pointer to a reference which contains the branch tip, and when we update HEAD via "git commit", we are actually updating the pointed-to branch tip. Early on, this was done using a symbolic link in the .git directory. But not all platforms have symbolic links. So now we have symbolic refs, which are basically text files that work like symbolic links. -Peff PS Those answers are all off the top of my head without doing any research in the archive, and some of those things predate me working on git. And I tried to explain them in a succint way that would make sense to a newer user. So please take the historical accuracy of my "in the beginning" stories with a grain of salt. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html