A Git Workflow is a recipe or recommendation for how to use Git to accomplish work consistently and productively.

Gitflow Workflow

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 users to leverage Git effectively and consistently. Git offers a lot of flexibility in how users manage changes. Given Git's focus on flexibility, there is no standardized process on how to interact with Git. When working with a team on a Git managed project, it’s important to make sure the team is all in agreement on how the flow of changes will be applied. To ensure the team is on the same page, an agreed-upon Git workflow should be developed or selected. There are several publicized Git workflows that may be a good fit for your team. 1

When evaluating a workflow for your team, it's most important that you consider your team’s culture. You want the workflow to enhance the effectiveness of your team and not be a burden that limits productivity. Some things to consider when evaluating a Git workflow are:2

  • Does this workflow scale with team size?
  • Is it easy to undo mistakes and errors with this workflow?
  • Does this workflow impose any new unnecessary cognitive overhead to the team?

Gitflow Workflow

The Gitflow Workflow was first published in a highly regarded 2010 blog post from Vincent Driessen at nvie. The Gitflow Workflow defines a strict branching model designed around the project release. This workflow doesn’t add any new concepts or commands beyond what’s required for the Feature Branch Workflow. Instead, it assigns very specific roles to different branches and defines how and when they should interact.1

Gitflow is ideally suited for projects that have a scheduled release cycle. This workflow doesn’t add any new concepts or commands beyond what’s required for the Feature Branch Workflow. Instead, it assigns very specific roles to different branches and defines how and when they should interact. In addition to feature branches, it uses individual branches for preparing, maintaining, and recording releases. Of course, you also get to leverage all the benefits of the Feature Branch Workflow: pull requests, isolated experiments, and more efficient collaboration.2

Develop and Master Branches3
Instead of a single master branch, this workflow uses two branches to record the history of the project. The master branch stores the official release history, and the develop branch serves as an integration branch for features. It's also convenient to tag all commits in the master branch with a version number.4

The overall flow of Gitflow

  • A develop branch is created from master
  • A release branch is created from develop
  • Feature branches are created from develop
  • When a feature is complete it is merged into the develop branch
  • When the release branch is done it is merged into develop and master
  • If an issue in master is detected a hotfix branch is created from master
  • Once the hotfix is complete it is merged to both develop and master

Feature Branches

Each new feature should reside in its own branch, which can be pushed to the central repository for backup/collaboration. But, instead of branching off of master, feature branches use develop as their parent branch. When a feature is complete, it gets merged back into develop. Features should never interact directly with master.5

The core idea behind the Feature Branch Workflow is that all feature development should take place in a dedicated branch instead of the master branch. This encapsulation makes it easy for multiple developers to work on a particular feature without disturbing the main codebase. It also means the master branch will never contain broken code, which is a huge advantage for continuous integration environments.6

Encapsulating feature development also makes it possible to leverage pull requests, which are a way to initiate discussions around a branch. They give other developers the opportunity to sign off on a feature before it gets integrated into the official project. Or, if you get stuck in the middle of a feature, you can open a pull request asking for suggestions from your colleagues. The point is, pull requests make it incredibly easy for your team to comment on each other’s work.7

$ git checkout develop 
$ git checkout -b feature_branch

Update, add, commit, and push changes

On this branch, edit, stage, and commit changes in the usual fashion, building up the feature with as many commits as necessary. Work on the feature and make commits like you would any time you use Git. When ready, push your commits, updating the feature branch on Bitbucket/GitHub/CodeCommit.8

Best Practices

  • Make clean, single-purpose commits (Atomic Commit)
  • Write meaningful commit messages (For Atlassian BitBucket and Jira use Smart Commits)
  • Commit early, commit often
  • Don’t alter published history
  • Don’t commit generated files

$ git status 
$ git add  
$ git commit -m'PROJ-123 #comment Write meaningful commit messages'

Push feature branch to remote

It’s a good idea to push the feature branch up to the central repository. This serves as a convenient backup, when collaborating with other developers, this would give them access to view commits to the new branch.9

$ git push -u origin feature_branch

Pull requests

Aside from isolating feature development, branches make it possible to discuss changes via pull requests. Once someone completes a feature, they don’t immediately merge it into develop. Instead, they push the feature branch to the central server and file a pull request asking to merge their additions into develop. This gives other developers an opportunity to review the changes before they become a part of the main codebase.10

Code review is a major benefit of pull requests, but they’re actually designed to be a generic way to talk about code. You can think of pull requests as a discussion dedicated to a particular branch. This means that they can also be used much earlier in the development process. For example, if a developer needs help with a particular feature, all they have to do is file a pull request. Interested parties will be notified automatically, and they’ll be able to see the question right next to the relevant commits.11


Rebasing is required if any new pull requests were merged after you had taken the feature branch. After rebasing, any conflicts that arise need to be resolved, and the code needs to be pushed back to the remote branch.12

Update your target branch from upstream

$ git checkout develop
$ git pull upstream develop 
$ git push origin develop

Rebase your branch

This will rewind all your commits on this branch and then replay them against the tip of the branch you are rebasing against.13

$ git checkout feature_branch
$ git rebase develop

Fix conflicts and continue rebasing

Once all conflicting files are fixed you can continue the rebase

$ git rebase --continue

Push your newly rebased branch to origin

$ git push -u origin feature_branch

Create a Pull Request

(Peer) Code Review

Code Review, or Peer Code Review, is the act of consciously and systematically convening with one’s fellow programmers to check each other’s code for mistakes, and has been repeatedly shown to accelerate and streamline the process of software development like few other practices can.14

Code reviews should look at:

  • Design: Is the code well-designed and appropriate for your system?
  • Functionality: Does the code behave as the author likely intended? Is the way the code behaves good for its users?
  • Complexity: Could the code be made simpler? Would another developer be able to easily understand and use this code when they come across it in the future?
  • Tests: Does the code have correct and well-designed automated tests?
  • Naming: Did the developer choose clear names for variables, classes, methods, etc.?
  • Comments: Are the comments clear and useful?
  • Style: Does the code follow our style guides?
  • Documentation: Did the developer also update relevant documentation?

Finishing a feature branch (passed code review)

When you’re done with the development work on the feature, the next step is to merge the feature_branch into develop.

$ git checkout develop 
$ git merge feature_branch
$ git push origin develop

Deployment to Staging/QA/UAT Environment

Deploy the develop branch to a staging/alpha site for QA/Testing/UAT. see Testing and Quality Assurance

Release Branches

Once develop has acquired enough features for a release (or a predetermined release date is approaching), you fork a release branch off of develop. Creating this branch starts the next release cycle, so no new features can be added after this point—only bug fixes, documentation generation, and other release-oriented tasks should go in this branch. Once it's ready to ship, the release branch gets merged into master and tagged with a version number. In addition, it should be merged back into develop, which may have progressed since the release was initiated.15

Using a dedicated branch to prepare releases makes it possible for one team to polish the current release while another team continues working on features for the next release. It also creates well-defined phases of development (e.g., it's easy to say, “This week we're preparing for version 4.0,” and to actually see it in the structure of the repository).16

Making release branches is another straightforward branching operation. Like feature branches, release branches are based on the develop branch.17

Once the release is ready to ship, it will get merged it into master and develop, then the release branch will be deleted. It’s important to merge back into develop because critical updates may have been added to the release branch and they need to be accessible to new features..18

Bash script to automate the Gitflow tag/release process

Deployment to Production Environment

Deploy the master branch to the production site.

Last edited by MichaelAlber .
Page last modified on Monday November 23, 2020 21:22:21 PST.