Triangle Workflows

A triangle workflow involves an upstream project and a personal fork containing a development branch of the project. This configuration makes git pull merge changes from the upstream but git push send local commits to the personal fork.

To set up a project area

• Fork the project on https://github.com/<project>

If you already cloned the upstream repository

• Rename 'origin' to 'upstream' and add a new remote 'github':

$ cd <project>
$ git remote rename origin upstream
$ git remote add github git@github.com:<user>/<project>.git

Else this is a new project area

• Clone the newly forked branch:

$ git clone -o github git@github.com:<user>/<project>.git

• Add a remote 'upstream' to point to the official repository:

$ cd project
$ git remote add upstream git@github.com:<organization>/<project>.git
$ git fetch upstream

In both cases

• Set the default push remote to be the new fork:

$ git config remote.pushdefault github
$ git config push.default current

To start a new development

• Create and checkout a local branch where the work will be done, based off the upstream/master branch:

$ cd <project>
$ git checkout -b <development> upstream/master

• Develop on this branch, committing freely to the local repository.

$ git add <files>
$ git commit -m '<message>'

• Push commits to the remote github/<development> branch using:

$ git push

• Merge changes from the upstream/master branch:

$ git pull

• To rebase this branch instead of merging:

$ git pull --rebase

These are all quite simple because of the options used in the earlier steps.

Parallel work on the master branch

It is relatively easy to commit changes to the upstream/master branch while you're still developing in your private development branch. To switch your working directory to the master, use

$ git stash save <message>  # Optional, saves uncommitted changes
$ git checkout master
$ git pull

Now you can make any changes needed. To commit them and push them to the upstream repository

$ git add <files>
$ git commit -m '<message>'
$ git push upstream

To get back to where you were on your development branch again

$ git checkout <development>
$ git stash pop  # Optional, restores saved uncommitted changes

To close a development

• When you're ready for review, issue a pull request for this branch through github.

• After the branch has been merged, delete it using

$ git checkout master
$ git pull
$ git branch -d <development>