Ferreting out git branches

posted: May 2, 2020

tl;dr: The command line isn’t the best way to see branches, so you have to dig deeper...

I’ve lost track of the number of different software Version Control Systems (VCS), or source control systems, or Software Configuration Management (SCM) systems that I’ve used over the decades. A partial list, in roughly chronological order for me, includes PVCS, ClearCase, CVS, Perforce, Subversion (SVN), and, for the past five years at two different companies, git and its cloud-based companion service, GitHub.

I can see why Linus Torvalds created git, as it is ideally suited for open source development. On a large, popular open source development project, there will be many developers scattered across the globe working asynchronously in a loosely coordinated (or uncoordinated) manner. Developers rarely meet face-to-face, and they can come and go from the project at their own whim. A developer may start working on a change and then walk away from it, never to be heard from again, leaving the code in an uncertain state.

Git tries to solve the challenges of developers working independently on the same codebase by fundamentally shifting the paradigm of how a version control system functions. Instead of “checking out” and locking individual files to allow one developer at a time to make changes, git allows all developers to see and modify all of the files at the same time. Only when changes are ready to be checked into a shared code branch do those changes need to be reviewed and selectively merged, by someone with authority for that branch. Hence the famous git pull request and somewhat infamous git merge process, although merging code is always a challenge in any version control system.

Git works well in enterprise settings too, which can also benefit from the developer independence, empowerment, and asynchronicity that git fosters. It works especially well when paired with GitHub, which removes the hassles of managing a git server and which adds a useful Web UI on top of git, along with other features for collaborating on code. There are similar cloud-based alternatives to GitHub such as GitLab, but GitHub has worked well enough to keep developers at my current and previous companies happy, except for the occasional outage.

A clean, well-structured, recent branch history

Developers can use git and GitHub in multiple ways. There’s the git command line, which some hardcore and masochistic developers prefer to use almost exclusively; the aforementioned GitHub Web UI; the freely available GitHub Desktop application; and a variety of open source and proprietary applications for various operating systems. I use a combination of the first three, although some of the happiest git/GitHub users that I know are developers who have paid for one of the better proprietary applications such as Tower or GitKraken, which allow them to completely avoid the git command line.

One of the biggest challenges of using git is managing the proliferation of branches. The canonical post entitled “A successful Git branching model” offers good advice on how and when to branch and merge the code, depending on the needs and deliverables of the particular project. In practice, branches tend to grow in number over time. It’s a lot easier to create a branch than to destroy one, since a final decision of what to do with the code on a branch must be made before deleting it forever. Git repositories with the bare minimum number of required branches are few and far between, although they do exist (see screenshot above). Often there are stale branches, and in process branches that have not yet been updated with the latest commits from the parent branch. When I dive into a codebase, one of the first aspects I focus on is the branch history, to understand where I should even begin to look at and modify the code.

The freely available tools for managing git, alas, do not provide good mechanisms for seeing and managing branches. The command line comes up especially short: a git log --graph command produces a character-based graph across many console lines, with some color, but the output for any sort of mildly complex codebase will be difficult to understand. Branch history is fundamentally a graph, and a GUI of some sort is hugely helpful for viewing it.

The GitHub Web UI does provide a graph view of branch history, but it is fairly well hidden and a surprising number of developers don’t know where it resides. Don’t look for a “Branches” or “Branch History” button - there isn’t one. Instead, first you have to click on the “Insights” tab (which is a fairly generic name - isn’t everything that the GitHub Web UI shows providing insights into the code?), then you click on the even more strangely named “Network” button in the sidebar. The branch history graph has nothing to do with the network that resides between your web browser and; alas, “network” is a term sometimes used for a “graph”. The visualization produced takes some getting used to: time is compressed, and the master branch (presumably the most important one) does not always appear at the top. However, I still recommend getting used to using the GitHub’s Insights->Network feature to view and manage branches.

Branch history was right at the top of the V1 GitHub Desktop app

The free GitHub Desktop app used to, back in the version 1 days, have built-in partial visualization of the branch history which showed the current branch relative to any other branch that the user selected. I considered it one of the most valuable features of the entire app, as I could (among other things) immediately see when the branch I was working on needed to be updated with the new commits on the parent branch. Alas, the GitHub team dropped that feature from version 2. Although many have asked for it to be added back, it has yet to make its return. While at my last company, I never bothered upgrading to version 2 and continued to use version 1 because I didn’t want to lose the branch history graph. Upon joining meltmedia, however, I bit the bullet and installed version 2, which forced me into using the aforementioned Insights->Network branch history graph.

If the GitHub team would make it easier for developers to see the branch history, by adding it back to the Desktop app and making it more prominent in the GitHub Web UI, I think it would help many developers do a better job of managing branches. Maybe Microsoft, which now owns GitHub, will improve this. The world would be a better place if they did.

Related post: Deleting early and often