git-p4

git p4 clone | sync | submit [options]

--help
    Display help message and exit.

--version
    Display version information and exit.

--debug
    Enable debugging output.

--verbose
    Enable verbose output.

-d
    Specify the Perforce depot path to clone, sync, or submit from. This parameter is mandatory for clone, and often needed for sync/submit. Example: '//depot/project'.

-b
    Specify the Git branch name. Default is 'master'.

--branch-in-name
    Include the git branch name in the commit messages generated from P4 changes.

-g
    Specify the Git command to use. Default is 'git'.

--detect-branches
    Detect branches during import. Git-p4 will attempt to separate history imported from Perforce into multiple branches.

--max-changes
    Limit the number of Perforce changes to import. Useful for initial testing.

--changes
    Import only changes within the specified range. Example: '1234-5678'.

--use-client-spec
    Use the current P4 client spec to filter files for submitting changes to Perforce. Useful when you only want to submit a subset of the changes based on the client view.

--import-local
    Import commits that only exist in the local git repository. By default it skips git commits not already submitted to P4.

--p4-port
    Specify the Perforce port. Overrides the P4PORT environment variable.

--p4-user
    Specify the Perforce user. Overrides the P4USER environment variable.

--p4-client
    Specify the Perforce client. Overrides the P4CLIENT environment variable.

--preserve-user
    Preserve the original user when submit from git to perforce.

--cleanup
    Removes any temporary files and directories created during the operation.

-r
    Create a review after each submission (only relevant for submit).

The `git-p4` command is a utility that facilitates bidirectional code migration and synchronization between a Git repository and a Perforce Helix Core version control server. It allows you to import changes from a Perforce depot into a Git branch, effectively creating a Git history that mirrors the Perforce history. Conversely, it allows you to submit Git commits to a Perforce depot as changelists. This is useful for teams transitioning from Perforce to Git or for projects that require collaboration between developers using both version control systems. The command supports various options for customizing the import and export process, including specifying the Perforce depot path, branch mappings, and author mappings. It requires a configured Perforce environment and a working Git repository. While powerful, `git-p4` requires careful configuration and understanding of both Git and Perforce concepts to avoid data loss or conflicts.

The core functionalities are 'clone', 'sync', and 'submit'. Clone is to clone a p4 repository to git, sync is to pull changes from p4 into git, and submit is to submit changes from git to p4.

Requires a properly configured Perforce environment (P4PORT, P4USER, P4CLIENT environment variables) and a valid Git repository. Submitting changes from Git to Perforce can be complex and may require manual conflict resolution. Large histories can take considerable time and resources to clone. It is a good practice to test a small subset of the history before attempting to import the entire depot. Incorrect configuration can lead to data loss or corruption in either the Git or Perforce repository. Careful planning is highly recommended.

Git-p4 does not handle Perforce branches and integrations natively; these often need special handling.

You can map Perforce users to Git authors using an author mapping file. This file typically contains lines of the form 'Perforce User = Git Name '. This mapping is important for preserving accurate authorship information during import and export operations.

Cloning very large Perforce repositories can be time-consuming and resource-intensive. Consider using techniques such as shallow cloning or importing only a subset of the history initially to improve performance.

When submitting changes from Git to Perforce, conflicts may arise if the same files have been modified in both systems. `git-p4` will attempt to automatically resolve conflicts, but manual intervention may be required in some cases. It is important to understand Git and Perforce conflict resolution mechanisms to resolve these issues effectively.

Make sure to create a .gitignore file for files and paths that you don't want git to track in your repository. Otherwise, git-p4 could try to submit those files to Perforce and the submit may fail.

The `git-p4` command was created to bridge the gap between Git and Perforce, two popular version control systems. It has evolved over time to support various workflows, including one-time migrations from Perforce to Git, and continuous synchronization between the two systems. Development focuses on improving performance, handling complex Perforce features, and providing better error handling. Usage has increased as more organizations adopt Git while still needing to interact with existing Perforce repositories. Early versions were less robust and had limitations in handling large repositories or complex branching scenarios. Modern versions have addressed many of these issues, making `git-p4` a more reliable and versatile tool.

git(1), p4(1)