Category: Tools

For the past year I’ve been using Perforce for my VCS. Originally, I had used Perforce over something like Git or SVN because of its ubiquity in game development and its supposed advantage in handling large binary files. I think Perforce is a fine VCS, but the lack of documentation, being locked into using Perforce’s tools (at least to my knowledge), and an almost nonexistent community has me reconsidering other VCS options. I decided it was time to take another look at Git. Git is used basically everywhere, has a wealth of resources, and I like having the choice of different self-hosted services like GitLab and Gitea (which is what I’m using now). Git also seems to handle binary files better these days, with Git LFS adding file locking support, which basically allows Git users to get the same functionality that a Perforce checkout would enable.

With the decision to switch from Perforce to Git settled, I looked into how best to convert my existing Perforce depot into a Git repository. I wanted to write a quick help you avoid some of the snags I encountered.

If you don’t care about preserving your Perforce history

It should be noted, this process is extremely easy if you don’t care about preserving the history of your Perforce depot. If this applies to you, the easiest way to switch from Perforce to Git is to simply initialize a new Git repository in the local Perforce workspace. At this point you can add a .gitignore, initialize Git LFS, and then push this repo to the remote Git hosting service of your choice. This of course means your Git commit history will be starting from the latest revision Perforce depot you’ve pulled. This may be fine for projects early on in development, but if you have release milestones you’d like to be able to revert back to, you’ll want to preserve your history while converting to a Git repository. Luckily, Git provides some tools to assist in this conversion.

Covert from P4 to a Git while maintaining your Perforce history

Setting up the environment

We will need Python installed to run the git-p4 script. On Windows you can check to see if Python is installed by running

py --version

If Python is installed, you should see some output like

Python 3.10.1

Where the version number will be whatever is recent at the time reading this. In my case I was using 3.10.1. I have not tested this process using Python 2, but I don’t see why it wouldn’t work.

In my case, I was getting errors when trying to run this script. Downloading the latest script from here fixed the problem. In my case I’m using Fork, so my git-p4 script goes in the C:\Users\[USER_NAME]\AppData\Local\Fork\gitInstance\2.33.1\mingw64\libexec\git-core directory.

You’ll also need to add an alias to your .gitconfig, which aliases p4 to the git-p4.py script you just downloaded. The line should be added to [alias] section of your .gitconfig and should look something like this:

[alias]
	p4 = !'C:\\Users\\kevin\\AppData\\Local\\Fork\\gitInstance\\2.33.1\\mingw64\\libexec\\git-core\\git-p4.py'

You should replace the path with wherever you had downloaded the git-p4.py script in the previous step.

Cloning from your Perforce depot

You’ll first want to open your Perforce workspace. For me this meant opening P4V and connecting to my remote Perforce server. After that you can run:

git p4 clone //depot/main@all [Path_And_Name_Of_Your_New_Repository]

This will clone the Perforce depot as a Git repository in the path your specified. For example:

git p4 clone //depot/main@all /z/Repos/MyRepo

Will clone the repository in the folder Z:/Repos/MyRepo. The @all at the end of the depot path specifies to preserve the entire Perforce submission history as a Git commit history. Once the cloning completes, you can check this by running either git log or gitk. At this point you can do any other “smoke tests” you’d normally do to make sure your clone was successful.

Conclusion

At this point you have a new Git repository, and can do anything you’d do with any other Git repository. Since you’ve just cloned from Perforce, you’ll probably want to add a .gitignore, initialize Git LFS, add a .gitattributes file, and setup your new remote. At this point you can now use Git as your VCS for your project.