Need help grasping some concepts

Hello, people.

I've been reading this list for quite a while now, and trying to understand what's going on, and wandering around in the code.

There are some concepts I'd like you to help me understand better:

1) What are plumbing and porcelain functions, methods, APIs... What's
the meaning of that classification and difference between the two?

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?

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?

If you prefer, just a link to some material I can read to understand those concepts better would be great. :)

Thank you very much!

On Tue, Feb 15, 2011 at 10:19:27PM -0200, João P. Sampaio wrote:

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.

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?).

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.

On Tue, 15 Feb 2011, Jo?o P. Sampaio wrote:

'plumbing' is the very low-level functionality, 'porcelain' makes use of the plumbing to get the job done in a user friendly way.

this is not a hard and fast separation, it is a set of terminology that grew because the initial git commands would do the jobe, but were ugly (and in some cases dangerous) to use. people wrote wrapper scripts that did sanity checking, offered good defaults, error messages meaningful to normal humans (as opposed to git developers), etc. There became a need to differentiate between the large population of wrappers and the underlying commands that they called. using a bathroom analogy, the core commands are the plumbing (it's there, but normally only experts understand it's care and feeding), and the things users are expected to use (the pretty, smooth fixtures that would be worthless without the plumbing under them)

git doesn't store directories at all. Git stores file contents and some metadata about the file (path, executable or not, but not ownership)

As such, if there is no file to store, git doesn't have anything to store.

so yes, an empty directory will not exist in a git repository (the workaround is to make a single, empty hidden file in that directory, typically something like .gitignore so that now there is a file to track)

yep.

David Lang

Thank you very much, Jeff and David. My problems are solved! :)