path: root/man1/git-p4.1

'\" t
.\"     Title: git-p4
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2024-04-12
.\"    Manual: Git Manual
.\"    Source: Git 2.44.0.591.g8f7582d995
.\"  Language: English
.\"
.TH "GIT\-P4" "1" "2024\-04\-12" "Git 2\&.44\&.0\&.591\&.g8f7582" "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
.sp
.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
.\}
.sp
.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
.\}
.sp
.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
.\}
.sp
.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
.\}
.sp
.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
.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
.\}
.sp
.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
.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
.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
.\}
.sp
.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
.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
.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
.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
.\}
.sp
.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
.\}
.sp
.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
.\}
.sp
.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 submit\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
.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
.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
.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
.\}
.sp
.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
.\}
.sp
.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
.\}
.sp
.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