Git workflow for a small team

We will essentially use this workflow: http://nvie.com/posts/a-successful-git-branching-model/ and the diagrams there explain the relationship between branches. This document will list the commands needed to perform common tasks and explain what's happening. This is a work in progress so if you have any suggestions, you can submit them through a pull request on GitHub.

General guidelines

• All work should be done on a branch created for the feature or bug that you are working on. Never be tempted to work directly on the develop or master branches.
• The master branch should only ever contain well-tested code from the develop branch. The lead developer on a project is responsible for this and no-one else should push to it.
• Follow this guide carefully and collaboration will be safe and easy.

Connect to a remote Git repo

Before you can share your work with others, you need to to connect your local working directory to the remote repository.

If the repo has already been set up on a service such as GitHub:

1. Go to the repo's web page and copy its clone URL.
2. Open a terminal window and navigate to the directory that you want to contain the repo's directory.
3. git clone clone-url - Download the repo.

If you have started a project locally and want to add Git support to it:

1. Create an empty repo on GitHub and copy its clone URL. We will use this as a remote repo where we can share the project with others.
2. Open a terminal window and navigate to the root directory of your project.
3. git init - Set up Git in this directory.
4. git remote add origin clone-url - Tell Git where to find the remote repo.
5. git add -A - Stage all files to be saved.
6. git commit -m "Initial commit" - Save your initial version locally with a message.
7. git push -u origin master - Upload your repo to the server.

Day-to-day workflow

In this example, we are beginning work on a contact form for a website.

1. Prepare to work on a new feature

   1. git checkout develop - Switch to the branch that you want to base your work on, usually develop.
   2. git pull - Make sure you have the latest version.
   3. git checkout -b contact-form - Create a branch for the new feature and switch to it.

2. Develop the feature

   1. Work on the files in the project directory until you want to save your progress.
   2. git status - Check you are still on the correct branch and see a summary of the changes you have made.
   3. git add -A - Stage all files to be saved.
   4. git commit -m "Added email contact form" - Save all of your work as a new version with a description of the changes.
   5. Repeat until the feature is complete and fully tested.

3. Add your feature to the main development branch

   1. git checkout develop - Switch back to the parent branch.
   2. git pull --no-ff contact-form - Fetch the latest version of the develop branch and combine it with your feature branch. The --no-ff option preserves the history of the feature branch and keeps the shared branch clean.
   3. Resolve any conflicts between the branches and follow the prompts to complete the merge. Check that your feature is still working and does not conflict with anyone else's work.
   4. git branch -d contact-form - Delete the feature branch once it is no longer needed.
   5. git push origin develop - Upload your updated branch for others to access.

Other useful commands

git status - Check which branch you are working on and see a summary of changes. Always do this before starting work or committing changes to avoid working on the wrong branch.

git log --graph --oneline --decorate --all - Show a colourful graph that shows how branches and commits are related.

Stash changes

If you do begin to work on the wrong branch:

• git stash - Remove your changes but store them in memory.
• git checkout branch-name - Switch to the correct branch.
• git stash pop - Reapply your work there.
• Continue working or commit your work to the correct branch.

Cache your GitHub credentials

Accessing GitHub with HTTPS is much easier to set up than SSH, plus it also works through strict firewalls and proxies when SSH may fail. However, it gets annoying to type your username and password all the time. You can tell Git to remember your credentials for an hour by entering the following.

git config --global credential.helper cache
git config --global credential.helper 'cache --timeout=3600'

Undo a commit

This will create a new commit that undoes all the changes from a previous commit. This is safe and doesn't actually delete anything from the project's history.

1. git log - Find the commit that you want to revert to and copy its hash.
2. git revert hash - Undo the selected commit.
3. If you have more than one commit, you may have to resolve any conflicts.