Subscribe

Inform and Act

Read our official statements regarding recent executive orders and find resources to help you take action. Learn more

Are you part of a software development team that's recently moved to
GitHub? Where some team members are excited to use git for source control but
you're more comfortable with Subversion? The good news is that you can
all use the tools you already enjoy - GitHub repositories can be accessed from
both Git and Subversion (SVN) clients.

This is an overview of how you can take advantage of
the GitHub Flow
from your favorite Subversion client.

The GitHub Flow involves iterating through the following steps for each
feature/fix:

  1. Create a topic branch from the latest master branch
  2. Make commits in the topic branch until you're ready to merge it
  3. Make a pull request to pull the topic branch into the master branch; discuss the
    changes, make more commits, etc. until the team is ready to merge it
  4. Merge the pull request and deploy

Get Started

The first thing you'll want to do is a Subversion checkout. Since Git clones keep the
working directory (where you edit files) separate from the repository
data, there is only one branch in the working directory at a time.
Subversion checkouts are different -- they mix the repository data in the
working directories, so there is a working directory for each branch and
tag you've checked out. For repositories with many branches and tags,
checking out everything can be a bandwidth burden; so you should start
with a partial checkout.

GitHub supports both Git and Subversion clients using the HTTP protocol,
start by browsing to the repository page on github.com to get the HTTP clone URL:
repo-snapshot

Then get your checkout ready:

  1. Start with an empty checkout of the repository. Browse to the
    repository page on github.com and use the HTTP clone URL:

    $ svn co --depth empty https://github.com/widgetmakers/gizmo
    Checked out revision 1.
    $ cd gizmo
    
  2. Get the 'trunk' branch. The Subversion bridge maps trunk to
    the git HEAD branch (usually master.)

    $ svn up trunk
    A    trunk
    A    trunk/README.md
    A    trunk/gizmo.rb
    Updated to revision 1.
    
  3. Get an empty checkout of the branches directory. This is
    where all of the non-HEAD branches live, and where you'll be making
    feature branches.

    $ svn up --depth empty branches
    Updated to revision 1.
    

Get Into The Flow

The first step is to create a topic branch from the latest master
branch. From your svn client, make sure master is current by updating
trunk; then use svn copy to create a branch.

$ svn up trunk
At revision 1.
$ svn copy trunk branches/more_awesome
A         branches/more_awesome
$ svn commit -m 'Added more_awesome topic branch'
Adding         branches/more_awesome

Committed revision 2.

You can see that the new branch is there from the web interface or a git
client:

branch-snapshot

$ git fetch
From https://github.com/widgetville/gizmo
 * [new branch]      more_awesome -> origin/more_awesome

Write Some Code

Add some features, fix some
bugs, and make plenty of commits along the way. This works like the
Subversion you're used to - edit your file(s) and use svn commit to
record your changes.

$ svn status
M       gizmo.rb
$ svn commit -m 'Guard against known problems'
Sending        more_awesome/gizmo.rb
Transmitting file data .
Committed revision 3.
$ svn status
?       test
$ svn add test
A         test
A         test/gizmo_test.rb
$ svn commit -m 'Test coverage for problems'
Adding         more_awesome/test
Adding         more_awesome/test/gizmo_test.rb
Transmitting file data .
Committed revision 4.

Discuss, Develop, Deliver

When you have your changes ready to share with the rest of the team, use
the web interface to make a Pull Request:

  1. Browse to your topic branch and click on the Pull Request button to
    the right of your repository name.
    pr-create
  2. Fill out the Pull Request form with a description of the changes in
    your branch.
    pr-describe
  3. Discuss the changes with your team members. The discussion includes
    comments on commits in the pull request, comments entered on the pull
    request web page, and commits added to the topic branch.
    pr-discuss
  4. Merge your pull request. The pull request page will indicate whether the changes can be merged cleanly; in most cases they can, and all you need to do is click the button and you're done! If there are conflicts, you'll need to resolve them first, which we'll cover in a later blog post.
    pr-merge1
    pr-merge2
    pr-closed

Your changes will now be in the master branch; use svn update to bring your checkout up to date, and then start working on the next awesome thing!

Have feedback on this post? Let @github know on Twitter.

Need help or found a bug? Contact us.