Tuesday, April 23, 2013

Managing a project on Github.

A short post on managing code via Github. They probably have a thousand articles and this has been written a million times before, but I'll write it to remind my self, and  as a nifty reference for my group in "Company project"(I guess there will be some sort of post about that).

The post is a work in progress, so feel free to add tips & tricks, corrections and whatnot in the comments, or drop me an email or a message on G+.

The Project

The current project, and the one I'll refer in this post, is a LaTeX project for the report, that we are supposed to write. It contains 5 sections at the moment and a single appendix(there are more to come), its a total of 9 pages and growing.

The overhead of the below described process is probably growing over our heads before we know - but it makes things more manageable and adds structure to the process - which can probably help us.

The Meats

When developing with Github you have a bunch of useful features, what is mainly explored in this post is the pull-request(shortened to PR) feature.


The master branch is supposed to be a stable version of whatever you are doing, in our case it is supposed to be a compile-able report that we can ship off to our mentor at any point in time.

To achieve that goal, branches come in very handy. When you write something new, or change an existing part, a branch helps you keep your changes in one place. Thereby not polluting the master-branch with your unfinished or non compile-able work.

The part about keeping master clean, could very well be achieved with tags - this would require close coordination between team members about when what happens, when to make a tag, how many commits and so on. With the branches approach, you can keep your changes isolated and do not have to worry about what the rest of the world is doing to the code base.

In conclusion branches helps you keep sets of changes isolated from the rest of your project, without the coordination efforts required when working in the same branch.

Commands: create a new branch git branch <branch-name>, switch to a branch: git checkout <branch-name>


When you've create a set of changes, and you are ready for the world to know that you have something, you create a PR. Actually, if you go to the Github project page right after pushing your latest changes, there should be a button allowing you to create a pull request.

Put in a short name and a description of what has been done, and the world is ready to check it out. This process doesn't seem more fit than sending an email to the team, telling them that the branch is now ready for review/merging.

But of course its smarter, why else would I write a post about it. Your changes are nicely lined up, in a separate tab of the PR's view in Github, that's a first. Secondly, when you hover your mouse over a changed line, a little speech balloon pops up to the left of the change, if you click this you can comment on that specific change. This allows the team to review your changes, and possibly rule out spelling mistakes, faulty environments, forgetfulness and the likes.

And when the team says go, you can press the green merge button and your changes are merged into master(if you choose master as your target). Also the green button won't appear if your changes are in conflict with other changes in the project(More about this later).

In conclusion pull requests are a nice way of making sure that the team knows what is changed, and that every part of your project is keeping up to some agreed upon standard.

Commands: Only Github UI action relevant.


For me this is a very natural way of working with a project, that being a report in LaTeX or a codebase of several thousand lines. Keeping track of changes, makes the team aware of whats going on, thereby not leaving anyone behind and unknowing of the projects current status.

The Nifties

When you experience a yellow button, and your pull request cannot be merged, it is often caused by other PR's being merged into master, and therefore conflicting with yours. This can be solved by rebasing your changes on top of master(For a reference, see http://git-scm.com/book/en/Git-Branching-Rebasing).

    git checkout <your-branch>;
    git rebase master

Thats all for now, if you have anymore nifty tricks please add them in the comments.

No comments:

Choose a month: