What to consider before migrating to Git

Series: An Introduction to Git

9th of September, 2012

This is the second part of a three part series about migrating to Git. If you haven’t read part one and are unfamiliar with the advantages of Git, you should check it out.

Migrating to Git, Part 1: Advantages

If you already understand the benefits of Git, or have already read part one, welcome to part two in the series! We’re going to discuss certain pre-conditions of a migration to Git and make sure your team is ready for the transition.


Before migrating to Git, you should make sure your team is ready to migrate. Changing version control systems (especially in a large team) is not a trivial undertaking, and certain technical debt should not exist in your code base to ensure a smooth transition.

Here’s a rough guide to help you evaluate whether you’re ready to migrate:

1. Ensure your code base is buildable and stable

If you can’t perform a clean, full build of your application, you should absolutely delay your migrations plans and pay down technical debt before attempting any large scale project (let alone something is risky as migrating to a different version control system). Post-migration, the entire application will need to be completely rebuilt and regression tested. This seems like an obvious prerequisite, but not every organization performs full builds on a regular basis, especially with legacy applications. Being unable to build your application or lacking confidence in your build is a recipe for disaster.

2. Set up a continuous integration server

It’s a good idea to implement a CI solution in order to get up-to-date feedback on build issues as developers begin to use Git for the first time. It’s amazing the types of issues that crop up in the first few days post-migration. Most issues are minor if they’re caught early enough.

3. Prepare a regression test plan or implement automated testing

Changing version control systems is quite disruptive. Prepare for a number of things to go wrong. At the very minimum, you should plan for a full regression test of your application immediately after migration and before developers begin committing code. This window should be minimized to avoid syncing nightmares.

If you don’t have an automated test suite, this may be a burden to your QA team. There may be a temptation to piggy-back the Git migration onto a major release and kill two testing birds with one stone, but I caution against this as it will be hard to track down the root cause of defects.

If you work in a team that practices Kanban or Scrum, it’s a good idea to plan for a loss of velocity during the migration period. This loss of productivity should be minimal if the migration is planned properly. For instance, if your team practices Scrum, it may be a good idea to consider the migration iteration zero and release the product (fully tested) at the end of the sprint. A full sprint is unnecessary, but a short sprint (of a week or less) is also a good opportunity to pay down any kind of technical debt that is a blocker of the migration to Git.

4. Plan for training

Our team attempted to train grassroots-style, and it was tough. Budget for at least a full day of training to ensure your developers are comfortable with core Git and DVCS concepts.

It also helps that developers understand the rationale for switching version control systems, as any impedance to velocity will be met with frustration. If they understand the long-term benefits, it will make the short-term frustrations easier to deal with.

5. Identify an evangelist to lead the migration and post-migration support

At least one member of the team should be very familiar with Git in order to ensure a smooth migration.

Certain questions will come up, like:

It’s helpful for one person to take ownership of the migration and establish a developer workflow before the migration. The workflow will evolve, but it helps to have a starting point and a rough objective. The evangelist will guide the team through the initial learning curve, and after the entire team is comfortable with Git the decision making process will naturally become more democratic and decentralized, just like Git itself.

Speaking from personal experience, it’s helpful (but not required) that the evangelist is not distracted with development tasks immediately after post-migration. I recommend considering them a build manager or a DevOps team-member for a finite period of time post-migration to ensure capacity for support.

6. Make a list of why you’re migrating to Git in the first place

This the least technical prerequisite and more of a return-on-investment analysis exercise.

It’s important to come up with a justification for the migration. If you’re unable to make this list and be prepared to justify it, you probably don’t have someone on the team that understands the benefits of Git well enough to support the migration through the often challenging transitional period.¬†Simply put, if you’re unable to justify the expense and disruption of a VCS migration, don’t bother. Wait around until you’re about to create a reasonable business case and that you have specific measurable goals to revisit during the post-migration retrospective.

This list may include items such as:

The final steps

If you’re confident and ready to migrate to Git, check out the final part of my Migrating to Git series, Migrating to Git, Part 3: Moving your code to Git.

This work by Kevin Webber is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.