Photo from Chile

A Git Workflow for Open Source Collaboration - Part IV - Submitting Contributions

In this installment in my series describing a Git workflow for open source collaboration we'll look at the final step in the workflow, submitting your contribution to the project owner(s).

Create a GitHub Pull Request

Your develop branch in your fork now contains the code you want to contribute, so you now need to send a pull request to the project owner(s) asking them to accept your contribution. Go to the main page for your GitHub repo (the fork that you created and to which you just pushed), and click the pull request button, which looks like this:


A Git Workflow for Open Source Collaboration - Part III - Developing Code

In this installment in my series describing a Git workflow for open source collaboration we'll look at the workflow for developing code to be contributed back to the project (e.g., bug fixes, new features, etc.).

Add a Feature

After reading parts I and II your local repo is all set up and ready to go. Let's say you want to add a feature to the project. The first step is to create a topic branch for your changes. A topic branch is not a special type of branch from a technical perspective, it's just a regular Git branch, but I'm going to use that term to refer to a branch that you create for one specific purpose. It might be to fix a bug or to add a feature. This brings us to our first rule:

Rule #1 - All Changes Should Be Made in a Topic Branch

That's right. Never make changes directly in the develop branch, and never, ever, touch the master branch. If you want to add a feature you need to create a new topic branch for your feature. Let's call it newFeature and create it by issuing the command from within the develop branch:

view plain print about
1git checkout -b newFeature

You'll recall from the previous post that the -b option tells Git to create a new branch. Make some code changes and commit often. Don't worry about creating too many commits as you're going to squash them down before merging them back into the develop branch. One thing you want to keep on top of, though, is keeping your code up to date with the code in the main repo. If changes happen to code in the main repo you want to get those changes into your topic branch as soon as possible, to minimize the chances of merge conflicts later. This brings us to the second rule:


A Git Workflow for Open Source Collaboration - Part II - Getting Started

In this installment in my series describing a Git workflow for open source collaboration we'll look at the steps to get your local development environment ready to participate in the workflow.

Get Git and a GitHub Account

In order to make use of this workflow as described you'll need to have Git installed on your machine, you'll need a GitHub account, and you'll need to configure your machine to talk to GitHub. I wrote a blog post covering those topics, for folks on OS X, awhile back. If you are on another OS there are plenty of resources available.

Create a Fork

This post assumes that you're starting from scratch, so the first thing you'll need to do is create a fork of the main project repo on GitHub.

For the purposes of this post I'll be using the repo for ValidateThis, so go to the main GitHub repo for ValidateThis, which is located at Click the fork button which you'll see near the upper right-hand corner of the screen:

You'll see a message similar to this, telling you that GitHub is creating a fork of the repo for you:

Once the fork has been created you'll be taken to the repo page for your fork of the ValidateThis repo.


The Git User's Survey is On

I found this out via a tweet from Mike Henke and then also saw it mentioned on the GitHub blog. Every year Git runs a survey of Git users to get feedback and help drive the future development of Git.

You can answer as many or as few questions as you like, and you can even return to the survey later and update your answers. The survey will be active until October 15th, and the results of the survey will be made public via the Git wiki after that. The survey can be found at, why not complete it today?

A Git Workflow for Open Source Collaboration - Part I - Introduction

As some of you may know, I'm the lead developer on an open source project called ValidateThis. I changed the version control software that I'm using for the project from Subversion to Git almost a year ago, and I've been very happy with Git ever since. There was a bit of a learning curve to Git, particularly as I'd never really used the command line much, and it's pretty much required with Git, but that was actually one of the reasons for the switch - to give me the impetus to really learn how to work with Git.

I am lucky enough to have several contributors to the project, and they made me aware recently that the fact that the source is housed in a Git repository is interfering with their ability to make contributions. They all have plenty of experience working with Subversion, but Git is quite new to most of them. Simply learning the syntax of Git is no problem, but what many people find difficult, me included, is figuring out how to change their workflow, as working with Git can be quite different from working with Subversion. So I decided to do some research and come up with a proposal for a workflow for all of the contributors. We're going to give it a try and see how well it goes. If changes need to be made, we'll make them. My hope is that the workflow we devise is one that can be used by other open source projects as well, if they choose to do so.

