git-p4

git p4 command [options] [args]

Common commands:
    git p4 clone [options] //depot/path...
    git p4 sync [options]
    git p4 submit [options] [changelist...]

--help
    Show help message and exit.

--version
    Show program's version number and exit.

--detect-branches
    Attempt to detect Perforce branches automatically during clone or sync operations.

--nomg
    Disable Perforce Multi-Git integration if the server supports it.

--sync-only
    Used with 'submit'; synchronize the Git repository but do not submit changes to Perforce.

--preserve-empty-commits
    During 'submit', preserve Git commits that result in empty changelists in Perforce.

--max-changes=
    Limit the number of Perforce changelists to import during clone or sync.

--branch=
    Specify a specific Perforce branch to track (e.g., 'main', 'release').

--origin=
    Set the name of the Git remote that tracks the Perforce history; default is 'p4'.

--user=
    Specify the Perforce user for authentication.

--port=
    Specify the Perforce server address (e.g., 'perforce.example.com:1666').

--client=
    Specify the Perforce client workspace name to use for operations.

--import-labels
    Import Perforce labels as Git tags during clone or sync.

--submit-labels
    When submitting, import any Git tags matching Perforce label names.

--dry-run
    Perform all checks and preparation for submit, but do not actually submit changes to Perforce.

--prepare-only
    Only prepare the Perforce changelist for submission, do not submit it. Useful for manual review.

--auto-submit
    Automatically submit the prepared changelist to Perforce without manual confirmation.

--preserve-ownership
    Attempt to preserve original Git commit author and date information when submitting to Perforce.

--git-authors
    Use a .git-p4-authors file to map Git commit authors to Perforce users for correct attribution.

--debug
    Enable debug output for troubleshooting.

The git-p4 command provides a robust bridge between the Git and Perforce Source Code Management systems. It enables developers to leverage Git's powerful local workflow and features (like branching, merging, and fast commits) while interacting with a Perforce server for centralized version control.

git-p4 allows users to import Perforce history into a Git repository, synchronize the Git repository with new changes from Perforce, and submit Git commits back to Perforce as new changelists. This is particularly useful for teams migrating from Perforce to Git, or for those who wish to use Git's distributed nature for local development while maintaining Perforce as the canonical shared repository.

It handles the mapping of Perforce changelists to Git commits and vice versa, supporting features like branch detection, label import, and author mapping.

Perforce 'streams' are not directly supported by git-p4 and must often be managed as standard branches or through specific client views.

Complex Perforce integrations, such as those involving exclusive locks or highly customized triggers, may not translate perfectly to the Git workflow.

Unicode path encoding and large binary files can sometimes pose challenges; ensure your Perforce client and server are configured correctly for character sets and file types.

A working Perforce command-line client (`p4`) must be installed and accessible in the system's PATH.

Many git-p4 behaviors can be configured via Git's configuration system, using `git config`. For instance, `git config git-p4.user ` or `git config git-p4.port ` can set default Perforce connection parameters, avoiding the need to specify them with every command invocation. Other options like `git-p4.detectBranches` can also be persisted in the Git repository's configuration.

To ensure correct author attribution when submitting Git commits to Perforce, git-p4 can utilize a `.git-p4-authors` file. This file maps Git author identities (name and email) to Perforce usernames. For example, a line in this file might look like: `Jane Doe = janedoe_p4`. This allows maintaining proper ownership and history in Perforce.

git-p4 is a long-standing component of the Git distribution's `contrib` directory. It was developed to provide an effective bridge for organizations using Perforce to integrate with the Git workflow, or for individual developers wanting to use Git locally against a Perforce backend. Its development has focused on robustness and compatibility, adapting to new Git and Perforce features over time, making it a reliable tool for mixed SCM environments.

git(1), p4(1), git-fast-import(1), git-rebase(1)