Git Workflow

git-workflow.md

Git Feature Branch Workflow

Setting up and working on a feature branch

1. Make sure you're on the master branch and your git status is clean
2. Next make sure your local master branch is up to date with master branch at origin: git pull --rebase or gpr with the dotmatrix alias
3. Once you have confirmed you have a clean index and you are up to date, create a new feature branch. If you're working on a new feature for pagination for example, something like this would work git checkout -b pagination or with dotmatrix aliases gco -b pagination. Some people like to make GitHub issues for the work they're about to do and prefix the feature with a number matching the GitHub issue, like this gco -b 352-pagination
4. Do all of your work as normal in this branch and make commits freely. When you are ready to push the branch up you can do so like this: git push origin 352-pagination. Alternativley, you can use the dotmatrix alias git put. This will assume that whatever branch name you are on locally should be pushed up to a branch at that name at origin.

Merging a feature branch

1. When you're satisfied with your work and you've pushed it up to GitHub as a feature branch, you can create a pull request on GitHub as documented here: https://help.github.com/articles/creating-a-pull-request
2. Pull requests can be merged into the repository via GitHub as well like so: https://help.github.com/articles/merging-a-pull-request However, this will create a 'merge commit' that is a special kind of commit just to bring in the other commits from your feature branch. Many people don't like this and find it untidy. There's a better way to do this on the command line to avoid the merge commit.
3. We need to make sure that the feature branch will merge cleanly into the master branch, so first git checkout master or gco master and make sure we're up to date and clean again: git pull --rebase or gpr.
4. Now check out your feature branch: git checkout 352-pagination or gco 352-pagination
5. Next we want to rebase the master branch onto the feature branch. This will make it so there's nothing in master that isn't in your feature branch too, and you can then merge cleanly. Do the rebase like this: git rebase master
6. If you're working on a team there may be merge conflicts that you need to fix, which is outside the scope of these instructions
7. Now checkout the master branch again: gco master
8. And merge the feature: git merge 352-pagination
9. You're done! You've got a clean merge without the merge commit. Push this up to GitHub: git put or git push origin master

Cleaning up

1. We should delete our local feature branch: git branch -D 352-pagination or gb -D 352-pagination
2. We also want to delete the feature branch at origin if it's up there: git push origin :352-pagination (This is a funny syntax, note the colon)

A note about WIP commits

It's nice to name our commits what they do, like: 'Add hidden resources to nav for admins' or 'Paginate orders index'. However, sometimes we just aren't finished with our work yet. It can be nice to push up a 'WIP' or 'work in progress' commit to GitHub from time to time.

You should only do this on a feature branch!

1. Add your changes to the index and make the commit starting with 'WIP:' and name it after what you're doing, not what will be done. For example git ci -m "WIP: Adding users to index page"
2. Push it up to GitHub: git put
3. When you resume, you can undo the last commit and move its changes back into your index with this: git reset head^ or git doff
4. Now you can continue on your way!

A note about 'develop' branches

Some people have a develop branch that they use instead of master. You can treat develop just like master in the above instructions if this is the case.