William Vaughn

The gittutorial manual review

The git tutorial manual is actually two separate manuals, gittutorial(7) and gittutorial-2(7). I will be reviewing them both in this post, followed by some brief summaries of what I learned or thought was noteworthy while reading them.

Review

I think if I were an absolute beginner and I started with these tutorials, the gittutorial would be slightly helpful, and the gittutorial-2 would be confusing. I don’t think the manual is where true beginners typically start with git. I would guess many learn the basics of git as part of the learning the basics of programming. The gittutorial manual is a reiteration of the basics. It gives enough context on git to start using it, though I wouldn’t say it does so particularly well. There are probably better and more practical getting started tutorials available from a quick google search. This manual feels outdated because the examples are of Alice and Bob sharing a single filesystem where they both have user directories and their own repositories. That’s not typically how we work with git these days, and I don’t think it’s a helpful distraction for todays beginner programmer.

In contrast, the gittutorial-2 manual quickly gets you straight into the internal architecture of git in a way that could be overwhelming for a beginner. As a developer who has been using git for 10 years without ever reading the manual though, this was illuminating! This felt like information I had been missing. While it may be overwhelming for a beginner perhaps it is best to be forced to go a little deeper in order to build a foundational and lasting understanding. I think I would recommend a beginner to read gittutorial-2 in their first few months of learning, but not right away. This manual aims to teach how to think about a git repository as a system and database of information. I think that vantage can potentially be a leg-up in learning to wield git beyond the basics.

gittutorial

Some things I learned and plan to use.

log and .. ranges

git log --stat --summary

This is a nice view on the log.

git fetch /home/bob/myrepo master
git log -p HEAD..FETCH_HEAD

The usage of git fetch and the FETCH_HEAD symbol as a way to peek at code. This also demonstrates the concept of commit ranges, which I rarely use and probably could use more.

The two-dot .. form means: show everything that is reachable from FETCH_HEAD, but exclude anything that is reachable from HEAD. The example in the manual is a peek at Bob’s changes absent of Alice’s changes.

The three-dot ... form means: show everything that is reachable from either, but exclude anything that is reachable from both. This is a view of Alice’s changes combined with Bob’s changes.

git log --since="2 weeks ago" # commits from the last 2 week

Could be handy occasionally.

gitk

I didn’t know this existed. Its a Tkinter based UI for git! It’s pretty old-school cool. I’m happy that it exists and I’m going to find reasons to open it up in strange situations when pairing with colleagues, just to see their reactions.

git show

An introduction to seeing the details of commits. I think I often go straight to github when I need to find a commit, when it may be much easier to use git show.

Git ancestry targeting:

git grep

Search a commit for a pattern. I did not know this existed.

gittutorial-2

Objects

Git “commit” objects refer to snapshots of the whole directory structure in a repo known as a “tree”. Each directory is a tree object in git, and file data is stored in “blobs”. The trees can themselves refer to other trees (sub directories). Using git cat-file and git ls-tree you can introspect the objects stored by git.

The index file

The index let’s git show us the difference between the state of the working directory and the last commit. By default git uses the index to create commits, not the working directory. What I learned here, which I already knew by using git was I can use git add to manipulate the index in order to shape commits, without necessarily discarding my working tree. In practice I don’t really do this very often, I just add everything to a commit.

Conclusion

The gittutorial-2 is worth a look, you’ll learn about how git works in a way which should help you master it in the long run. There’s still a lot more for me to read about git. My plan is to move on to the giteveryday manual. I’ve also been trying to work my way through the Git User’s Manual, as well as the manual for Magit; a great interface to git from within Emacs. It doesn’t shield you from git, but like gitk, it gives you a different way to visualize and manipulate the database of git objects.

Go RTFM! And as always, thanks for reading the manual review!