During my work, I sometimes get in touch with new technology. This usually involves long time searching for tutorials and best practices. More annoying, I keep on searching my browser history to recover some pieces of information from a tutorial I read a few days before. In this article I gather all the information I regularly need to work with git and github. It might be useful for others, but it is primarily targeted on myself.
Well, I actually do write source code. I feel like doing research in software engineering really benefits from coding. In most of my research projects I write some code that allows me to handle data in software projects in a different and new way. Most often, it seems like I could have reached my goal much easier by using some scripts and existing tools (e.g. R, NetMiner). But during my research, I feel kind of limited by everything weaker than a general purpose programming language. It is very probable that this limitation is only existing in my mind. However, research is partly a creative process and being creative is a state of mind. I find expressing my thoughts in Java very inspiring.
That being said, I am of course also concerned with managing my source code. GitHub is great for this, because it allows to share the mechanisms that I used to do my research. In a perfect world, others would use my code to verify my results and extend them by new data points or related studies. In reality, my research prototypes include too many quick hacks to be really useful to others. Nevertheless, I try.
In doing so, I need to define my own workflows. They should be simple (because most often, I am working alone), standard conform (because sometimes I want others to help me and I do not want to burden them with learning new things), and easy to remember. I found a beautiful post describing a workflow around github that perfectly makes sense to me: If the guys at GitHub can do with this workflow, it should be great for me…
The only issue: As a git newbie I always need to lookup the commands to do. So… here they are (correct, this is a selfish post as a reminder to myself. But please feel free to use it for your own purposes or to suggest improvements 🙂 I gathered these commands from the diaspora workflow page, /tmp/labs git cheat sheet, and Geoff’s blog post on the matter, especially in Oliver’s update in the comments.
On a new machine
Sometimes I want to start fresh from the repository – either on a new machine or in a different workspace. Here is how you do it:
git clone firstname.lastname@example.org:<you>/<project>.git cd <project>
Now, we are ready to start.
Working on a new feature
When starting to develop a new feature, it is time to create a branch. This is great, especially for me: I can start developing something new, sometimes many things in parallel. Meanwhile, the main branch remains functional. If I feel like I found a dead end, I can simply delete the branch. Of course, having worked with CVS and SVN, I am a little bit afraid that merging branches might be a problem. But I have been told that git can deal with this.
git checkout -b <new_feature>
This creates a local branch. <new_feature> should be a descriptive name. I think it is good practice to have the feature name start with the issue number. Now we have a local branch. This is not enough, because we want to store our changes on the server.
git push origin <new_feature>
Now the server knows the branch. If we do a git push, it will go to the branch. At the moment, I get an error message here: Apparently, the push to the branch works, but git also tries to push to master. And that fails:
! [rejected] master -> master (non-fast-forward)
Easy to ignore, because that is what I want. Still, we also want to receive pulls from our branch.
git branch --set-upstream <new_feature> origin/<new_feature>
This does the trick and we are set to work.
Working in the branch
No surprises here. Do the changes and then:
git commit -a git push
This loads the changes to the branch on github.
Synchronization with master branch
Case 1: Getting changes from master in your branch
It is not unusual that the master branch changes, even if you are the only developer, e.g. you might do a bug fix. Here is what you need to do to get those changes into your branch:
git pull git merge origin/master
Do not forget to pull first! Otherwise, git will not find anything to merge. After the merge, you have a number of commits that you can push to your branch on the server to bring it up to date.
Case 2: Finishing your work and pushing your changes into the master branch
At some point the new feature is developed and tested and should be included into the main branch. Push all your changes into your branch on the server.
git commit -a git push
Then, switch to the master branch.
git checkout master
Now, do a merge:
git merge <new_feature> git push
Understanding the state of things
Well, you sure want to look on your github page regularly. But of course there are also some commands that come in handy.
git status git branch -r
If you want to delete your branch online, you can do the following (I did not test this):
git push origin :<new_feature>
I did not use some of the commands that I encountered. The only one that comes to my mind now is
git rebase master
Apparently, some people prefer this above git merge. I will write more on the matter once I have my own opinion about this. The above seems to work for me.