I am going to describe this workflow in detail through a series of posts on my blog, this post being the first installment. The series will likely contain the following posts:

  • Introduction
  • Setting Up Your Local Environment
  • Developing Code
  • Submitting Code to the Project


Using Git Rebase to Squash Commits - Revisited

I wrote a blog post awhile back about using Git rebase to squash a bunch of small commits into a single commit. I really like this approach as it allows me to commit frequently without having to litter my public repo with lots of meaningless commits. I've recently been researching Git workflows, trying to come up with a workflow for contributors to ValidateThis, and noticed that there's an easier way to start a rebase for all commits in a branch, which is generally what I need to rebase.

When I start working on a new feature, or even a bug fix, I generally start a new branch for it:

view plain print about
1git checkout -b newBranch

I then make my changes, committing frequently. When I'm ready to merge my changes back into the master branch I don't want all of those small, meaningless commits showing up, so I use get rebase to squash them. In the pervious article I discussed how I'd use git log to determine how many commits I wanted to rebase and then use git rebase -i HEAD~n, where n is the number of commits that I want to rebase. This is a useful feature if your commits are already in your master branch, but if all you want to do is rebase all of the commits in the current branch (newBranch in this example), then you can simply do:

view plain print about
1git rebase -i master

Which tells Git to rebase all of the commits in the current branch that are not already in master. After issuing that command you can follow the steps as described in the previous article to choose which ones to squash and then to create a new commit message.

Comparing Files from Different Branches with Git Difftool

As a relative newcomer to Git one of the things I've struggled most with is how to compare files from different branches. The challenge comes from the fact that, from the perspective of the file system, two branches cannot exist at the same time. When you switch from one branch to another the new branch replaces the old branch, so you cannot use a native file compare tool to compare two sets of files, as there really is only one set of files at any point in time. Now I admit that I might be totally wrong about this, and I'm sure that there are other, perhaps better, solutions to the issue, but the one that works for me currently is git difftool.

What is Git Difftool?

According to the man page for git-difftool,

git difftool is a git command that allows you to compare and edit files between revisions using common diff tools. git difftool is a frontend to git diff and accepts the same options and arguments.

I've tried using git diff in the past and, after spending years working with a wonderful tool like Subclipse's Synchronize with Repository, I just did not enjoy the output of git diff at all. Luckily, git difftool works with a file compare tool on your system, making the output much easier (for me at least) to deal with. On my system, which is OS X, because I have the Apple Developer Tools installed, when I issue the git difftool the output is sent to opendiff, which in turn uses FileMerge which is a nice, graphical file compare and merge tool. Other than installing the developer tools, which I did long before I started using Git, I didn't have to do any other setup. I honestly have no idea how easy it is to set up a graphical compare tool to work with git difftool on a Windows or Linux box, but I'm guessing it cannot be that difficult.

Using Git Difftool

To start a compare, you simply issue the git difftool command and pass it paths to two sets of files. The paths look like branchName:path. So if I wanted to compare the file ValidationFactory.cfc from the master branch to the same file in the newStuff branch, I'd type:

view plain print about
1git difftool master:ValidationFactory.cfc newBranch:ValidationFactory.cfc

I'd see a prompt that says something like:

view plain print about
1merge tool candidates: opendiff kdiff3 tkdiff xxdiff meld kompare gvimdiff diffuse ecmerge araxis emerge vimdiff
2Viewing: 'master:ValidationFactory.cfc'
3Hit return to launch 'opendiff':

And when I hit return FileMerge would open up with both files displayed. If I want to compare an entire folder, I can just type

view plain print about
1git difftool master:ValidateThis/core/ newBranch:ValidateThis/core/

And then I receive that prompt for each individual file in turn.

I still don't think this is anywhere near as good as what I had with Subclipse, and I'm guessing there are ways to configure it to make it even friendlier, but for now it's much better than git diff.

More Entries