My Git Book & Sandbox

tl;dr: I am not satisfied with the Git tutorials I have seen so I have written one myself. You can see its draft here:

We have had 14(!) new developers join our team(s) in the last 8 weeks. Every single one of them will be using Git from day one. We have an aggressive deployment process using a centralized workflow – no dictator/lieutenants or any of that, every single developer pushes and pulls to and from the main repository. Our new devs are new – often new to Unix, new to Web development, and certainly new to Git.

Git is hard. Git is complicated. All the more so as the team size grows. Every single dev is expected to handle the complications of branching, staging, diffing, committing, merging, remotes, resets, rebasing, conflict resolution, and so on. HEAD. Index. Stash.

Git follows the Unix philosophy – everything is possible, but nothing is obvious. Git’s “porcelain” or ‘surface’ commands would be considered ‘plumbing’ anywhere else. One solution would be to use a GUI, but that would just be hiding the problem (though perhaps this option should not be dismissed so easily).

Regrettably, it has been my experience that most Git documentation and tutorials are either of the ‘Hello Branch’ variety or of the ‘git plumbing internals’ persuasion, and fail to hit the balance of robustness and accessibility new devs need. This is par for the course with many complicated/technical topics: those who understand it well, struggle to explain it to those less comfortable. You can always tell people to read the man pages, but when it’s your devs and your code on the online, fixing the problem is more important displaying your hard-coreness. Otherwise, new devs just pick up the minimum they can/need in order to survive, and (ab)use Git to their own (and our) detriment.

Lastly, explaining something is always the best way to learn, and explaining Git has been a great for me to improve my Git understanding.

So anyway, I am undertaking a humble effort to create a better Git tutorial. This will include:

  • A single-command setup for a local Git sandbox, so devs can experiment with advanced command without fear of destroying their (or others’) work.
  • A step-by-step walk-through of important Git commands and settings, explaining the reasoning and practicing together in said tutorial.
  • An (admittedly) opinionated dictation of the correct workflow when working on a feature.
  • A (hopefully) reference-style index for those just coming for a quick ‘how do I do that’.

Necessarily, many of the issues will be simplified or approximated, to facilitate understanding over exactness.

I have personally found myself asking about and later explaining these topics over and over. It took me some time to come around to creating my own Git sandbox to practice. Hopefully this will at least help some people, some of the time.

Naturally, this is not the first or last Git tutorial, sandbox, or even book. That’s fine – I am not trying to compete with anyone else, just fill the void my personal way, which I felt has been lacking.

Further drafts will hopefully be prettified and strengthened. Contributions will of course be welcome.