GitAndGitFlow

Git and Git Flow

Introduction

For AlCap we are going to follow the git flow branching model. A couple of useful links to read are the git tutorial here, an explanation of git flow here and a cheat sheet here but this page will outline the main steps and also a couple of important additions we've learned.

First Steps

Once you have initially cloned the AlcapDAQ repository, git flow needs to be set up separately.

First, check that you have git flow installed on your machine:
> which git-flow
If nothing appears, then you need to install it. (For Ubuntu, I think it was a simple sudo apt-get command but you should look it up)

If you do have git flow installed, do the following:

> cd AlcapDAQ  
> git flow init -d  

(The -d option tells git flow to use the default prefixes for the different branch types).

Feature Branches

Starting a Feature Branch
When you want to add a new feature, type the following commands:
> git flow feature start [feature_name]
where feature_name is a descriptive name for your feature.

This will automatically create a branch of develop and move you over to the new branch. To check you can type the command git branch which will list all the branches you have locally, with the branch you are currently on denoted by an asterisk.

(Some other useful options to git branch are -a to print both local and remote branches and -v, -vv or -vvv to get a more verbose output with things like the last commit message on each branch and which remote branch each local branch is tracking)

Publishing a Feature Branch
One of the first things you should do once you create a new feature branch is to "publish" it. This just means that the branch will be pushed to GitHub for everyone to see what's being worked on.

To do this type the command:
> git flow feature publish [feature_name]

Working on a Feature Branch
There is no difference with working on a feature branch as with any other type of branch, so your usual git work routine should be the same, which, ideally, would be something like this:

• Check the status of your local area: git status
• You can check differences of files with: git diff [file]
• Commit changes: git commit -m "<useful message>"
• Push commits to GitHub: git push

In general, it's a good idea to commit often, even small changes, and then when enough commits have been made you should push.

Finishing a Feature Branch
Once your feature is ready to be merged back into develop (do we need to have a process of asking John first?). We first need to check that there have been no changes to develop since we created our feature branch:
> git pull
if everything is up to date then we can skip to finishing the next couple of paragraphs (up to git flow feature finish).

First, pull the changes into the develop branch directly:

> git checkout develop
> git pull

and now we can go back and update our feature branch

> git checkout [feature_name]
> git flow feature rebase

this will just shift your branch's history to the HEAD of develop in case someone else has merged another feature branch in since you created yours. (More information and an example here)
We now need to pull again on the feature branch (I'm not sure why. Can someone explain?)
git pull

Now that we have the latest version of the develop branch and our feature branch is up to date, we can finish:

> git flow feature finish -F [feature_name]  
> git push

(the -F option just makes sure that the feature branch gets deleted on GitHub as well as in your local area).

I think (feel free to disagree with me) that the default merge commit for feature branches should be kept at the start of the commit message. This allows us to easily see which branches in the network belong to which feature.

Conclusion

That's everything I can think of for the time being. If you have any questions then you can open an issue on the repository and between us we can somehow reach an answer.

Useful Tips

Super duper git log

Here's a macro I got from a colleague a while ago that I find really useful. Add this to your .bash_profile:

git config --global alias.lg "log --color --graph 
--pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr)%C(bold 
blue)<%an>%Creset' --abbrev-commit"

then the command git lg gives you a beautiful commit history to look at.

Moving commits from one branch to another

I (ben) just hit this problem and thought I'd document it here for future reference. This was the situation:

• I did git flow feature start My_new_feature
• Panicked my develop branch was not up-to-date.
• Changed to develop and pulled: git checkout develop; git pull

At this point I meant to change back to my feature, but forgot. So off I went committing, and only after 5 big commits did I realise I wasn't where I expected to be.

So. Solution:

• git checkout feature/My_new_feature to change to the feature
• git flow feature rebaseto transfer develop's commits to the feature branch
• git checkout develop to change back to develop
• git reset --hard HEAD~5 which permanently removed the last 5 commits on develop (see stack overflow).

Then I was able to checkout my feature again and continue as if nothing happened. I would have gotten away with my foolishness if it wasn't for this wiki...

Using git cherry-pick

Also, it seems like git cherry-pick can do similar things, but more powerfully:

• http://www.git-scm.com/docs/git-cherry-pick/1.7.3.3
• http://www.williambharding.com/blog/git/git-move-commit-to-another-branch/

Steps:

1. Use git log to select the commit hash to copy over
2. Change to the branch you want to work on (git checkout SOME-BRANCH-NAME).
3. Use git cherry-pick COMMIT-HASH to bring over the commit from the other branch
4. Repeat step 3 until all commits are brought over.
5. Undo the commits from the first (incorrect) branch, with git reset as above.