« Back to Index

Git Workflow

View original Gist on GitHub

Git Workflow.md

Git Workflow

When using Git Version Control you have quite a few workflow variations. Which one you choose depends on your team and what fits your requirements and usage more appropriately.

Here are some popular options that will be described later in this document:

Expectations

All of these workflows assume that you have a remote repository and by default the main branch is called master.

Also, we don’t cover every possible detail about git and how it works/what certain concepts mean; as we assume a certain level of past experience from the reader. By this I mean, for example, if you don’t know what a ‘merge conflict’ is you’ll need to read up on git a bit more first in order to benefit from this document.

What’s not covered?

One model I’ve not covered is the “Git ‘Forked Repo’ Workflow”, which is based around the concept of developers not having push access to a repository but are able to fork the repo (i.e. make a clone of it). Pull Requests can then be made to the upstream repository that was forked from.

The reason for not covering this particular workflow is that within the BBC the majority of repositories are private by nature (except for those specifically made to be open-source) and so all developers working on a specific project will be given push access to the relevant private repo.

Note: although the BBC does not encourage forking of its own private repositories, it does recognise and accept that the forking model is the fundamental and primary concept behind the open-source movement

Code Reviews

Although not directly related to git workflows, it’s important to remember that the GitHub model of reviewing code revolves around the idea of a Pull Request, but this is merely a clever abstraction on top of gits own git request-pull model which is built around the simple concept that a feature should be encapsulated within a single commit.

The command git request-pull is described in the git manual as follows:

Summarizes the changes between two commits to the standard output, and includes the given URL in the generated summary.

This facilitates the ability to post the diff/summary of changes into a mailing list for easy comparison and reasoning before consideration to merging into master.

The only requirement for using the built-in git request-pull is that you need to provide a URL for where the commit you’re proposing to be reviewed/merged can be pulled from by the owner of the origin repo.

So in other words, you’ll need to have a fork of the origin repo in another git repo that’s accessible to the developers you’re asking to review your commit. This isn’t a problem for most organisations, although it’s a little trickier for the BBC as it doesn’t encourage forks of its private repositories. Just something to be aware of.

Git ‘Centralised’ Workflow

Summary: everyone works from the master branch

Pros

Cons

Git ‘Feature Branches’ Workflow

Summary: everyone works from their own ‘feature’ branch

Notes

To reduce the likeliness of a merge conflict, developers should consider updating their master branch regularly and merging those changes into their feature branch (e.g. git merge master).

Developers can also consider pulling master directly into their feature branch either by using git pull origin master or by using git pull --rebase origin master (which will unshift their feature branch commits so that they sit ontop of whatever is inside master; meaning the feature branch commits are ‘top of the stack’).

Also, when using --rebase you do typically experience less conflicts.

Pros

Cons

† this is dependant on your team and your specific workflow
and the details a merge commit provides

Git ‘Gitflow’ Workflow

Gitflow is an evolution of the ‘feature branch’ model that adds additional layers to the workflow.

With Gitflow you have additional branches that interact with each other in different ways:

Gitflow

Pros

Cons

Git ‘Single Commit/No Branches’ Workflow

Summary: everyone works from master, but ‘rebase’ commits before push

Notes

The reason you would choose this model is if you were using a traditional git request-pull for code reviews, and also it helps to keep your commit history clean and organised.

This approach ideally benefits small changes and short-lived PRs.

Pros

Cons

Git ‘Rebase Feature Branch Commits’ Workflow

Summary: work from a ‘feature’ branch, but ‘rebase’ commits before merge

Notes

GitHub specifically offers a feature where by GitHub issues are automatically closed whenever a push to master includes the phrase Fixes #n (where n is the issue number); similarly it’ll automatically close a pull request when the commit message in master includes the phrase Closes #n (where n is the pull request number).

Also, the GitHub user interface now (as of 2016) suppports the ability to squash commits when merging. This might be a preferable option to the above steps.

Pros

† this is dependant on your team and your specific workflow
and the details a merge commit provides

Cons

Note: if branches are deleted from GitHub then eventually the commits will be garbage collected and history lost there as well. So pick this option according to whether it fits your team’s long term needs

References