Daniel Reifsnider, Sony Interactive Entertainment
May 15, 2019

This article seeks to provide a short explanation of the benefits of having a branching methodology. I’d like to start this article off with two statements. First, I apologize for the pun in the title. Second, I absolutely agree with the title’s statement.

While branching is one of the things that makes Git as a version control system so powerful, without any strategy or methodology behind it, branching can become dangerous rather quickly especially when multiple people are involved. Having an agreed upon, adhered to, and consistent branching method can help mitigate many of the basic problems teams encounter when using Git.

Wait, what’s Git again?

Before jumping straight into the deep end, let’s take a quick moment to review what Git is exactly, and how such an unimposing name has come to define one of the most popular file version control systems used today.

Without going into all the technicalities, Git in the most basic sense is a change tracker. It tracks the changes you make to text-based files and holds records of these changes in what’s known as commits. Commits are “pointers” or references to a set of changes and the files in which those changes occurred. In turn, branches are “pointers” to a set of commits.

I often like to think of commits and branches as buckets: a commit is a bucket that contains some changes made to specific files, and a branch is a bucket that contains multiple commit buckets. Buckets in buckets:

Let’s talk branches

One of the great, but terrifying things, about Git is that you’re free to create branches in a repository whenever you please. You can seemingly have an unlimited amount of branches in a single repository, and each one of these branches can have a whole host of different changes. In theory, each team member could have their own independent branch in a single repository, even if multiple team members are simultaneously working on the same set of files and content.

While it might seem like a good idea at first to separate out each individual’s work into an unrestricted amount of branches to avoid stepping on each other’s toes (so to speak), at some point each individual’s work will eventually need to be brought together, or merged, to have a complete set of content.

This can, and will most likely, result in conflicting changes to the content.

Take the following situation for example:

Amanda and Alex are both working on a publication, and all the files for the publication are stored in one Git repository. Amanda is creating content in her own separate branch named Amanda-Branch, and Alex is creating content in his own separate branch named Alex-Branch:

They eventually get to a place where they are finished creating content and are ready to generate the publication and send it to reviewers.

How do they merge their files and changes together? Amanda could merge Alex’s branch into her own and then generate the publication from her branch. Alex could do the same with his own branch. They could create a third branch and then merge both of their branches into this third branch. What if they both created and edited some of the same files, but because they’re human, each of these files contains significantly different content? Who gets to decide which content to keep and which content to discard?

Let’s say they eventually answer these questions, generate the publication, and send it out to reviewers. Now they have a handful of changes that the reviewers have requested. What branch should they make the changes to? Do they continue using their individual branches? Do they use the third branch that contains both of their work? Do they each make additional branches based off of their existing branches? How do they ensure they’re not duplicating each other’s work or making conflicting changes?

This is where having a consistent branching method that all team members adhere to can resolve and mitigate many of these questions for Amanda and Alex.

Branching methodologies

Okay so, let’s just pick a branching method and stick to it right? Unfortunately, it’s not quite as simple as that.

While branching methods help mitigate many of the common questions and issues Amanda and Alex faced above, they also define the workflow in which work is done across the team. This is an important aspect because while the workflow answers many questions (What should we do next? Follow the workflow!) it also dictates that all team members follow it. If an individual on a team were to deviate from the workflow because say they disagreed with it, then issues would come about sooner or later. Much in the case of technical documentation, consistency is key.

So before deciding on a branching method, it’s important to first analyze your team’s current workflow and either create a branching method or choose an existing one that best fits your workflow. As a team, ask yourself:

  • Do you want to separate out content that’s currently being created from the finalized, published content?
  • Do you want the option to review content while it’s being created?
  • Do you need to fix errors immediately or can they be fixed with the next version?
  • Is it important to track versions of the content?
  • Will you ever “rollback” your content to a previous version?

While the above list is not exhaustive, the answers to these questions will help inform the branching method that best fits your team.

Some of the more popular and well-documented branching methods are:

These existing branching methods might not take into account all the various aspects of your current workflow. Because there’s rarely a one size fits all branching method, expect to make agreed-upon modifications to one of these methods, come up with your own method, or change your current workflow. While a benefit of using an established branching method is that it often enforces the workflow to prevent mistakes (GitFlow CLI in particular), you are also free to create your own.

Regardless of whether you create your own or decide to use an existing method, the most important aspects of the branching method you choose are that it’s agreed on by all team members and that it’s consistently followed.