git-p4.1 (32811B)
- '\" t
- .\" Title: git-p4
- .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
- .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
- .\" Date: 2025-03-14
- .\" Manual: Git Manual
- .\" Source: Git 2.49.0
- .\" Language: English
- .\"
- .TH "GIT\-P4" "1" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
- .\" -----------------------------------------------------------------
- .\" * Define some portability stuff
- .\" -----------------------------------------------------------------
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .\" http://bugs.debian.org/507673
- .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- .ie \n(.g .ds Aq \(aq
- .el .ds Aq '
- .\" -----------------------------------------------------------------
- .\" * set default formatting
- .\" -----------------------------------------------------------------
- .\" disable hyphenation
- .nh
- .\" disable justification (adjust text to left margin only)
- .ad l
- .\" -----------------------------------------------------------------
- .\" * MAIN CONTENT STARTS HERE *
- .\" -----------------------------------------------------------------
- .SH "NAME"
- git-p4 \- Import from and submit to Perforce repositories
- .SH "SYNOPSIS"
- .sp
- .nf
- \fIgit p4 clone\fR [<sync\-options>] [<clone\-options>] <p4\-depot\-path>\&...\:
- \fIgit p4 sync\fR [<sync\-options>] [<p4\-depot\-path>\&...\:]
- \fIgit p4 rebase\fR
- \fIgit p4 submit\fR [<submit\-options>] [<master\-branch\-name>]
- .fi
- .SH "DESCRIPTION"
- .sp
- This command provides a way to interact with p4 repositories using Git\&.
- .sp
- Create a new Git repository from an existing p4 repository using \fIgit p4 clone\fR, giving it one or more p4 depot paths\&. Incorporate new commits from p4 changes with \fIgit p4 sync\fR\&. The \fIsync\fR command is also used to include new branches from other p4 depot paths\&. Submit Git changes back to p4 using \fIgit p4 submit\fR\&. The command \fIgit p4 rebase\fR does a sync plus rebases the current branch onto the updated p4 remote branch\&.
- .SH "EXAMPLES"
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Clone a repository:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git p4 clone //depot/path/project
- .fi
- .if n \{\
- .RE
- .\}
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Do some work in the newly created Git repository:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ cd project
- $ vi foo\&.h
- $ git commit \-a \-m "edited foo\&.h"
- .fi
- .if n \{\
- .RE
- .\}
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Update the Git repository with recent changes from p4, rebasing your work on top:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git p4 rebase
- .fi
- .if n \{\
- .RE
- .\}
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Submit your commits back to p4:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git p4 submit
- .fi
- .if n \{\
- .RE
- .\}
- .RE
- .SH "COMMANDS"
- .SS "Clone"
- .sp
- Generally, \fIgit p4 clone\fR is used to create a new Git directory from an existing p4 repository:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git p4 clone //depot/path/project
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- This:
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 1.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 1." 4.2
- .\}
- Creates an empty Git repository in a subdirectory called
- \fIproject\fR\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 2.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 2." 4.2
- .\}
- Imports the full contents of the head revision from the given p4 depot path into a single commit in the Git branch
- \fIrefs/remotes/p4/master\fR\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04' 3.\h'+01'\c
- .\}
- .el \{\
- .sp -1
- .IP " 3." 4.2
- .\}
- Creates a local branch,
- \fImaster\fR
- from this remote and checks it out\&.
- .RE
- .sp
- To reproduce the entire p4 history in Git, use the \fI@all\fR modifier on the depot path:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git p4 clone //depot/path/project@all
- .fi
- .if n \{\
- .RE
- .\}
- .SS "Sync"
- .sp
- As development continues in the p4 repository, those changes can be included in the Git repository using:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git p4 sync
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- This command finds new changes in p4 and imports them as Git commits\&.
- .sp
- P4 repositories can be added to an existing Git repository using \fIgit p4 sync\fR too:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ mkdir repo\-git
- $ cd repo\-git
- $ git init
- $ git p4 sync //path/in/your/perforce/depot
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- This imports the specified depot into \fIrefs/remotes/p4/master\fR in an existing Git repository\&. The \fB\-\-branch\fR option can be used to specify a different branch to be used for the p4 content\&.
- .sp
- If a Git repository includes branches \fIrefs/remotes/origin/p4\fR, these will be fetched and consulted first during a \fIgit p4 sync\fR\&. Since importing directly from p4 is considerably slower than pulling changes from a Git remote, this can be useful in a multi\-developer environment\&.
- .sp
- If there are multiple branches, doing \fIgit p4 sync\fR will automatically use the "BRANCH DETECTION" algorithm to try to partition new changes into the right branch\&. This can be overridden with the \fB\-\-branch\fR option to specify just a single branch to update\&.
- .SS "Rebase"
- .sp
- A common working pattern is to fetch the latest changes from the p4 depot and merge them with local uncommitted changes\&. Often, the p4 repository is the ultimate location for all code, thus a rebase workflow makes sense\&. This command does \fIgit p4 sync\fR followed by \fIgit rebase\fR to move local commits on top of updated p4 changes\&.
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git p4 rebase
- .fi
- .if n \{\
- .RE
- .\}
- .SS "Submit"
- .sp
- Submitting changes from a Git repository back to the p4 repository requires a separate p4 client workspace\&. This should be specified using the \fBP4CLIENT\fR environment variable or the Git configuration variable \fIgit\-p4\&.client\fR\&. The p4 client must exist, but the client root will be created and populated if it does not already exist\&.
- .sp
- To submit all changes that are in the current Git branch but not in the \fIp4/master\fR branch, use:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git p4 submit
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- To specify a branch other than the current one, use:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git p4 submit topicbranch
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- To specify a single commit or a range of commits, use:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git p4 submit \-\-commit <sha1>
- $ git p4 submit \-\-commit <sha1\&.\&.sha1>
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- The upstream reference is generally \fIrefs/remotes/p4/master\fR, but can be overridden using the \fB\-\-origin=\fR command\-line option\&.
- .sp
- The p4 changes will be created as the user invoking \fIgit p4 submit\fR\&. The \fB\-\-preserve\-user\fR option will cause ownership to be modified according to the author of the Git commit\&. This option requires admin privileges in p4, which can be granted using \fIp4 protect\fR\&.
- .sp
- To shelve changes instead of submitting, use \fB\-\-shelve\fR and \fB\-\-update\-shelve\fR:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git p4 submit \-\-shelve
- $ git p4 submit \-\-update\-shelve 1234 \-\-update\-shelve 2345
- .fi
- .if n \{\
- .RE
- .\}
- .SS "Unshelve"
- .sp
- Unshelving will take a shelved P4 changelist, and produce the equivalent git commit in the branch refs/remotes/p4\-unshelved/<changelist>\&.
- .sp
- The git commit is created relative to the current origin revision (HEAD by default)\&. A parent commit is created based on the origin, and then the unshelve commit is created based on that\&.
- .sp
- The origin revision can be changed with the "\-\-origin" option\&.
- .sp
- If the target branch in refs/remotes/p4\-unshelved already exists, the old one will be renamed\&.
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git p4 sync
- $ git p4 unshelve 12345
- $ git show p4\-unshelved/12345
- <submit more changes via p4 to the same files>
- $ git p4 unshelve 12345
- <refuses to unshelve until git is in sync with p4 again>
- .fi
- .if n \{\
- .RE
- .\}
- .SH "OPTIONS"
- .SS "General options"
- .sp
- All commands except clone accept these options\&.
- .PP
- \-\-git\-dir <dir>
- .RS 4
- Set the
- \fBGIT_DIR\fR
- environment variable\&. See
- \fBgit\fR(1)\&.
- .RE
- .PP
- \-v, \-\-verbose
- .RS 4
- Provide more progress information\&.
- .RE
- .SS "Sync options"
- .sp
- These options can be used in the initial \fIclone\fR as well as in subsequent \fIsync\fR operations\&.
- .PP
- \-\-branch <ref>
- .RS 4
- Import changes into <ref> instead of refs/remotes/p4/master\&. If <ref> starts with refs/, it is used as is\&. Otherwise, if it does not start with p4/, that prefix is added\&.
- .sp
- By default a <ref> not starting with refs/ is treated as the name of a remote\-tracking branch (under refs/remotes/)\&. This behavior can be modified using the \-\-import\-local option\&.
- .sp
- The default <ref> is "master"\&.
- .sp
- This example imports a new remote "p4/proj2" into an existing Git repository:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- $ git init
- $ git p4 sync \-\-branch=refs/remotes/p4/proj2 //depot/proj2
- .fi
- .if n \{\
- .RE
- .\}
- .RE
- .PP
- \-\-detect\-branches
- .RS 4
- Use the branch detection algorithm to find new paths in p4\&. It is documented below in "BRANCH DETECTION"\&.
- .RE
- .PP
- \-\-changesfile <file>
- .RS 4
- Import exactly the p4 change numbers listed in
- \fIfile\fR, one per line\&. Normally,
- \fIgit p4\fR
- inspects the current p4 repository state and detects the changes it should import\&.
- .RE
- .PP
- \-\-silent
- .RS 4
- Do not print any progress information\&.
- .RE
- .PP
- \-\-detect\-labels
- .RS 4
- Query p4 for labels associated with the depot paths, and add them as tags in Git\&. Limited usefulness as only imports labels associated with new changelists\&. Deprecated\&.
- .RE
- .PP
- \-\-import\-labels
- .RS 4
- Import labels from p4 into Git\&.
- .RE
- .PP
- \-\-import\-local
- .RS 4
- By default, p4 branches are stored in
- \fIrefs/remotes/p4/\fR, where they will be treated as remote\-tracking branches by
- \fBgit-branch\fR(1)
- and other commands\&. This option instead puts p4 branches in
- \fIrefs/heads/p4/\fR\&. Note that future sync operations must specify
- \fB\-\-import\-local\fR
- as well so that they can find the p4 branches in refs/heads\&.
- .RE
- .PP
- \-\-max\-changes <n>
- .RS 4
- Import at most
- \fIn\fR
- changes, rather than the entire range of changes included in the given revision specifier\&. A typical usage would be use
- \fI@all\fR
- as the revision specifier, but then to use
- \fI\-\-max\-changes 1000\fR
- to import only the last 1000 revisions rather than the entire revision history\&.
- .RE
- .PP
- \-\-changes\-block\-size <n>
- .RS 4
- The internal block size to use when converting a revision specifier such as
- \fI@all\fR
- into a list of specific change numbers\&. Instead of using a single call to
- \fIp4 changes\fR
- to find the full list of changes for the conversion, there are a sequence of calls to
- \fIp4 changes \-m\fR, each of which requests one block of changes of the given size\&. The default block size is 500, which should usually be suitable\&.
- .RE
- .PP
- \-\-keep\-path
- .RS 4
- The mapping of file names from the p4 depot path to Git, by default, involves removing the entire depot path\&. With this option, the full p4 depot path is retained in Git\&. For example, path
- \fI//depot/main/foo/bar\&.c\fR, when imported from
- \fI//depot/main/\fR, becomes
- \fIfoo/bar\&.c\fR\&. With
- \fB\-\-keep\-path\fR, the Git path is instead
- \fIdepot/main/foo/bar\&.c\fR\&.
- .RE
- .PP
- \-\-use\-client\-spec
- .RS 4
- Use a client spec to find the list of interesting files in p4\&. See the "CLIENT SPEC" section below\&.
- .RE
- .PP
- \-/ <path>
- .RS 4
- Exclude selected depot paths when cloning or syncing\&.
- .RE
- .SS "Clone options"
- .sp
- These options can be used in an initial \fIclone\fR, along with the \fIsync\fR options described above\&.
- .PP
- \-\-destination <directory>
- .RS 4
- Where to create the Git repository\&. If not provided, the last component in the p4 depot path is used to create a new directory\&.
- .RE
- .PP
- \-\-bare
- .RS 4
- Perform a bare clone\&. See
- \fBgit-clone\fR(1)\&.
- .RE
- .SS "Submit options"
- .sp
- These options can be used to modify \fIgit p4 submit\fR behavior\&.
- .PP
- \-\-origin <commit>
- .RS 4
- Upstream location from which commits are identified to submit to p4\&. By default, this is the most recent p4 commit reachable from
- \fBHEAD\fR\&.
- .RE
- .PP
- \-M
- .RS 4
- Detect renames\&. See
- \fBgit-diff\fR(1)\&. Renames will be represented in p4 using explicit
- \fImove\fR
- operations\&. There is no corresponding option to detect copies, but there are variables for both moves and copies\&.
- .RE
- .PP
- \-\-preserve\-user
- .RS 4
- Re\-author p4 changes before submitting to p4\&. This option requires p4 admin privileges\&.
- .RE
- .PP
- \-\-export\-labels
- .RS 4
- Export tags from Git as p4 labels\&. Tags found in Git are applied to the perforce working directory\&.
- .RE
- .PP
- \-n, \-\-dry\-run
- .RS 4
- Show just what commits would be submitted to p4; do not change state in Git or p4\&.
- .RE
- .PP
- \-\-prepare\-p4\-only
- .RS 4
- Apply a commit to the p4 workspace, opening, adding and deleting files in p4 as for a normal submit operation\&. Do not issue the final "p4 submit", but instead print a message about how to submit manually or revert\&. This option always stops after the first (oldest) commit\&. Git tags are not exported to p4\&.
- .RE
- .PP
- \-\-shelve
- .RS 4
- Instead of submitting create a series of shelved changelists\&. After creating each shelve, the relevant files are reverted/deleted\&. If you have multiple commits pending multiple shelves will be created\&.
- .RE
- .PP
- \-\-update\-shelve CHANGELIST
- .RS 4
- Update an existing shelved changelist with this commit\&. Implies \-\-shelve\&. Repeat for multiple shelved changelists\&.
- .RE
- .PP
- \-\-conflict=(ask|skip|quit)
- .RS 4
- Conflicts can occur when applying a commit to p4\&. When this happens, the default behavior ("ask") is to prompt whether to skip this commit and continue, or quit\&. This option can be used to bypass the prompt, causing conflicting commits to be automatically skipped, or to quit trying to apply commits, without prompting\&.
- .RE
- .PP
- \-\-branch <branch>
- .RS 4
- After submitting, sync this named branch instead of the default p4/master\&. See the "Sync options" section above for more information\&.
- .RE
- .PP
- \-\-commit (<sha1>|<sha1>\&.\&.<sha1>)
- .RS 4
- Submit only the specified commit or range of commits, instead of the full list of changes that are in the current Git branch\&.
- .RE
- .PP
- \-\-disable\-rebase
- .RS 4
- Disable the automatic rebase after all commits have been successfully submitted\&. Can also be set with git\-p4\&.disableRebase\&.
- .RE
- .PP
- \-\-disable\-p4sync
- .RS 4
- Disable the automatic sync of p4/master from Perforce after commits have been submitted\&. Implies \-\-disable\-rebase\&. Can also be set with git\-p4\&.disableP4Sync\&. Sync with origin/master still goes ahead if possible\&.
- .RE
- .SH "HOOKS FOR SUBMIT"
- .SS "p4\-pre\-submit"
- .sp
- The \fBp4\-pre\-submit\fR hook is executed if it exists and is executable\&. The hook takes no parameters and nothing from standard input\&. Exiting with non\-zero status from this script prevents \fBgit\-p4\fR \fBsubmit\fR from launching\&. It can be bypassed with the \fB\-\-no\-verify\fR command line option\&.
- .sp
- One usage scenario is to run unit tests in the hook\&.
- .SS "p4\-prepare\-changelist"
- .sp
- The \fBp4\-prepare\-changelist\fR hook is executed right after preparing the default changelist message and before the editor is started\&. It takes one parameter, the name of the file that contains the changelist text\&. Exiting with a non\-zero status from the script will abort the process\&.
- .sp
- The purpose of the hook is to edit the message file in place, and it is not suppressed by the \fB\-\-no\-verify\fR option\&. This hook is called even if \fB\-\-prepare\-p4\-only\fR is set\&.
- .SS "p4\-changelist"
- .sp
- The \fBp4\-changelist\fR hook is executed after the changelist message has been edited by the user\&. It can be bypassed with the \fB\-\-no\-verify\fR option\&. It takes a single parameter, the name of the file that holds the proposed changelist text\&. Exiting with a non\-zero status causes the command to abort\&.
- .sp
- The hook is allowed to edit the changelist file and can be used to normalize the text into some project standard format\&. It can also be used to refuse the Submit after inspect the message file\&.
- .SS "p4\-post\-changelist"
- .sp
- The \fBp4\-post\-changelist\fR hook is invoked after the submit has successfully occurred in P4\&. It takes no parameters and is meant primarily for notification and cannot affect the outcome of the git p4 submit action\&.
- .SS "Rebase options"
- .sp
- These options can be used to modify \fIgit p4 rebase\fR behavior\&.
- .PP
- \-\-import\-labels
- .RS 4
- Import p4 labels\&.
- .RE
- .SS "Unshelve options"
- .PP
- \-\-origin
- .RS 4
- Sets the git refspec against which the shelved P4 changelist is compared\&. Defaults to p4/master\&.
- .RE
- .SH "DEPOT PATH SYNTAX"
- .sp
- The p4 depot path argument to \fIgit p4 sync\fR and \fIgit p4 clone\fR can be one or more space\-separated p4 depot paths, with an optional p4 revision specifier on the end:
- .PP
- "//depot/my/project"
- .RS 4
- Import one commit with all files in the
- \fI#head\fR
- change under that tree\&.
- .RE
- .PP
- "//depot/my/project@all"
- .RS 4
- Import one commit for each change in the history of that depot path\&.
- .RE
- .PP
- "//depot/my/project@1,6"
- .RS 4
- Import only changes 1 through 6\&.
- .RE
- .PP
- "//depot/proj1@all //depot/proj2@all"
- .RS 4
- Import all changes from both named depot paths into a single repository\&. Only files below these directories are included\&. There is not a subdirectory in Git for each "proj1" and "proj2"\&. You must use the
- \fB\-\-destination\fR
- option when specifying more than one depot path\&. The revision specifier must be specified identically on each depot path\&. If there are files in the depot paths with the same name, the path with the most recently updated version of the file is the one that appears in Git\&.
- .RE
- .sp
- See \fIp4 help revisions\fR for the full syntax of p4 revision specifiers\&.
- .SH "CLIENT SPEC"
- .sp
- The p4 client specification is maintained with the \fIp4 client\fR command and contains among other fields, a View that specifies how the depot is mapped into the client repository\&. The \fIclone\fR and \fIsync\fR commands can consult the client spec when given the \fB\-\-use\-client\-spec\fR option or when the useClientSpec variable is true\&. After \fIgit p4 clone\fR, the useClientSpec variable is automatically set in the repository configuration file\&. This allows future \fIgit p4 submit\fR commands to work properly; the submit command looks only at the variable and does not have a command\-line option\&.
- .sp
- The full syntax for a p4 view is documented in \fIp4 help views\fR\&. \fIgit p4\fR knows only a subset of the view syntax\&. It understands multi\-line mappings, overlays with \fI+\fR, exclusions with \fI\-\fR and double\-quotes around whitespace\&. Of the possible wildcards, \fIgit p4\fR only handles \fI\&...\:\fR, and only when it is at the end of the path\&. \fIgit p4\fR will complain if it encounters an unhandled wildcard\&.
- .sp
- Bugs in the implementation of overlap mappings exist\&. If multiple depot paths map through overlays to the same location in the repository, \fIgit p4\fR can choose the wrong one\&. This is hard to solve without dedicating a client spec just for \fIgit p4\fR\&.
- .sp
- The name of the client can be given to \fIgit p4\fR in multiple ways\&. The variable \fIgit\-p4\&.client\fR takes precedence if it exists\&. Otherwise, normal p4 mechanisms of determining the client are used: environment variable \fBP4CLIENT\fR, a file referenced by \fBP4CONFIG\fR, or the local host name\&.
- .SH "BRANCH DETECTION"
- .sp
- P4 does not have the same concept of a branch as Git\&. Instead, p4 organizes its content as a directory tree, where by convention different logical branches are in different locations in the tree\&. The \fIp4 branch\fR command is used to maintain mappings between different areas in the tree, and indicate related content\&. \fIgit p4\fR can use these mappings to determine branch relationships\&.
- .sp
- If you have a repository where all the branches of interest exist as subdirectories of a single depot path, you can use \fB\-\-detect\-branches\fR when cloning or syncing to have \fIgit p4\fR automatically find subdirectories in p4, and to generate these as branches in Git\&.
- .sp
- For example, if the P4 repository structure is:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- //depot/main/\&.\&.\&.
- //depot/branch1/\&.\&.\&.
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- And "p4 branch \-o branch1" shows a View line that looks like:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- //depot/main/\&.\&.\&. //depot/branch1/\&.\&.\&.
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- Then this \fIgit p4 clone\fR command:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- git p4 clone \-\-detect\-branches //depot@all
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- produces a separate branch in \fIrefs/remotes/p4/\fR for //depot/main, called \fImaster\fR, and one for //depot/branch1 called \fIdepot/branch1\fR\&.
- .sp
- However, it is not necessary to create branches in p4 to be able to use them like branches\&. Because it is difficult to infer branch relationships automatically, a Git configuration setting \fIgit\-p4\&.branchList\fR can be used to explicitly identify branch relationships\&. It is a list of "source:destination" pairs, like a simple p4 branch specification, where the "source" and "destination" are the path elements in the p4 repository\&. The example above relied on the presence of the p4 branch\&. Without p4 branches, the same result will occur with:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- git init depot
- cd depot
- git config git\-p4\&.branchList main:branch1
- git p4 clone \-\-detect\-branches //depot@all \&.
- .fi
- .if n \{\
- .RE
- .\}
- .SH "PERFORMANCE"
- .sp
- The fast\-import mechanism used by \fIgit p4\fR creates one pack file for each invocation of \fIgit p4 sync\fR\&. Normally, Git garbage compression (\fBgit-gc\fR(1)) automatically compresses these to fewer pack files, but explicit invocation of \fIgit repack \-adf\fR may improve performance\&.
- .SH "CONFIGURATION VARIABLES"
- .sp
- The following config settings can be used to modify \fIgit p4\fR behavior\&. They all are in the \fIgit\-p4\fR section\&.
- .SS "General variables"
- .PP
- git\-p4\&.user
- .RS 4
- User specified as an option to all p4 commands, with
- \fI\-u <user>\fR\&. The environment variable
- \fBP4USER\fR
- can be used instead\&.
- .RE
- .PP
- git\-p4\&.password
- .RS 4
- Password specified as an option to all p4 commands, with
- \fI\-P <password>\fR\&. The environment variable
- \fBP4PASS\fR
- can be used instead\&.
- .RE
- .PP
- git\-p4\&.port
- .RS 4
- Port specified as an option to all p4 commands, with
- \fI\-p <port>\fR\&. The environment variable
- \fBP4PORT\fR
- can be used instead\&.
- .RE
- .PP
- git\-p4\&.host
- .RS 4
- Host specified as an option to all p4 commands, with
- \fI\-h <host>\fR\&. The environment variable
- \fBP4HOST\fR
- can be used instead\&.
- .RE
- .PP
- git\-p4\&.client
- .RS 4
- Client specified as an option to all p4 commands, with
- \fI\-c <client>\fR, including the client spec\&.
- .RE
- .PP
- git\-p4\&.retries
- .RS 4
- Specifies the number of times to retry a p4 command (notably,
- \fIp4 sync\fR) if the network times out\&. The default value is 3\&. Set the value to 0 to disable retries or if your p4 version does not support retries (pre 2012\&.2)\&.
- .RE
- .SS "Clone and sync variables"
- .PP
- git\-p4\&.syncFromOrigin
- .RS 4
- Because importing commits from other Git repositories is much faster than importing them from p4, a mechanism exists to find p4 changes first in Git remotes\&. If branches exist under
- \fIrefs/remote/origin/p4\fR, those will be fetched and used when syncing from p4\&. This variable can be set to
- \fIfalse\fR
- to disable this behavior\&.
- .RE
- .PP
- git\-p4\&.branchUser
- .RS 4
- One phase in branch detection involves looking at p4 branches to find new ones to import\&. By default, all branches are inspected\&. This option limits the search to just those owned by the single user named in the variable\&.
- .RE
- .PP
- git\-p4\&.branchList
- .RS 4
- List of branches to be imported when branch detection is enabled\&. Each entry should be a pair of branch names separated by a colon (:)\&. This example declares that both branchA and branchB were created from main:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- git config git\-p4\&.branchList main:branchA
- git config \-\-add git\-p4\&.branchList main:branchB
- .fi
- .if n \{\
- .RE
- .\}
- .RE
- .PP
- git\-p4\&.ignoredP4Labels
- .RS 4
- List of p4 labels to ignore\&. This is built automatically as unimportable labels are discovered\&.
- .RE
- .PP
- git\-p4\&.importLabels
- .RS 4
- Import p4 labels into git, as per \-\-import\-labels\&.
- .RE
- .PP
- git\-p4\&.labelImportRegexp
- .RS 4
- Only p4 labels matching this regular expression will be imported\&. The default value is
- \fI[a\-zA\-Z0\-9_\e\-\&.]+$\fR\&.
- .RE
- .PP
- git\-p4\&.useClientSpec
- .RS 4
- Specify that the p4 client spec should be used to identify p4 depot paths of interest\&. This is equivalent to specifying the option
- \fB\-\-use\-client\-spec\fR\&. See the "CLIENT SPEC" section above\&. This variable is a boolean, not the name of a p4 client\&.
- .RE
- .PP
- git\-p4\&.pathEncoding
- .RS 4
- Perforce keeps the encoding of a path as given by the originating OS\&. Git expects paths encoded as UTF\-8\&. Use this config to tell git\-p4 what encoding Perforce had used for the paths\&. This encoding is used to transcode the paths to UTF\-8\&. As an example, Perforce on Windows often uses "cp1252" to encode path names\&. If this option is passed into a p4 clone request, it is persisted in the resulting new git repo\&.
- .RE
- .PP
- git\-p4\&.metadataDecodingStrategy
- .RS 4
- Perforce keeps the encoding of a changelist descriptions and user full names as stored by the client on a given OS\&. The p4v client uses the OS\-local encoding, and so different users can end up storing different changelist descriptions or user full names in different encodings, in the same depot\&. Git tolerates inconsistent/incorrect encodings in commit messages and author names, but expects them to be specified in utf\-8\&. git\-p4 can use three different decoding strategies in handling the encoding uncertainty in Perforce:
- \fIpassthrough\fR
- simply passes the original bytes through from Perforce to git, creating usable but incorrectly\-encoded data when the Perforce data is encoded as anything other than utf\-8\&.
- \fIstrict\fR
- expects the Perforce data to be encoded as utf\-8, and fails to import when this is not true\&.
- \fIfallback\fR
- attempts to interpret the data as utf\-8, and otherwise falls back to using a secondary encoding \- by default the common windows encoding
- \fIcp\-1252\fR
- \- with upper\-range bytes escaped if decoding with the fallback encoding also fails\&. Under python2 the default strategy is
- \fIpassthrough\fR
- for historical reasons, and under python3 the default is
- \fIfallback\fR\&. When
- \fIstrict\fR
- is selected and decoding fails, the error message will propose changing this config parameter as a workaround\&. If this option is passed into a p4 clone request, it is persisted into the resulting new git repo\&.
- .RE
- .PP
- git\-p4\&.metadataFallbackEncoding
- .RS 4
- Specify the fallback encoding to use when decoding Perforce author names and changelists descriptions using the
- \fIfallback\fR
- strategy (see git\-p4\&.metadataDecodingStrategy)\&. The fallback encoding will only be used when decoding as utf\-8 fails\&. This option defaults to cp1252, a common windows encoding\&. If this option is passed into a p4 clone request, it is persisted into the resulting new git repo\&.
- .RE
- .PP
- git\-p4\&.largeFileSystem
- .RS 4
- Specify the system that is used for large (binary) files\&. Please note that large file systems do not support the
- \fIgit p4 submit\fR
- command\&. Only Git LFS is implemented right now (see
- \m[blue]\fBhttps://git\-lfs\&.github\&.com/\fR\m[]
- for more information)\&. Download and install the Git LFS command line extension to use this option and configure it like this:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- git config git\-p4\&.largeFileSystem GitLFS
- .fi
- .if n \{\
- .RE
- .\}
- .RE
- .PP
- git\-p4\&.largeFileExtensions
- .RS 4
- All files matching a file extension in the list will be processed by the large file system\&. Do not prefix the extensions with
- \fI\&.\fR\&.
- .RE
- .PP
- git\-p4\&.largeFileThreshold
- .RS 4
- All files with an uncompressed size exceeding the threshold will be processed by the large file system\&. By default the threshold is defined in bytes\&. Add the suffix k, m, or g to change the unit\&.
- .RE
- .PP
- git\-p4\&.largeFileCompressedThreshold
- .RS 4
- All files with a compressed size exceeding the threshold will be processed by the large file system\&. This option might slow down your clone/sync process\&. By default the threshold is defined in bytes\&. Add the suffix k, m, or g to change the unit\&.
- .RE
- .PP
- git\-p4\&.largeFilePush
- .RS 4
- Boolean variable which defines if large files are automatically pushed to a server\&.
- .RE
- .PP
- git\-p4\&.keepEmptyCommits
- .RS 4
- A changelist that contains only excluded files will be imported as an empty commit if this boolean option is set to true\&.
- .RE
- .PP
- git\-p4\&.mapUser
- .RS 4
- Map a P4 user to a name and email address in Git\&. Use a string with the following format to create a mapping:
- .sp
- .if n \{\
- .RS 4
- .\}
- .nf
- git config \-\-add git\-p4\&.mapUser "p4user = First Last <mail@address\&.com>"
- .fi
- .if n \{\
- .RE
- .\}
- .sp
- A mapping will override any user information from P4\&. Mappings for multiple P4 user can be defined\&.
- .RE
- .SS "Submit variables"
- .PP
- git\-p4\&.detectRenames
- .RS 4
- Detect renames\&. See
- \fBgit-diff\fR(1)\&. This can be true, false, or a score as expected by
- \fIgit diff \-M\fR\&.
- .RE
- .PP
- git\-p4\&.detectCopies
- .RS 4
- Detect copies\&. See
- \fBgit-diff\fR(1)\&. This can be true, false, or a score as expected by
- \fIgit diff \-C\fR\&.
- .RE
- .PP
- git\-p4\&.detectCopiesHarder
- .RS 4
- Detect copies harder\&. See
- \fBgit-diff\fR(1)\&. A boolean\&.
- .RE
- .PP
- git\-p4\&.preserveUser
- .RS 4
- On submit, re\-author changes to reflect the Git author, regardless of who invokes
- \fIgit p4 submit\fR\&.
- .RE
- .PP
- git\-p4\&.allowMissingP4Users
- .RS 4
- When
- \fIpreserveUser\fR
- is true,
- \fIgit p4\fR
- normally dies if it cannot find an author in the p4 user map\&. This setting submits the change regardless\&.
- .RE
- .PP
- git\-p4\&.skipSubmitEdit
- .RS 4
- The submit process invokes the editor before each p4 change is submitted\&. If this setting is true, though, the editing step is skipped\&.
- .RE
- .PP
- git\-p4\&.skipSubmitEditCheck
- .RS 4
- After editing the p4 change message,
- \fIgit p4\fR
- makes sure that the description really was changed by looking at the file modification time\&. This option disables that test\&.
- .RE
- .PP
- git\-p4\&.allowSubmit
- .RS 4
- By default, any branch can be used as the source for a
- \fIgit p4 submit\fR
- operation\&. This configuration variable, if set, permits only the named branches to be used as submit sources\&. Branch names must be the short names (no "refs/heads/"), and should be separated by commas (","), with no spaces\&.
- .RE
- .PP
- git\-p4\&.skipUserNameCheck
- .RS 4
- If the user running
- \fIgit p4 submit\fR
- does not exist in the p4 user map,
- \fIgit p4\fR
- exits\&. This option can be used to force submission regardless\&.
- .RE
- .PP
- git\-p4\&.attemptRCSCleanup
- .RS 4
- If enabled,
- \fIgit p4 submit\fR
- will attempt to cleanup RCS keywords ($Header$, etc)\&. These would otherwise cause merge conflicts and prevent the submit going ahead\&. This option should be considered experimental at present\&.
- .RE
- .PP
- git\-p4\&.exportLabels
- .RS 4
- Export Git tags to p4 labels, as per \-\-export\-labels\&.
- .RE
- .PP
- git\-p4\&.labelExportRegexp
- .RS 4
- Only p4 labels matching this regular expression will be exported\&. The default value is
- \fI[a\-zA\-Z0\-9_\e\-\&.]+$\fR\&.
- .RE
- .PP
- git\-p4\&.conflict
- .RS 4
- Specify submit behavior when a conflict with p4 is found, as per \-\-conflict\&. The default behavior is
- \fIask\fR\&.
- .RE
- .PP
- git\-p4\&.disableRebase
- .RS 4
- Do not rebase the tree against p4/master following a submit\&.
- .RE
- .PP
- git\-p4\&.disableP4Sync
- .RS 4
- Do not sync p4/master with Perforce following a submit\&. Implies git\-p4\&.disableRebase\&.
- .RE
- .SH "IMPLEMENTATION DETAILS"
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Changesets from p4 are imported using Git fast\-import\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Cloning or syncing does not require a p4 client; file contents are collected using
- \fIp4 print\fR\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Submitting requires a p4 client, which is not in the same location as the Git repository\&. Patches are applied, one at a time, to this p4 client and submitted from there\&.
- .RE
- .sp
- .RS 4
- .ie n \{\
- \h'-04'\(bu\h'+03'\c
- .\}
- .el \{\
- .sp -1
- .IP \(bu 2.3
- .\}
- Each commit imported by
- \fIgit p4\fR
- has a line at the end of the log message indicating the p4 depot location and change number\&. This line is used by later
- \fIgit p4 sync\fR
- operations to know which p4 changes are new\&.
- .RE
- .SH "GIT"
- .sp
- Part of the \fBgit\fR(1) suite