Introducing GitHub Compare View

Picking up where Kyle left off in his Branch List post, we’re all very excited to announce a new feature designed to ease the process of comparing two points in a repository’s history. It’s called GitHub Compare View and it’s going to change the way you review code.

compare view example

The Compare View brings all information needed to determine what changed over a series of commits onto a single page: a condensed commit list in chronological order, followed by a rollup diff of all changes between the two points, followed by any relevant commit comments. All in the same place and with a single well-defined URL.

It’s a versatile feature with many potential uses. Some of our favorites are detailed below with links to live examples of Compare View in action.

Reviewing topic branches before merging

Reviewing topic branches is a fundamental activity for anyone maintaining an active open source project or working with a team on a private project. Until now, the easiest way to do a thorough review of a complex topic branch was to drop down to the shell and run some combination of the git log, git cherry, and git diff commands. With Compare View, we’ve taken that process and put it behind a single URL, so jumping into the review process is usually as simple as following a link.

Follow the examples below to see it live:

jquery omgrequire branch screen cap

Edit: These branches have been removed since the publishing of this post and can no longer be shown.

Generating comprehensive change logs for releases

While Compare View was initially designed to supplement our code review process, we quickly found that it was useful in a variety of other scenarios. Projects that are diligent about tagging can use Compare View to generate a comprehensive list of changes between any two releases.

A few examples in the wild:

Sinatra 0.9.4...1.0.a screen cap

How to customize the commit range

The commit range determines the starting and ending point to use in the comparison. It looks like this:

Here, we’re reviewing the proxy_owner topic branch using the master branch as the starting point. Hitting the button switches the starting and ending points. Clicking the starting or ending point label brings up the ref selector:

ref selector

Enter any branch, tag, or commit SHA1 in the little box there and get an instant preview of the newly selected revision. Hit Save & Refresh once you’re happy with the selection.

Getting There

We’ve seen what the Compare View feels like and how to change the commit range once there, but how do you get to a Compare View in the first place?

  • The Branch List page. Click the Compare button next to any branch to jump into a Compare View with that branch as the ending point. See Kyle’s post introducing the Branch List page for more information.
  • Push and Branch Create events. All push events with more than one commit now link to a Compare View over all commits included in the push. All create branch events now link to a Compare View between the repository’s default branch (typically master) and the branch head. This effects dashboards, repository timelines, and activity feeds.
  • Service Hooks. The IRC and Campfire service hooks now drop a Compare View link when more than one commit is included in the push. More service hooks will follow.

Compare View URLs

We wanted Compare View to be something we could link to from external sites and services anytime we were referring to a range of commits in a git repository. As such, we thought it would be worthwhile to document the basic structure of a Compare View URL:<USER>/<REPO>/compare/[<START>...]<END></i>

Where <USER> and <REPO> are obvious, and <START> and <END> are branch names, tag names, or commit SHA1s specifying the range of history to compare. If <START> is omitted, the repository’s default branch is assumed.

Big Plans

Compare View is the first of many code review related features we plan to introduce this year. We’ll be incorporating Compare View into other areas of the site and developing entirely new features with Compare View as a core component.

That being said, we felt it was important that the basic task of comparing two points in a repository’s history stand on its own and have a well defined URL so that the feature is useful in a broad number of circumstances. If everything goes to plan, you’ll be seeing Compare View links tossed around on mailing lists, forums, IRC channels, Campfire, blog posts, release announcements, issue trackers, etc. in the very near future.

"git-rev-parse(1) man page"
Have feedback on this post? Let @github know on Twitter.
Need help or found a bug? Contact us.



Discover new ways to build better

Try Marketplace apps free for 14 days

Learn more