Perforce to Git Migration

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

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