Git-Branchy-Workflow

VXL Branchy Git Workflow

The branchy workflow is the preferred workflow flow for VXL. In the branchy workflow, each new and independent feature or bug fix is developed on a separate topic branch. These topic branches are created from the master branch and are merged back into the master branch when complete.

This workflow requires a reasonable level of comfort with using Git. If you are coming from Subversion and are not familiar with Git, we recommend the rebase workflow. Some of the commands below may leave your local repository in a state that is difficult for a Git novice to understand. While Git makes it difficult to permanently loose committed changes, a Git novice may loose track of commits and need a Git expert to help recover them. Proceed at your own risk.

This document is not a Git tutorial. It is intended to outline the branchy workflow that is acceptable for VXL development.

Update

Update your local master branch

$ git checkout master
$ git pull

Create a Topic

New work is committed on topic branches. Name topics like you might name functions: concise but precise. A reader should have a general idea of the feature or fix to be developed given just the branch name.

To start a new topic branch from master:

$ git checkout -b my-topic master

Edit files and create commits (repeat as needed):

$ edit file1 file2 file3
$ git add file1 file2 file3
$ git commit

Switch Topics

To see a list of your local topic branches:

$ git branch

To checkout a different branch:

$ git checkout my-other-topic

Share a Topic

The official VXL repository hosted by sourceforge is not intended for sharing topic branches. The server-side checks will prevent you from pushing branches other than master to the server. However, you can configure Git to push your branches to other clones of the VXL repository for sharing, collaboration, code review, etc.

We may establish a VXL clone on GitHub for the purpose of sharing topic branches and accepting topic branches from outside contributors who do not have write access to the official repository. The wiki will be updated if/when this happens.

Merge a Topic

After a topic is complete, merge it into the upstream repository.

First checkout master and update your local master branch. To merge in your topic branch:

$ git merge my-topic

If the merge is successful, publish the updated master:

$ git push

Merge Conflicts

Merging a topic branch may fail due to conflicts between the topic and changes in the upstream master branch. There are multiple ways to resolve a merge conflict. The easiest way to is to resolve conflicts reported during the merge and complete the merge.

$ edit conflict_file1 conflict_file2
$ git add conflict_file1 conflict_file2
$ git commit

An alternative approach is to abandon the conflicting merge, rebase the topic branch onto the new upstream master, resolve the conflicts during the rebase, and merge again. The advantage of the latter approach is that it makes the history easier to follow (no messy conflict resolution changes in the merge commit). To do this:

Abandon the conflicting merge by resetting master to the upstream master

$ git reset --hard origin/master

Rebase the topic branch onto the updated master and resolve conflicts as needed

$ git checkout my-topic
$ git rebase origin/master
$ edit conflict_file1 conflict_file2
$ git add conflict_file1 conflict_file2
$ git rebase --continue

Do the merge again.

$ git checkout master
$ git merge my-topic

Delete a Topic

After a topic has been merged upstream, delete your local branch for the topic.

First checkout master and update your local master branch. Then delete the local topic:

$ git branch -d my-topic

The branch -d command works only when the topic branch has been correctly merged. Use -D instead of -d to force the deletion of an unmerged topic branch (warning - you could lose commits).