Empiria Ltd's Git Workflow

gistfile1.md

Git Workflow used by Empiria Ltd

This is the workflow we use on projects for our customers. We know it won't suit everyone as it depends upon our particular circumstances, but if it's useful to anyone else, please drop us a comment.

Context

• We are a small company and our projects tend to have small teams of trusted developers.
• Our customers rarely have experience of development work and are unfamiliar with tools like git or issue trackers.
• We want to provide our customers with access to code that we have written for them and a system for them to record issues that they find.
• We do not want to expose our 'work in progress' to our customers either during the course of development or even when the work is complete.

Overview

• We use github as the customer interface. Our customers' staff register accounts and join our github teams where they can see the code we produce and use the issue tracking and wiki functionality.
• The github repository for a given project only contains a 'master' branch and we only ever commit working, tested code to that branch.
• We run an internal git server to allow developers to collaborate on work in progress.
• We configure two remotes on each developer's repository. They are always named 'github' and 'empiria' and point to the github and internal server repositories.

Typical Scenarios

Sole Developer

A developer starts work on a change and creates a new branch in her local repository.

We call this a 'Personal Branch.' There's nothing special about it - no security that it makes it especially 'personal' - it's just the term we have agreed upon to describe this type of branch.

She commits to this personal branch as she progresses. She also rebases it regularly from the master branch to take account of any changes that may have been released.

Once the work is tested and complete, it is merged into the master branch which is then pushed to github.

We use the --squash option so that only one commit is added to master for that entire change, regardless of the number of commits on the personal branch.

Once github is up to date, she deletes the personal branch.

Collaborative Development

A developer realises that he is going to need some help from a colleague on a particular piece of work. He pushes his personal branch to our internal git server and his colleague pulls the work from there.

We call the branches on our internal server 'Collaborative Branches.' Again, there is nothing special about them as far as git is concerned. It's just the term we've chosen to describe that type of branch.

We now refer to his local branch as a 'Tracking Personal Branch' (and the same term applies to his colleague's local branch).

The two developers commit to their tracking personal branches and push and pull their work to and from the collaborative branch. They have to rebase their work regularly from the master branch and have to be careful to agree who is responsible for rebasing.

When the work is tested and complete, it is merged into the master branch, pushed to github (in exactly the same manner as for a personal branch) and the tracking personal and collaborative branches are deleted.

gistfile2.md

Git Commands - Sole Developer

In the code examples below, we use angled brackets to denote parameters that should be replaced with actual values.

e.g. The example code to create a new branch contains the command:

git checkout -b <branch name>

In reality, to create a branch named 'myNewBranch' the following command would be used:

git checkout -b myNewBranch

Create a Personal Branch

git checkout master
git pull
git checkout -b <branch name>

Update a Personal Branch with Changes from the Master Branch

git checkout <branch name>
git pull github master
git rebase master

Delete a Personal Branch

e.g. Abandoning a piece of work

git checkout master
git branch -D <branch name>

Merge a Personal Branch into the Master Branch

i.e. Publishing a completed piece of work to the customer

# Update the personal branch with changes from master
git checkout <branch name>
git pull github master
git rebase master

# Merge the personal branch into master and create a single commit
git checkout master
git merge --squash <branch name>
git commit -m "<commit message>"

# Push the master branch to the Github and Empiria repositories
git push
git push empiria master

# Delete the Personal Branch
git branch -D <branch name>

gistfile3.md

Git Commands - Collaborative Development

In the code examples below, we use angled brackets to denote parameters that should be replaced with actual values.

e.g. The example code to create a new collaborative branch contains the command:

git push -u empiria <branch name>

In reality, to create a branch named 'ourNewBranch' the following command would be used:

git push -u empiria ourNewBranch

Create a Collaborative Branch from an Existing Personal Branch

git checkout <branch name>
git push -u empiria <branch name>

Create a Tracking Personal Branch from an Existing Collaborative Branch

(If you don't know the name of the Collaborative Branch, don't worry: the 'fetch' command will show it).

git fetch empiria
git checkout --track empiria/<branch name>

Bring a Personal Branch up to date with Changes from the Empiria Repository

git checkout <branch name>
git pull

Push Changes from the Personal Branch to the Empiria Repository

git checkout <branch name>
git push

Delete a Collaborative Branch

git checkout master
git push empiria :<branch name>
git branch -D <branch name>

Update a Tracking Personal Branch with Changes from Master

e.g. Returning to a parked piece of collaborative work after a different change has been pushed to github

git checkout <branch name>
git pull
git push
git pull github master
git rebase master
git push

Merge a Tracking Personal Branch into Master

i.e. Publishing a completed piece of work to the customer

# Update the personal branch with changes from the collaborative  and master branches
git pull github master
git checkout <branch name>
git pull
git rebase master

# Merge the personal branch into master and create a single commit
git checkout master
git merge --squash <branch name>
git commit -m "<commit message>"

# Push the master branch to the Github and Empiria repositories
git push
git push empiria master

# Delete the collaborative and tracking personal branches
git push empiria :<branch name>
git branch -D <branch name>

gistfile4.md

Git Commands - The Basics

These are some basic git commands which we use frequently. They're here as a reminder and to allow us to bring new developers up to speed.

Where am I and What's Going On?

git status

Show all Local and Remote Branches

git branch -a

Show Tracking Details for Local Branches

git remote show empiria

Stage and Commit all Changes

git commit -a -m "<commit message>"

Commit

git commit -m "<commit message>"

Bring Local Repository up to Date with Changes from Remotes

git fetch --all
git remote prune empiria

Re-Write History!! (Be careful with this)

Not to be used on the master branch.

# e.g. for the last 10 commits
git rebase -i HEAD~10