A Basic Branch Strategy for Git

While I'd hardly call myself an expert when it comes to using Git, I have been called upon to come up with and train others on a good strategy to use for keeping things organized and working well with source control and the attached Continuous Integration/Continuous Deployment pipelines.

Keep It Simple

Keeping thing simple make them easy to remember. Something easy to remember is easy to follow. And if we can get everyone to follow the same strategy, we'll meet our primary goal of having everything organized well.

Folders are an easy way to add addtional organization without much effort. Did you know you could put Git branches into folders? A lot of people I've worked with over the years didn't know about that either. This leads to the first rule of the branch strategy I use:

Only protected branches and folders can live at top level

That's simple enough, but you may be asking what branches should be the protected ones? Is it just main? This will depend on your environment specifically, but in the case of my environment I maintain two distinct protected branches: main and develop.

The Main Branch

Depending on your environment you may call this branch master, or even something else, but the purpose of this branch is to mirror your production environment. No one should be directly committing to this branch, ever. If you have CI/CD setup in your environment anything comitted to this branch could wind up being deployed to production, which isn't good for untested code!

The Develop Branch

I've seen this one called many things over the years as well, but the main claim to fame with this branch is that it should directly mirror your QA or Beta environment. This environment should be setup such that you can test code in a real deployment environment that is as similarly setup to your production environment as is allowable. That way you can weed out any bugs before promoting your code to the production environment. Again like the main branch, no one should ever be committing directly to this branch.

With that brief description out of the way, we're ready for the second rule:

No one should have permission to commit directly to protected branches

If your chosen Git product has a setting to prevent this, turn it on... and leave it on. Here's what it looks like in Gitlab:

These settings are found in the repo itself under Settings and then under Repository.

Don't Keep Things Too Simple

While it may seem like I'm contradicting myself, you also don't want to keep things too simple. I've worked places where instead of naming their branches in a descriptive way, the were all named "work-username" and put in the work folder. So you could never tell what any of the branches were intended to be doing ever. Everyone just maintained their own work branch and called it good.

Instead of doing that we want to use branch names that are descriptive in a meaningful way. I'm not implying branch names need to be 100 characters long and basically mimic the short version of the issue or anything, but it needs to tell us what its purpose is. And this leads into the next rule:

Branch names must be descriptive in a meaningful way

If you use an issue tracker like Jira this can be easy: just name your branches the ID of the card you're working on. If you don't use an issue tracker and can't or don't want to use one, then a short 15 character or less description should be used.

Keep the list of folders short

The last thing to talk about branch strategy wise is how to name your folders. For obvious reasons we don't want to just let the develops make their own folder names, because that could get out of hand quickly. The final rule to my branch strategy comes from this:

Use a set of 2 or 3 folders with specific purposes

But what folders to use? Usually I like to put everything into 3 different folders:

• Feature: Anything new that is adding onto the project. Adding a new page, or adding a new character... these are features
• Bugfix: Anything found during testing that needs to be addressed. Did that new feature do everything we wanted, but caused something else to not work? That's a bugfix.
• Maintenence: This is for anything that modifies an existing feature, but doesn't add anything meaningful. This is where you'd put things if your boss decided he didn't like the wording on a button. No functionality changes, nothing was wrong, but something needed to change.

Summary

Here are all the rules laid out in a list:

• Only protected branches and folders can live at top level
• No one should have permission to commit directly to protected branches
• Branch names must be descriptive in a meaningful way
• Use a set of 2 or 3 folders with specific purposes

These might not be the best rules, but they've worked for me so far.