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…
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.
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:
Edit: These branches have been removed since the publishing of this post and can no longer be shown.
- [jQuery require support branch]()
- [Mustache pragma support branch]()
- [Homebrew Pathname.rename branch]()
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:
- Changes between the Sinatra 0.9.4 and 1.0.a releases (pictured above)
- Changes between the Rails 3.0 beta and current master
- Changes slated for the next version of Git
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:
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 (typicallymaster
) 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:
http://github.com/<USER>/<REPO>/compare/[<START>...]<END>
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"
Written by
Related posts
Congratulations to the winners of the 2024 Gaady Awards
The Gaady Awards are like the Emmy Awards for the field of digital accessibility. And, just like the Emmys, the Gaadys are a reason to celebrate! On November 21, GitHub was honored to roll out the red carpet for the accessibility community at our San Francisco headquarters.
Students: Start building your skills with the GitHub Foundations certification
The GitHub Foundations Certification exam fee is now waived for all students verified through GitHub Education.
Announcing GitHub Secure Open Source Fund: Help secure the open source ecosystem for everyone
Applications for the new GitHub Secure Open Source Fund are now open! Applications will be reviewed on a rolling basis until they close on January 7 at 11:59 pm PT. Programming and funding will begin in early 2025.