SVN to Git - prepping for the migration

Atlassian’s migration scripts

If you’re interested in making an abrupt transition to Git, Atlassian’s migration scripts are a good choice for you. These scripts provide all the tools you need to reliably convert your existing SVN repositories to Git repositories. The resulting native-Git history ensures you won’t need to deal with any SVN-to-Git interoperability issues after the conversion process.

We’ve provided a complete technical walkthrough for using these scripts to convert your entire codebase to a collection of Git repositories. This walkthrough explains everything from extracting SVN author information to re-organizing non-standard SVN repository structures.

SVN Mirror for Stash (now Bitbucket) plugin

SVN Mirror for Stash is a Bitbucket plugin that lets you easily maintain a hybrid codebase that works with both SVN and Git. Unlike Atlassian’s migration scripts, SVN Mirror for Stash lets you use Git and SVN simultaneously on the same project for as long as you like.

This compromise solution is a great option for larger companies. It enables incremental Git adoption by letting different teams migrate workflows at their convenience.

What is Git-SVN?

The git-svn tool is an interface between a local Git repository and a remote SVN repository. Git-svn lets developers write code and create commits locally with Git, then push them up to a central SVN repository with svn commit-style behavior. This should be temporary, but is helpful when debating making the switch from SVN to Git. 

git svn is a good option if you’re not sure about making the switch to Git and want to let some of your developers explore Git commands without committing to a full-on migration. It’s also perfect for the training phase—instead of an abrupt transition, your team can ease into it with local Git commands before worrying about collaboration workflows.

Note that git svn should only be a temporary phase of your migration process. Since it still depends on SVN for the “backend,” it can’t leverage the more powerful Git features like branching or advanced collaboration workflows.

Rollout strategies

Migrating your codebase is only one aspect of adopting Git. You also need to consider how to introduce Git to the people behind that codebase. External consultants, internal Git champions, and pilots teams are the three main strategies for moving your development team over to Git.

External Git consultants

Git consultants can essentially handle the migration process for you for a nominal fee. This has the advantage of creating a Git workflow that’s perfectly suited to your team without investing the time to figure it out on your own. It also makes expert training resources available to you while your team is learning Git. Atlassian Partners are pros when it comes to SVN to Git migration and are a good resource for sourcing a Git consultant.

On the other hand, designing and implementing a Git workflow on your own is a great way for your team to understand the inner workings of their new development process. This avoids the risk of your team being left in the dark when your consultant leaves.

Internal Git champions

A Git champion is a developer inside of your company who’s excited to start using Git. Leveraging a Git champion is a good option for companies with a strong developer culture and eager programmers comfortable being early adopters. The idea is to enable one of your engineers to become a Git expert so they can design a Git workflow tailored to your company and serve as an internal consultant when it’s time to transition the rest of the team to Git.

Compared to an external consultant, this has the advantage of keeping your Git expertise in-house. However, it requires a larger time investment to train that Git champion, and it runs the risk of choosing the wrong Git workflow or implementing it incorrectly.

Pilot teams

The third option for transitioning to Git is to test it out on a pilot team. This works best if you have a small team working on a relatively isolated project. This could work even better by combining external consultants with internal Git champions in the pilot team for a winning combo.

This has the advantage of requiring buy-in from your entire team, and also limits the risk of choosing the wrong workflow, since it gets input from the entire team while designing the new development process. In other words, it ensures any missing pieces are caught sooner than when a consultant or champion designs the new workflow on their own.

On the other hand, using a pilot team means more initial training and setup time: instead of one developer figuring out a new workflow, there’s a whole team that could potentially be temporarily less productive while they’re getting comfortable with their new workflow. However, this short term pain is absolutely worth the long term gain.

Security and permissions

Access control is an aspect of Git where you need to fundamentally re-think how you manage your codebase.

In SVN, you typically store your entire codebase in a single central repository, then limit access to different teams or individuals by folder. In Git, this is not possible: developers must retrieve the entire repository to work with it. You typically can not retrieve a subset of the repository, as you can with SVN. permissions can only be granted to entire Git repositories.

