Perforce to Git Migration

What you will learn

• Understand the core purpose of Perforce to Git Migration
• Master the basic usage and common options of Perforce to Git Migration
• Migrate Perforce repositories to Git using git-p4, preserving branch structure, commit history, and author information.
• Understand key concepts: Overview
• Know when to use this feature and when to avoid it

Start with a problem

Your team is migrating from another version control system to Git, or moving code and history between different Git platforms. You're worried about losing commit history or author information during the process.

Overview

Perforce (Helix Core) is widely used in enterprise environments. git-p4 is Git's official bidirectional bridge for Perforce-to-Git migration.

Prerequisites

# Confirm git-p4 is installed
git p4 help

# Verify Perforce access
p4 info

# Check Perforce client config
p4 client -o

Preparation

1. Define Perforce Mapping

# Define the Perforce depot path to migrate
P4_PATH="//depot/main/..."

2. Author Mapping

Create an authors.txt file mapping Perforce users to Git authors:

perforce_user1 = Alice <alice@example.com>
perforce_user2 = Bob <bob@example.com>

Migration Methods

Method 1: Full Migration (Complete History)

# Full clone from Perforce
git p4 clone //depot/main/... --destination=my-repo

# With author mapping
git p4 clone --authors-file=authors.txt //depot/main/... my-repo

Method 2: Incremental Migration (Large Repos)

# Migrate recent history only
git p4 clone --max-changes=1000 //depot/main/... my-repo

# Incrementally fetch more
cd my-repo
git p4 sync

Method 3: With Labels

git p4 clone --use-client-spec --detect-labels //depot/main/... my-repo

Branch Migration

Perforce branches are typically directory-level copies, different from Git's branch model.

# Map Perforce branches to Git branches
git p4 clone //depot/main/... main-repo

# Migrate feature branch
git p4 clone //depot/feature/... --ref=refs/heads/feature feature-repo

Post-Migration Checks

# Verify commit history
git log --oneline --graph --all

# Check author info
git shortlog -sne

# Check file integrity
git fsck

# Stats
git count-objects -v

Common Issues

Large Files

# Clean up large binaries before migration
# Consider using Git LFS
git lfs track "*.psd" "*.bin"

Permission Loss

Perforce's file permission model doesn't map to Git. Recommended:

1. Review sensitive file permissions after migration
2. Use .gitattributes for necessary permissions

Try it yourself

1. Practice the git-p4-perforce command in a test repository and observe state changes before and after
2. Experiment with different options and compare the output differences
3. Simulate a real scenario where you would need to use this, and walk through the full process

Continue Learning

1. migration/svn-to-git — SVN to Git migration
2. migration/hg-to-git — Mercurial to Git migration
3. migration/platform-migration — Cross-platform Git migration

Further reading

Keep going on the same topic:

• git filter-repo Repository Rewriting Deep Dive
• Mercurial to Git Migration Guide
• Repository Migration Strategy Guide