A Git-Flow Explainer & How To Tutorial
What is Git-Flow?
When someone talks about Git-Flow, it could mean two things.
- A successful branching model (theory)
- A set of terminal commands that extend the regular git command set (practice)
In this post, I will cover both in order to get you ready to start using it today.
As a developer, Git is probably part of your daily work. You develop new features, you merge them later, then you release them, and finally, you fix potential bugs.
If there is no exact way of doing all these things, especially as a team, you quickly get in trouble. That’s why Git-Flow is here: It provides you with a precise work-“flow” (ha, I said it) to handle day-to-day Git business.
The Theory 😒
There is a lot explained in Vincent Driessen’s original introduction of Git-Flow, but I’ll try to keep it short.
There are two main branches: master and develop. They are the king and queen of Git-Flow Land, which explains why there is only one of each.
master is for production. Here sits the code that’s live, nice, and cozy. Not much happens here unless someone releases code to production.
develop is for code that’s currently in development. Features and bug fixes are merged here, so it’s a little bit busier.
There are three supporting branches: features, releases, hotfixes. Each of these branches has clear rules from where they originate and where they merge to. There can be multiple branches for any of these. (e.g., one for every feature that’s being developed, one per hotfix, etc.)
If you want to program a new feature or do some refactoring, this is what you want. You create a new feature branch and do your thing while leaving develop untouched. At some point, the feature finishes, and the produced changes merge back into develop. This is the kind of branch that’s probably being used the most, here is where all the action happens. All code that is still under development is somewhere in a feature branch.
This is also the perfect place if you want to do an experiment. If it doesn’t work, delete the branch, and nothing happens. Nobody needs to know.
When a feature branch gets created, it originates from the develop branch and merges back into develop.
The name of the branch will be features/name_of_your_feature.
You decide that you have enough well-tested fancy features to bring them to production. Then you make a release branch. No development should be done here, just minor last-minute bug fixes, version bumps, etc.
When a release branch gets created, it originates from the develop branch and merges back into master and develop.
The reason for this branch is that you can read the code for production while the develop branch can already receive new features for the next release.
When a release branch gets created, it gets assigned a version number. NOT EARLIER. Everything up to that point that’s sitting in develop branch is for “the next release”. The name of the branch will be releases/name_of_your_release.
Ay yes. You pushed your glorious code into production but just then notice a bug that needs fixing in production. There is no reason for panic; this happens to everyone. And, there is a Git-Flow solution for it: The hotfix branch. It grabs the code from production (master), the bug gets fixed, and the changes merge back in master and develop.
When a hotfix branch gets created, it originates from the master branch and merges back into master and develop.
The beautiful this here is that potentially unstable code in develop is not going to affect our hotfix, plus other developers can continue coding while the hero may fix the production bug.
Also, hotfix branches get a version number when it’s created, (e.g., 1.2.1 if your release was 1.2). Don’t forget to bump the version in your code when doing this.
The Practice 🤩
Yes, I am well aware that theory is tedious but necessary. So, good, we arrived at the fun part of this article.
Having read all of the above theory probably sounds like “a lot of work”, or “so many git commands, just to fix a bug”. Well, you’re in luck. There is a command tool, which extends the abilities of git to those of Git-Flow.
$ brew install git-flow
$ apt-get install git-flow
$ wget -q -O - --no-check-certificate https://raw.github.com/petervanderdoes/gitflow-avh/develop/contrib/gitflow-installer.sh install stable | bash
$ git flow init
This command initializes your repository as a “git flow” repository. You have to choose names for your branches, but I strictly advise you to leave it at the defaults (as described above). It also checks out the develop branch, which is from where you should go.
Now you’re ready to go!
You’ll see, it’s pretty straightforward. The best is just to play around a little bit with it on a test repository.
Create a feature
$ git flow feature start feature_name
Remember: Branches off develop
Finish a feature branch
$ git flow feature finish feature_name
Remember: Merges back into develop
Create a release
$ git flow release start version_number
Remember: Branches off develop
Finish a release
$ git flow release finish version_number
Remember: Merges into master and back into develop
Create a hotfix
$ git flow hotfix start version_number
Remember: Branches off master
Finish a hotfix
$ git flow hotfix finish version_number
Remember: Merges into develop and back into master
Bonus: For Lazy Developers
I wrote some scripts that make it easier to work with git-flow, or even git in general, and linked them to an alias in my terminal. You can check the project out from GitHub:
$ npm i -g @themarcba/lazy-git
There you can do cool things with the blink of an eye:
# Creates a new git-flow feature $ f my_feature # Finishes the current git-flow release $ rl finish # Pushes the current branch (whatever it is) $ p
Further documentation you can find in the link above.
I hope you're all set for now, and maybe you get to use Git-Flow in your next project. 😎