Triangle workflows

triangle-workflow.md

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. However those config settings only work on relatively recent versions of git; 1.7.9 doesn't support the required remote.pushdefault config setting so you will have to explicitly tell git push which remote to push to.

This gist does not attempt to explain exactly what these commands do, it's intended as a cheat-sheet/reminder.

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

The above commands are optional and won't work on older versions of git such as 1.7.9, they save having to type the names of the remote and branch when pushing changes to github.

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

These commands are quite simple because of the options used in the earlier steps. On older git versions you have to use git push github instead.

Merge or Rebase

There are two ways to import changes committed to the master branch before this branch gets merged. If there are no conflicts between the two sets of changes though it may not be necessary to do either.

• To merge changes from the upstream/master branch:

$ git pull

• To rebase this branch onto the latest upstream/master commit:

$ git pull --rebase

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 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>