This means you have to split up your large, monolithic SVN repository into several small Git repositories. We actually experienced this first hand here at Atlassian when our Jira development team migrated to Git. All of our Jira plugins used to be stored in a single SVN repository, but after the migration, each plugin ended up in its own repository.

Keep in mind that Git was designed to securely integrate code contributions from thousands of independent Linux developers, so it definitely provides some way to set up whatever kind of access control your team needs. This may, however, require a fresh look at your build cycle.

If you’re concerned about maintaining dependencies between your new collection of Git repositories, you may find a dependency management layer on top of Git helpful. A dependency management layer will help with build times because as a project grows, you need “caching” in order to speed up your build time. A list of recommended dependency management layer tools for every technology stack can be found in this helpful article: "Git and project dependencies".

A repository for every developer

As a developer, the biggest change you’ll need to adjust to is the distributed nature of Git. Instead of a single central repository, every developer has their own copy of the entire repository. This dramatically changes the way you collaborate with your fellow programmers.

Instead of checking out an SVN repository with svn checkout and getting a working copy, you clone the entire Git repository to your local machine with git clone.

Collaboration occurs by moving branches between repositories with either git push, git fetch, or git pull. Sharing is commonly done on the branch level in Git but can be done on the commit level, similar to SVN. But in Git, a commit represents the entire state of the whole project instead rather than file modifications. Since you can use branches in both Git and SVN, the important distinction here is that you can commit locally with Git, without sharing your work. This enables you to experiment more freely, work more effectively offline and speeds up almost all version control related commands.

However, it’s important to understand that a remote repository is not a direct link into somebody else’s repository. It’s simply a bookmark that prevents you from having to re-type the full URL each time you interact with a remote repository. Until you explicitly pull or push a branch to a remote repository, you’re working in an isolated environment.

The other big adjustment for SVN users is the notion of “local” and “remote” repositories. Local repositories are on your local machine, and all other repositories are referred to as remote repositories. The main purpose of a remote repository is to make your code accessible to the rest of the team, and thus no active development takes place in them. Local repositories reside on your local machine, and it’s where you do all of your software development.

Don’t be scared of branching or merging

In SVN, you commit code by editing files in your working copy, then running svn commit to send the code to the central repository. Everybody else can then pull those changes into their own working copies with svn update. SVN branches are usually reserved for large, long-running aspects of a project because merging is a dangerous procedure that has the potential to break the project.

Git’s basic development workflow is much different. Instead of being bound to a single line of development (e.g., trunk/), life revolves around branching and merging.

When you want to start working on anything in Git, you create and check out a new branch with git checkout -b . This gives you a dedicated line of development where you can write code without worrying about affecting anyone else on your team. If you break something beyond repair, you simply throw the branch away with git branch -d . If you build something useful, you file a pull request asking to merge it into the main branch.

Potential Git workflows

When choosing a Git workflow it is important to consider your team's needs. A simple workflow can maximise development speed and flexibility, while a more complex workflow can ensure greater consistency and control of work in progress. You can adapt and combine the general approaches listed below to suit your needs and the different roles on your team. A core developer might use feature branches while a contractor works from a fork, for example.

• A centralized workflow provides the closest match to common SVN processes, so it's a good option to get started.
• Building on that idea, using a feature branch workflow lets developers keep their work in progress isolated and important shared branches protected. Feature branches also form the basis for managing changes via pull requests.
• A Gitflow workflow is a more formal, structured extension to feature branching, making it a great option for larger teams with well-defined release cycles.
• Finally, consider a forking workflow if you need maximum isolation and control over changes, or have many developers contributing to one repository.

But, if you really want to get the most out of Git as a professional team, you should consider the feature branch workflow. This is a truly distributed workflow that is highly secure, incredibly scalable, and quintessentially agile.

Transitioning your team to Git can be a daunting task, but it doesn’t have to be. This article introduced some of the common options for migrating your existing codebase, rolling out Git to your development teams, and dealing with security and permissions. We also introduced the biggest challenges that your developers should be prepared for during the migration process.

Hopefully, you now have a solid foundation for introducing distributed development to your company, regardless of its size or current development practices.