Gitflow is a git workflow model with predictable branching patterns, including developing new features, shipping out releases, and handling hotfixes. Vincent Driessen came up with the original idea in 2010. Eventually helper CLIs came out (which I recommend using) that hide away the complexity of the flow steps. I will write about these in an upcoming post. Although, I find it useful to know what is going on under the hood before committing to a new automation toolset.
This blog post goes through a quick demo of a project using gitflow, and the various steps it goes through, from working on a feature to releasing it into production.
You can clone the repo for this post here https://github.com/joeshub/gitflow-demo, or better yet follow along step by step.
Start a new sample git project
mkdir gitflow-demo && cd gitflow-demo
touch README
git commit -am "first commit"
git remote add origin git@github.com:joeshub/gitflow-demo.git
git push -u origin master
Develop branch
Our Working tree is always the develop branch in gitflow. Create a new develop branch locally and push it up. You should now have 2 branches upstream; master and develop.
git checkout -b develop
git push -u origin develop
Feature/xyz branches
New development in gitflow is always done in a feature branch, based off the develop working tree branch. Feature branches are by convention prefixed with feature and a slash, so the format is feature/foo
git checkout -b feature/foo develop
echo "console.log('foo');" >> foo.js
git commit -am "Adding foo file"
Now let’s assume we or another team member wants to simultaneously work on a different feature. We just create a new branch for it that tracks develop.
git checkout -b feature/bar develop
echo "console.log('bar');" >> bar.js
git commit -am "Adding bar file"
Merging features into develop
When ready, we send a pull request for the feature so it can be merged into the develop branch.
For simplicity, here we are going to just merge feature/foo back into develop without sending an PR, and push it back into develop.
git checkout develop
git merge feature/foo
git push
Rebasing from develop into a feature branch
Now let’s switch to our feature/bar branch. To get the latest changes that have landed in develop, we need to rebase from there. This will do a rewind/apply/replay so that your changes get added on top of any new updates to develop since you last pulled. You will want to do this rebasing from develop step often while working on a feature branch to avoid messy conflicts.
git checkout feature/bar
git rebase develop
# First, rewinding head to replay your work on top of it...
# Applying: Adding bar file
If you run a git log you will see your change to bar.js is now the last commit in your branch, and the other foo features that have already landed in develop.
git log --pretty=oneline --abbrev-commit
# 8b404a5 (HEAD -> feature/bar) Adding bar file
# 195431c (origin/develop, feature/foo, develop) Adding foo file
# fed3007 (origin/master, master) initial commit
Now we just repeat the same steps as before. We merge and push our feature upstream into develop. Again we are skipping the PR step here for simplicity.
git checkout develop
git merge feature/bar
git push
Releasing code
We always create release branches from develop. They are always prefixed with release/ in gitflow, for example release/1.0. This allows work to continue on develop, while we do a release. We then push our new release branch upstream. Normally a build & deploy step runs which pushes the release to a staging environment for testing and QA.
git checkout -b release/1.0 develop
git push -u origin release/1.0
Fixing issues after a release
Looks like QA found a bug! In this case, bar.js needs to output text in all caps.
To fix bugs found in a release branch, we make edits to the release branch and merge those changes back into the release branch, and normally this goes through a PR step as well. In larger teams, you can also create a new branch to track the bug fix and send a PR to merge this into the release branch.
echo "console.log('BAR');" > bar.js
git commit -am "hot fix bar.js"
git push
After bug fixes are released, we need to make sure to merge the release branch changes into our main develop branch.
git checkout develop
git merge release/1.0
git push
Releasing to production from master
Once a release is tested, it is then released into production. So we will merge our release branch into master as well.
git checkout master
git merge release/1.0
git push
Tagging master allows us to track the release version that’s currently out on production. Once we’ve tagged master we are finally ready to deploy that tag into production.
git tag v1.0.0
git push origin v1.0.0
Hot fixing bugs in production
After our release went out, marketing looked at the ALL CAPS and decided it wasn’t very nice. So we need to do a hot fix to our production code.
Using the gitflow naming convention, we create a branch off of master named hotfix/ and the bug being fixed, for example hotfix/fixes-bar-caps.
git checkout -b hotfix/fixes-bar-caps master
echo "console.log('bar');" > bar.js
git commit -am "hotfix removes all caps in bar.js"
Once ready, we will merge the hotfix into master. Then we’ll re-tag a release and push that tag to master.
git checkout master
git merge hotfix/fixes-bar-caps
git push
git tag v1.0.1
git push origin v1.0.1
We also need to make sure to merge the hotfix back into our develop branch, to keep it up to date with master.
git checkout develop
git merge hotfix/fixes-bar-caps
git push
Cleaning up branches after a release
After you’re done with a release, it’s good to clean up branches that have already been merged in. At this point you will have the following branches:
git branch -avv
# develop 00b2d00 [origin/develop] hotfix removes all caps in bar.js
# feature/bar 8b404a5 Adding bar file
# feature/foo 195431c Adding foo file
# hotfix/fixes-bar-caps 00b2d00 hotfix removes all caps in bar.js
# master 00b2d00 [origin/master] hotfix removes all caps in bar.js
# release/1.0 c26f0f3 [origin/release/1.0] hot fix bar.js
# remotes/origin/develop 00b2d00 hotfix removes all caps in bar.js
# remotes/origin/master 00b2d00 hotfix removes all caps in bar.js
# remotes/origin/release/1.0 c26f0f3 hot fix bar.js
To clean up we can delete the feature and hotfix branches.
git branch -d feature/foo
git branch -d feature/bar
git branch -d hotfix/fixes-bar-caps
git branch -avv
# develop 00b2d00 [origin/develop] hotfix removes all caps in bar.js
# master 00b2d00 [origin/master] hotfix removes all caps in bar.js
# release/1.0 c26f0f3 [origin/release/1.0] hot fix bar.js
# remotes/origin/develop 00b2d00 hotfix removes all caps in bar.js
# remotes/origin/master 00b2d00 hotfix removes all caps in bar.js
# remotes/origin/release/1.0 c26f0f3 hot fix bar.js
Automating gitflow with tooling
As I mentioned earlier, while knowing all the inner workings of gitflow is helpful, there are tools built that automate some of these steps. I’ll write a quick post on those tools next.