🕜

Git Workflows
Overview
This document’s purpose is to serve as an overview on best practices, anti-patterns, and git workflows. Git
is a robust version control solution and as such can be used in many ways. This makes it challenging to
find a one size fits all approach to best practices. These recommendations are meant to offer guidance and
trade offs but ultimately each team’s needs are different.

Goals
Control over released features

Reduce merge conflicts

Reduce code drift between environments

Common Patterns
Below are some common patterns seen in software development flows and how they map to our goals.
The pattern that works best for your team may not be the same pattern that works for another team.

Control Over Released Features

A common need is to release a set of features at a specific time. To that end there are two popular
strategies used to control when a feature releases.

Feature Branch
A feature branch is often used to keep a long running set of smaller changes together for a full feature
release. This has the benefit of keeping new code out of production while it is still being worked on.
Unfortunately these branches often have conflicts merging back into the main or master branch due to the
length of time between branching and merging.
Keeping feature branches short lived can help with merge conflicts. Often as part of workflows the main
branch is merged back into the feature branch in an attempt to get it in sync before merging back into
main. The problem with this approach is that it can unintentionally rollback changes and requires
meticulous conflict resolution in files. It also tends to litter your git history with unnecessary duplicate
commits.

Feature Flag
A feature flag is a code implementation that utilizes environment variables or dynamic configurations to
turn features on and off. This can be beneficial for workflows that use a continuous release process as it

Git Workflows 1
 allows code to continually be merged without being accessible in production. The downside is that for large
features the codebase can become littered with conditionals checking feature flags.
Often using feature flags sparingly and ensuring the feature code isn’t hooked up to any external access
points is the best way to keep in progress code from running in production while also not cluttering the
codebase. Additionally, using a database table or redis store allows features to be turned off and on at a
whim without restarting services or servers, unlike environment variables.

Reduce Merge Conflicts

Merge conflicts are a common problem in source control and although git handles it well in most cases
there are patterns that can help reduce how frequently a conflict occurs. Merge conflicts typically happens
when two developers change the same line of code in the same file. Or one developer modifies the file
while another deletes it.
Reducing the friction between developing features and merging those features into production increases
developer productivity. There are several ways to reduce merge conflicts while keeping a clean and
readable git history.

Small Pull Requests

Keeping code changes small per commit and pull request can reduce code review time. It also has the
benefit of having less change of running into a merge conflict. This practice is good regardless of workflow
but in the case of trunk based development it can cause problems if feature flags are not used and test
suites are lacking.
The upside is that it allows quickly applying patches to main and keeping environments in sync.

Fast Forward Merging

A fast forward merge allows you to apply your commits without conflict to the head of another branch. In
the case of merge conflicts, one common pattern to remedy the conflict is to rebase your set of changes on
top of the new work that made its way into the main branch, which is causing the conflict.

For example, lets say my branch only has 2 commits but there is a merge conflict with main branch. I can
run a rebase command that will attempt to grab the latest commits from main, apply them to your branch
and then apply your two commits after. This can become incredibly messy for a large set of commits that
continually change the same conflicted file. In those cases squashing first can help.

git rebase --onto main HEAD~2

Squash Merging
Squash merging can be done before a pull request is open or during the merge into main branch. The idea
of squash merging is to reduce unnecessary commits and temporary place holders that may happen as
part of the development cycle. Squashing should only be used if the commits that are being merged don’t
offer value as separate commits. It can help reduce “fixed typo” style commits and keeping main clean with
a series of feature commits.

Git Workflows 2
 Reduce Code Drift Between Environments
It is common to have different features released in different environments as they are tested and rolled out.
It can be challenging to track down bugs and understand the state of a product when the deployed code is
significantly different in each environment.
Drift between environments happens when environments have different code deployed from different
branches in a repository.

Continuous Integration
Using a continuous integration workflow to quickly transition work from development to production can help
cut down on the drift between environments. Continuous Integration workflows require an upfront
investment in ensuring pipelines are stable and autonomous.

Feature Flags
Often a form of Feature Flags will be used along with a Continuous Integration workflow to ensure large
features can be released in small chunks without being accessible in production environments. Using
Feature Flags requires engineering discipline to continuous audit and remove feature flags over time.

Comparing Workflows
Git Workflow | Atlassian Git Tutorial
Git is the most commonly used version control system today. A Git workflow is a recipe or recommendation for how to use Git to
accomplish work in a consistent and productive manner. Git workflows encourage developers and DevOps teams to leverage Git
effectively and consistently.
https://www.atlassian.com/git/tutorials/comparing-workflows

GitFlow
GitFlow utilizes different branches to simulate environments and bundles of changes. This pattern offers a
nice separation of concerns so that features aren’t accidentally released early but have the trade off of a
complex workflow where features will often face merge conflicts when it’s time to release.

Git Workflows 3
 Figure 1: Example GitFlow Workflow

Trunk
Trunk based development utilizes a main branch that all work is built off of and committed to. Often feature
flags are used so that different environments can have a different set of live features. The upside is that the
codebase isn’t fractured into different feature branches but it requires a commitment to engineering best
practices to ensure quality releases.

Figure 2: Example Trunk Workflow

Recommendations
Startups notoriously need room to pivot quickly and prototype new features. This need to constantly
innovate lends itself to a process that is quick and efficient for release. Being able to understand what code

Git Workflows 4
 exists and which environments have been deployed to is crucial for Product and QA to test the product.

With these goals in mind, a Trunk-based worked gives the most flexibility to move quickly while also
allowing us to manage different environments. Ensuring teams understand how and where to use feature
flags and that tests are written for new code will lead to less conflicts with separate feature releases.

Resources
Learn Git Branching

Learn Git Branching

An interactive Git visualization tool to educate and challenge!

https://learngitbranching.js.org/

Related Articles

Git workflow anti-patterns - Code with Jason

Here are some Git workflow anti-patterns I've observed in my career. This is not meant
to be an exhaustive list. These are just some of the common ones I've come across.
And as a side note: I firmly believe that the workflows I describe in the post are the best
https://www.codewithjason.com/git-workflow-anti-patterns/

From Git Flow to Trunk Based Development

I have worked with Git Flow for a few years and it helped me a lot to structure my Git
branches. However, I have encountered some problems with Git Flow, most of them
coming from long-living branches. The solution to solve those problems is trunk based
https://team-coder.com/from-git-flow-to-trunk-based-development/

5 Different Git Workflows

Over this article, we are discussing different git workflow strategies. Mainly git supports
5 different workflows. Here let's explore each one in detail. Git is one of the best version
control available now. It is so flexible. You can create your own workflow strategies
https://medium.com/javarevisited/5-different-git-workflows-50f75d8783a7

Git Branching Strategies vs. Trunk-Based Development - LaunchDarkly | LaunchDarkly

Gain a deeper understanding of Git branching strategies compared to trunk-based development.
And learn how to increase your deployment velocity with feature flag management.

https://launchdarkly.com/blog/git-branching-strategies-vs-trunk-based-development/

Git Workflows 5