A Simple Git Workflow

This is an outline of a simple git workflow that I feel works well for projects with multiple collaborators. This article covers a branching model, as well as a few suggestions regarding pull requests and commit messages.

Branching

Branching is a powerful feature of git. Since creating and merging branches is so cheap and easy, there is no reason not to use them. I propose having two branches that always exist: master and development. These branches are complemented with feature branches that deal with the implementation of specific features and may be deleted when completed and merged.

The master branch is the default branch created when a new git repository is initialized. This is generally the branch that a new user first encounters when looking at a project. I like to keep this branch stable and fully functional 100% of the time. That is not most of the time, it is all of the time. If something accidentally gets merged into master that is broken in some way, the merge should be immediately reverted. The master branch should be a point of safety and sanity for all developers, where one can always view and run the code and expect it to work correctly. The only branch that should be merged into the master is the development branch, and only when the development branch is stable and the person merging knows what they are doing.

The development branch is where features are branched and merged. Feature branches should only be merged after they have been tested and are found to work. Ideally, the development branch should be stable almost all of the time. When bugs do work their way into the development branch, it should be a fairly high priority to get them sorted out. Periodically, when the development branch has been fully tested and debugged and is seen to be working correctly, it can be merged into the master branch.

Finally, feature branches are branched and merged off of the development branch. These are used to implement new features or experiment with the code. Once the feature is completed and tested thoroughly, it can be merged back into the development branch. As noted above, the development branch is meant to be mostly stable, so ensuring that things work before merging a feature branch is quite important.

Pull requests

I think that code reviews are useful for ensuring that code being merged looks correct and adheres to accepted style guidelines. A simple way to start a code review is to submit a pull request (PR) when one wants to merge. The PR should provide a robust description of the contents of the branch being merged and any other relevant information. Upon submitting the PR, notify someone who is qualified to review the code and ask them to do so. After reviewing they should either indicate that the PR is good and can be merged, or suggest changes that should be made.

Commit messages

Commit messages should tell the reader what the commit has accomplished without them having to dig through the changes. For a non-trivial change, write at least a sentence to describe it (but avoid being verbose).

I prefer to write my commit message in the simple present tense. For example, use "Add function to..." rather than "Added function to..." or "Adding function to...".

Final words

This outline is quite simple and not at all exhaustive. It is meant as a few general guidelines rather than some sort of comprehensive guide for working with git. This post may continue to be updated as my git workflow evolves.