Proud to be a Moron – My Journey with Git

Martin, I enjoyed your post, one of several I found at the bottom of the page Subversion vs. Git: Myths and Facts.

I want to make a minor speculation as to why Git is so hard to learn and why so many people hate it.  Before doing so, a bit of background, I am also an "old guy".  Trained in Computer Science at UCLA then at UC Berkeley, several years working in research environments, then a couple more decades and counting doing work in the "real world" developing applications.  I have used CVS and Git a fair bit but my use of Git was vanilla, just your simple add/commit/pull/push/pull type uses with very little branching.

BTW, speaking of branching, I strongly recommend Gitflow considered harmful and it's followup Follow-up to 'GitFlow considered harmful' .

Recently I needed to explain Git to others so decided to read up and try to "really understand" Git.

I listened to a couple of good YouTube tutorials and then tried to start creating some example git sessions with simulated clients to illustrate various combinations and sequences of commands.

Doing so enabled me to do vanilla things but many questions arose.  When and why would my working files change?  What about the index? Why is Git claimed to be a "distributed" system when everyone who uses it synchronizes their work via a common remote repository?

I quickly encountered the usual problem of confusing overloading of functions, absurdly complex options, utter lack of documentation of semantics (e.g. explain semantics of commands based on input/change of state/output of each command with respect to the underlying objects (working files, index, local repo, current branch, other branches, etc.).

I decided to begin reading Scott Chacon's book ProGit.  I then realized something.  The people who expound and Git and even those who developed it do not know how to specify semantics!

I have done a bit of Linux kernel work so I already had the experience of seeing cultures where the code is the spec so the fact that the geniouses that bring us Linux don't know how to write or explain something to others did not come as a complete shock.  (-;

Here is an example of a letter I am penning to Scott Chacon that includes an  example (one of what is surely dozens or hundreds) of imprecise writinng.  I have not yet sent this email to Scott since I am not sure what email  address to use.  I have sent him a LinkedIn Connection request.

(letter to Scott Chacon

Hi Scott.

I am learning Git and see a paragraph in section 3.1 of Pro Git that seems incorrect:

The book states:

[BEGIN CITATION

Note:

Switching branches changes files in your working directory

It's important to note that when you switch branches in Git, files in your working directory will change. If you switch to an older branch, your working directory will be reverted to look like it did the last time you committed on that branch. If Git cannot do it cleanly, it will not let you switch at all.

END CITATION]

First "switching branches" is ill-defined. I will assume that "switching branches" means doing a `git checkout <branch>`.

If so, then the above statement is false in two cases:

case 1:
The branch does not yet exist. In this case, checkout will create a new branch, set HEAD to point to that branch, and leave the working directory untouched.

case 2:
The branch points to the same commit as the branch that HEAD points to. In this case, checkout will change HEAD to point to the branch but, again, leave the working files unchanged since both the old HEAD and  new HEAD point to branches that point to the same commit.

One caveat... if the phrases "changes files in your working directory" and "files in your working directory will change" include the null change, then arguably the above paragraphs are semantically correct.  But you have to admit, they are misleading.

It is NOT (always) the case that "when you switch branches in Git, files in your working directory will change".

Another misleading sentence in that section is:

"HEAD moves when you checkout"

Well, no, HEAD is assigned to. If you assign it to itself or to a branch that points to what it already points to, then it does not "move".  "Move" here is really an extraneous albeit convenient piece of terminology.  A better explanation of the semantics of checkout (well, checkout of a branch, as opposed to checkout of a file -- overloading is yet another issue) would include that checkout reassigns HEAD to point to the branch and if that branch points to a different commit modifies the working files to be as of that commit. There is more to say, such as what happens to the index, etc.

Ultimately, the confusion here is that git makes use of pointers (a branch is a pointer to a commit) and pointers to pointers (HEAD is a pointer to a branch) and is very sloppy in its documentation about describing the input/output semantics of operations that affect various pointers. Were Git documentation to be better specified by defining all actions in terms of input/output semantics on all git entities (HEAD, working files, the index, etc.), it would be easier to learn Git.

)

So, that's my comment for now.

Cheers,

Dennis Allard

allard@oceanpark.com