git p4

A real-world coexistence tool when you can't migrate yet.

🎯 What & why

A two-way bridge between Git and Perforce. The real coexistence tool when management will not let you migrate yet.

🧠 Mental model

git p4 clone pulls P4 changelists into Git commits; git p4 submit reverses the flow, turning your Git commits into P4 changelists. Branch detection and client-spec handling are the sharp edges.

🛠️ Synopsis

git p4 <subcommand> [<options>]

Requires the p4 CLI on PATH and a working P4 environment (P4PORT,
P4USER, P4CLIENT). State lives under refs/remotes/p4/ and in the
git-p4.* config namespace. Treat the imported branches like any
other remote-tracking refs.

🎚️ Switches & options

Flag	What it does
`--branch <name>`	Name (or rename) the imported branch; defaults to refs/remotes/p4/master.
`--detect-branches`	Walk P4 branch specs and import each as its own Git branch instead of one linear history.
`--keep-path`	Preserve the full P4 depot path inside the Git tree instead of stripping the depot prefix.
`--use-client-spec`	Honor the current P4 client view when mapping depot paths to working-tree paths.
`--shelve`	On submit, create a P4 shelved changelist instead of submitting outright.
`--import-labels`	⚠️ Import every P4 label as a Git tag; on large depots this can create thousands of refs.

📦 Subcommands

clone — Initial import of a P4 depot path into a fresh Git repo.

git p4 clone --detect-branches //depot/proj@all proj.git

sync — Fetch new P4 changelists into the existing remote-tracking refs.

git p4 sync

rebase — Sync, then rebase the current branch onto the updated p4/master.

git p4 rebase

submit — Turn new Git commits on the current branch into P4 changelists.

git p4 submit --shelve

branches — List the P4 branches git p4 currently tracks.

git p4 branches

💡 Use cases

Letting a small team work in Git while the larger org stays on Perforce.
Phased migration: run the bridge for months, then cut over once tooling is ready.
Hosting a Git mirror of a P4 depot for code review tools that only speak Git.
Cherry-picking from a Git feature branch back into a P4 release stream.

🧪 Examples

Initial clone with branch detection

git p4 clone --detect-branches --use-client-spec //depot/proj@all

Pick up new P4 changelists and rebase

git p4 rebase

Submit local commits as P4 changelists

git p4 submit

Shelve instead of submit for review

git p4 submit --shelve --update-shelve 1234

🎓 Recommendations

Set git-p4.useclientspec=true and git-p4.detectRenames=true once, in repo config, so every operation behaves consistently.
Always git p4 rebase before git p4 submit; submit without a fresh sync produces out-of-order changelists.
Keep one Git branch per P4 stream; do not try to multiplex submits from a single branch onto two streams.

🪤 Common pitfalls

Running git p4 clone without --use-client-spec on a depot that depends on view mappings; you get the wrong tree.
Importing labels on a large depot without thinking; refs/tags explodes and fetches slow to a crawl.
Force-pushing or rewriting commits that have already been submitted to P4; the bridge will resubmit them as duplicates.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.