A step-by-step guide to migrating from Perforce to Git

Step 2: Mapping users and permissions to a new Git repo

After the data is moved over, the next task is usually to start mapping your users and permissions into new Bitbucket projects. If you use LDAP for a user directory you’ll save some time here. Otherwise, you can easily extract a set of user accounts from Perforce using the p4 users –o command and then enter them into Bitbucket a project at a time.

Translating Perforce permissions into the equivalent Bitbucket permissions can be difficult because Perforce permissions are granular and complex, with the possibility of excluding access to individual files. This complicated permission scheme is one reason why a Perforce server can bog down – every attempt at access may cause the server to perform an expensive computation on a complicated data structure.

In most cases it’s faster just to ask project leads to define a simpler set of permissions in Bitbucket using the normal project, repo, and branch level permissions. Indeed, you’ll want to revisit your permission setup anyway, as Git offers up so many new workflow options. For example, in Perforce you may have restricted branch creation, while in Bitbucket you may only need to restrict push access to the main branch.

Step 3: Managing large binary files

If you stored large binary blobs in Perforce, think carefully about how you want to manage those in Git. You could try out Git LFS, or you could simply use a regular artifact management system instead. In any case you don’t want to blindly push large blobs into a Git repo.

Step 4: Managing complex dependencies

A Perforce working copy may actually map in read-only copies of data from several modules. In Git, this is done either using submodules, subtrees, or by leveraging CI/CD or artifact management systems. There’s no easy answer here, but some data import tools can model a submodule relationship between Git repos. For a more in depth look on how to use submodules or subtrees, you can read about each here: https://www.atlassian.com/git/tutorials/git-subtree.

Step 5: Structuring your team during the migration

So, your Perforce server has 100 projects from 10 teams. You’ve got a migration strategy and tool set laid out. Schedule the maintenance window and go!

Er… no.

Remember that switching SCM tools is as much about developers as it is data. You’ve got people, process, and schedule to consider – don’t try to boil the ocean in a single day. It’s too risky.

You need to consider a project plan during the actual migration phase. (It might be a good time to try out a new Jira workflow…) Here are some options you can look at.

• Migrate team-by-team and project-by-project. Aim to start a project and team at the beginning of a sprint or program increment, when you have some time to adapt.
• Migrate incrementally. Import all of your data in a weekend, but then let teams slowly complete the switch to Git over time. Periodically pickup the deltas by re-running your import tools. Although more complex, this strategy isn’t bad if you have dependencies between teams and the early adopters need at least a recent snapshot in Git to feed their CI/CD pipeline.
• Use both systems at the same time for a period of time. While not for the faint of heart, it’s technically feasible to use Git Fusion to do a two-way data exchange as long as you are not doing complex operations that will confuse the data translator.

Lastly, invest in communicating the changes to the team – the motivation, the why, and a series of steps for how to do it. Pick an “early adopter” team with engineers experienced in the entire software development lifecycle, and have that team be a model for the others. Find Git champions to assist people when they have a difficulty. Making small, understandable, iterative changes will help this process be successful.

Step 6: Mirroring data

Perforce has a simple but effective system for mirroring data to remote sites to reduce the effect of latency. It has a more complex system for running a set of local mirrors for read-only clustering. Although latency is simply not as much of a concern for Git, if you are running a worldwide operation you should look at Bitbucket Data Center for both clustering and mirroring, which will greatly speed up your clone times for a global team.

Step 7: Choosing your ALM Tools

And now for some good news – you’ve got a lot of choices for your ALM tool stack when you move from Perforce to Git. Pretty much every developer and ALM tool out there works with Git, and of course Bitbucket gives you great integration with Jira and Bamboo. As you transition to Git, you can explore Bamboo features such as Plan Branches that take advantage of a feature branch workflow.

Step 8: Defining success after a Perforce to Git migration

So how exactly do you measure success during a migration from Perforce to Git? In many migration projects we tend to focus too much on the fidelity of data transfer. But that is not a useful metric for many reasons. It’s likely that you can never get a bit-for-bit history in Git that is exactly the equivalent of what happened in a centralized SCM system like Perforce.

A more practical approach is to use CI/CD for verification. Once you switch your CI/CD pipeline from Perforce to Git, do all your tests still pass? And can you still deploy your software? If all of your important older builds can still pass through your CI/CD pipeline, then it’s time to declare victory!

That’s a wrap

So now you’ve seen why there’s movement from Perforce to Git, and how to actually get there. The next step is to choose a Git solution. If you are switching from Perforce for game development, see why game developers love Bitbucket.