The internal structure of Git

Git is rapidly becoming the predominant collaboration-versioning tool for computer programming projects. It’s light, fast, flexible, integrates perfectly with GitHub, and hundreds of important open source projects are based on it (e.g. Joomla, Zend Framework, etc.), so it is no surprise that its share of usage is exploding.

However, many people find it difficult to understand and use it. It is light, but maybe too light, as it comes with no decent user interface. It is flexible, but maybe too flexible, as it gives the user many options that could generate a feeling of confusion. It is fast, but maybe too fast, as it asks the user to jump right into the action giving him/her no feedback or map.

More in general, the top three reasons why people find Git difficult to use are, in order of importance:

  1. Git documentation is written by non-humans, and is directed to other non-humans
  2. Git online feedbacks are written by non-humans, and are directed to other non-humans
  3. Git command syntax is written by non-humans, and it is directed to other non-humans

Summed up: Git has a non-intuitive, often confusing naming structure.

Just to give you an example, the versions of your projects are called _commit_s, but are placed in the objects directory (I guess creating a commits directory was too obvious). The branches are small subprojects of your main project, so that you can work on any small detail you desire and at the end, either toss it or integrate it with the main project. So obviously branches are stored in a branches directory, right? Wrong. They are stored in a refs directory (as reference, what else).

Git is a terrific product with a terrible naming convention.

Almost all Git documentation on the internet is based on the idea that giving you simple, basic commands will make you (or me) comfortable enough with Git. That did not work for me, as I felt even more confused the more I was working with it. Git add, git commit, git checkout… what does it all really mean?

I found that when dealing with complex objects (and Git is definitely complex) a lower level approach works best for me, so I collected my thoughts in a structure that made sense to me. I hope it will make sense also to you.


See also