Git Workflow Model

Git has become the de facto version control system used by software engineers. It's an incredibly powerful tool for project collaboration, but is often feared and misunderstood. Just in the past month, I have worked on three projects with small teams and on each team there was confusion about using git, particularly in a team environment.

I would like to present a git workflow model that I have distilled down to a concise and easily digestible process. Use this model to lay a solid foundation for effective software collaboration. This basic workflow can also be easily extended as teams grow and projects become more complex. I'll provide a few examples for extending the model at the end of this post.

For this example, I'll use GitHub as the remote repository as it's currently the market leader (Bitbucket is a good alternative). I'll also assume you're familiar with basic git.


Diagram

Here is a diagram I put together for visualizing the basic git workflow process we'll be building out:
Git Workflow Diagram


Getting Started

  1. Create a GitHub organization that will be used to house your project repository.
  2. Invite team members to the organization.
  3. Create your initial project repo. If you have a current repo, have no fear, GitHub makes it easy to port over to your organization. You won't lose any of your previous commit history either.
  4. Your repo will come with a master branch. Create a second branch titled 'dev'. I'll explain how these two branches work a little later.
  5. Have team members fork and clone a copy of the organization repo locally. For this model, let's name our forked remote 'origin' and our organizaitonal remote 'upstream'.

Contributing

  1. Each team member should cut a branch for the task they are working on. Using a naming convention for your branches will keep your pull requests organized. Each branch should be prefaced with a descriptive name. Here are some good examples:
    • feat/...
    • test/...
    • bug/...
    • refactor/...
    • cleanup/...
    • doc/...
  2. Here we'll create a form validation feature branch:
    git checkout -b feat/form-validation
  3. Make commits to your branch.
  4. When you've finished with your project task, sync the latest changes from the organization.*
    git pull upstream <branch_to_update_from>
  5. Check for and resolve any merge conflicts.
  6. Once you've synced the organization changes, push your commits to your forked repo at the namespaced branch:
    git push origin feat/form-validation

*Note: A rebase workflow can also be used where each of your commits is replayed on top of the pulled commits to form an easily readable git log. Rebase does rewrite history though. For a rebase workflow:
git pull --rebase upstream <branch_to_update_from>

Pull Requests

  1. Submit a pull request to upstream dev. Include a description of your changes.
  2. Your pull request will be reviewed by another team member. The point of code reviews is to help keep the codebase clean and of high quality.
  3. Fix any issues raised by your code reviwer, and push your fixes as a single new commit.
  4. Once the pull request has been reviewed, it will be merged by another member of the team. Your code is now part of the organization's code base and can be pulled down by your team.

Restart the Process

Delete your remote and local branches for the completed feature and cut a new one for your next task.

git push origin :feat/form-validation
git branch -D :feat/form-validation
git checkout -b feat/new-feature

Write more code, rinse and repeat!


Organization Branches

Let's talk about the two branches in our organization repo:

  • master: This is your production branch. It should always have a working copy of your code on it. Only push to this branch when you have thoroughly tested your development branch for bugs.

  • dev: This is your development branch. All team member pull requests should be sent to dev (never to master). Once dev is tested and in a production-ready state, issue a pull request from dev to master. Once the pull request is merged, master is up to date with the latest working version of your code.


Extending

This organization branching model can easily be scaled as your team and project grows. Here are some additional branches that are helpful for extending your organization repo:

  • BugFix Branch:
    • Cut from: master
    • Merges to: master
    • Pull changes to: dev
    • Purpose: The bug fix branch is used for squashing any production bugs that arise. Cut a branch from master, fix the bugs and merge back into master, so your production branch is bug free.
  • Feature Branch:
    • Cut from: dev
    • Merges to: dev
    • Purpose: A feature branch is useful when creating large features that multiple team members will be contributing to. Cut a branch from dev and start developing the feature. Once the feature is complete, merge into dev. Create as many feature branches as necessary.
  • Release Branch:
    • Cut from: dev
    • Merges to: master
    • Pull changes to: dev
    • Purpose: The release branch sits as an intermediary between dev and master. Once a release branch is cut, no more changes from dev can be added. The release branch performs all testing and quality control ensuring the code is production-grade before merging into master.