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!
--
João Paulo Melo de Sampaio
Computer Engineering Student @ UFSCar
Website: http://www.jpmelos.com
Twitter: twitter.com/jpmelos (@jpmelos)
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.
On Tue, 15 Feb 2011, Jo?o P. Sampaio wrote:
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?
'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)
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?
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)
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?
yep.
David Lang