In this post I will talk to you about git flow and how you can use it to improve best practices in your application development life cycle. Usually the development life cycle mainly consists on repeating the iteration process described below:
Create new features;
Launch new release;
Fix unexpected errors in the launched release.
In the following topics, I will describe how git flow will help you to achieve that iteration process.
1. What is git-flow
First of all, let me explain what is git flow. Git flow is a set of git extensions that provides high-level operations that implements Vincent Driessen’s branching model. This model has since been implemented in a number of variations and proved to be a successful approach. This branching model is based on two main branches with special meaning:
The develop branch which contains the ongoing development line and gathers all finished improvements and fixes.
The master branch which contains the stable release line. Its head represents the latest stable release.
Besides the develop and master branches which are unique, this model also defines other three kind of branches that are created during the development life cycle. Those branches will be described later on this post.
To demonstrate how to use git flow for application development, we’ll create a very simple web site composed by an homepage and a contacts page.
2. Setup git-flow
Now that we know what git flow is, it is time to install it on you machine. Git flow extensions can be installed on OS X, Linux and Windows but you first need to have a working git installation.
To setup git flow on linux (debian based) you can execute the following command:
sudo apt-get install git-flow
To setup git flow on OS X you can use homebrew (OS X package manager) and execute the following command:
brew install git-flow
To setup git flow on Windows (with Cygwin installed with util-linux and wget packages) you can execute the following command:
wget -q -O - --no-check-certificate https://github.com/nvie/gitflow/raw/develop/contrib/gitflow-installer.sh | bash
For other systems or for more detailed instructions please check the git flow wiki.
Note: To use git flow commands with auto completion, check instructions here.
3. Prepare your repository
Now that we have git flow ready to use, it’s time to prepare our git repository to use git flow. To achieve that we will create an empty directory and execute the initialization command:
mkdir git-flow-demo cd git-flow-demo git flow init -d
This last command initializes a new git repository, creates the develop and master branches and makes some configurations in your local git configuration file. The -d option indicates to initialize the repository using default branch names. Without this option you can initialize the repository in an interactive way.
Notice that the develop branch was automatically checked out after the initialization.
You could also execute this command in an existing git repository, in that case the code in your master branch will be copied to the develop branch.
If it’s not already set globally, don’t forget to configure your user within the git repository by issuing the following commands:
git config --local user.name "Your name" git config --local user.email "email@example.com"
4. Create features
In order to create our simple web site, we’ll have to implement two features:
The homepage feature
The contacts page feature
So, let’s create our first feature. To do that execute the following command in the root of your repository.
git flow feature start homepage
This command will create a new feature branch called feature/homepage that deviates from the last commit on the develop branch. This allows you to isolate the code you’ll create and avoid breaking code on the develop branch.You can also notice that the newly created feature branch is automatically checked out.
Let’s create the file index.html and put the following content in it.
<!DOCTYPE html> <html> <head> <title>Git flow demo</title> </head> <body> <h1>Git flow demo</h1> <p>This is just a simple site to demonstrate git flow workflow</p> </body> </html>
Now that we completed our site home page, it is time to commit our changes and finish the current feature. To do that execute the following commands:
git add index.html git commit -m "Added home page" git flow feature finish homepage
The last command will merge the commits on the feature branch back to the develop branch and delete the feature branch.
Now we’ll repeat the same process to create the contacts page feature. Execute the command bellow to create the contacts page feature branch.
git flow feature start contacts-page
Now create the file contacts-page.html and put the following content in it.
<!DOCTYPE html> <html> <head> <title>Contacts page</title> </head> <body> <h2>Byte&Code contacts page</h2> <p><a href="mailto:firstname.lastname@example.org" title="Byte&Code">Byte&Code email</a></p> </body> </html>
Edit the index.html file and add a hyperlink to the contacts page.
... <p><a href="contacts-page.html" title="Contacts">Contacts</a></p> ...
Again commit the changes and finish the current feature.
git add contacts-page.html git add index.html git commit -m "Added contacts page" git flow feature finish contacts-page
Note that with git flow, you can work on multiple features. For that, ensure that you commit all changes on the current branch and then checkout the feature branch you want to work with.
5. Launch new release
Now that we’ve create two features of our web site, it’s time to prepare a new release. To prepare our first release, execute the following command:
git flow release start v0.1.0
Similarly to features, the above command will create a new branch that deviates from the last commit on develop branch but this time the created branch will have the prefix “release/”. This branch must exclusively be used to adjust code or fix bugs. You may not use this kind of branch to add new functionalities.
Let’s add the release version number to the home page so you can identify the current version of our site. Edit the index.html and change the title element with the following content.
... <title>Git flow demo (v0.1.0)</title> ...
Now that we’ve adjusted our code for the new release, it’s time to commit the changes and launch the release. For that execute the following commands:
git add index.html git commit -m "Added version number to the homepage title" git flow release finish v0.1.0
The last command will execute the following operations:
Merge the release/v0.1.0 branch back to the develop branch
Merge the release/v0.1.0 branch to the master branch
Create a tag with the release branch name (v0.1.0)
Delete the release branch
At this point, the head of develop and master branches are the same and it is marked by the tag v0.1.0. You can now send your site to production with version v0.1.0 at any time, by issuing the following command on the repository:
git checkout v0.1.0
6. Creating hot fixes
Let’s say that we found out that an error exists on production and we have to fix the problem urgently. We can create an hot fix to solve the problem. We assume that the release on production corresponds to the last release on the master branch, in this example we’re talking about the version v0.1.0. Execute the following command:
git flow hotfix start v0.1.2
As opposed to features and releases branches, the last command will create a new hot fix branch deviating from the last commit of the master branch.
Let’s correct the error found on contacts page. In this page I made a mistake on purpose. I used the h2 html element instead of the h1 element. Edit contacts-page.html and correct the error.
... <h1>Byte&Code contacts page</h1> ...
Now that we solved the problem, commit the changes and finish the hot fix.
git add contacts-page.html git commit -m "Correct contacts page title" git flow hotfix finish v0.1.2
The last command will execute the following operations:
Merge the hot fix branch back to the master branch;
Merge the hot fix branch back to the develop branch in order to correct also the error on the development line.
Create a new tag v0.1.2 to mark this commit;
You can now deploy the new version (v0.1.2) with the bug correction.
In this post, we saw the basic steps of an application development using git flow. We created a couple of features, launch a new release and then correct a problem found on a launched release. Git flow allows more advanced features that I didn’t cover on this post. You can find more information in this nice and useful cheatsheet.
I hope this post will help you to start working with git flow. Feel free to comment.