Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GIT-P4(1)			  Git Manual			     GIT-P4(1)

       git-p4 -	Import from and	submit to Perforce repositories

       git p4 clone [<sync options>] [<clone options>] <p4 depot path>...
       git p4 sync [<sync options>] [<p4 depot path>...]
       git p4 rebase
       git p4 submit [<submit options>]	[<master branch	name>]

       This command provides a way to interact with p4 repositories using Git.

       Create a	new Git	repository from	an existing p4 repository using	git p4
       clone, giving it	one or more p4 depot paths. Incorporate	new commits
       from p4 changes with git	p4 sync. The sync command is also used to
       include new branches from other p4 depot	paths. Submit Git changes back
       to p4 using git p4 submit. The command git p4 rebase does a sync	plus
       rebases the current branch onto the updated p4 remote branch.

       o   Clone a repository:

	       $ git p4	clone //depot/path/project

       o   Do some work	in the newly created Git repository:

	       $ cd project
	       $ vi foo.h
	       $ git commit -a -m "edited foo.h"

       o   Update the Git repository with recent changes from p4, rebasing
	   your	work on	top:

	       $ git p4	rebase

       o   Submit your commits back to p4:

	       $ git p4	submit

       Generally, git p4 clone is used to create a new Git directory from an
       existing	p4 repository:

	   $ git p4 clone //depot/path/project


	1. Creates an empty Git	repository in a	subdirectory called project.

	2. Imports the full contents of	the head revision from the given p4
	   depot path into a single commit in the Git branch

	3. Creates a local branch, master from this remote and checks it out.

       To reproduce the	entire p4 history in Git, use the @all modifier	on the
       depot path:

	   $ git p4 clone //depot/path/project@all

       As development continues	in the p4 repository, those changes can	be
       included	in the Git repository using:

	   $ git p4 sync

       This command finds new changes in p4 and	imports	them as	Git commits.

       P4 repositories can be added to an existing Git repository using	git p4
       sync too:

	   $ mkdir repo-git
	   $ cd	repo-git
	   $ git init
	   $ git p4 sync //path/in/your/perforce/depot

       This imports the	specified depot	into refs/remotes/p4/master in an
       existing	Git repository.	The --branch option can	be used	to specify a
       different branch	to be used for the p4 content.

       If a Git	repository includes branches refs/remotes/origin/p4, these
       will be fetched and consulted first during a git	p4 sync. Since
       importing directly from p4 is considerably slower than pulling changes
       from a Git remote, this can be useful in	a multi-developer environment.

       If there	are multiple branches, doing git p4 sync will automatically
       use the "BRANCH DETECTION" algorithm to try to partition	new changes
       into the	right branch. This can be overridden with the --branch option
       to specify just a single	branch to update.

       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 git p4 sync followed by git
       rebase to move local commits on top of updated p4 changes.

	   $ git p4 rebase

       Submitting changes from a Git repository	back to	the p4 repository
       requires	a separate p4 client workspace.	This should be specified using
       the P4CLIENT environment	variable or the	Git configuration variable
       git-p4.client. The p4 client must exist,	but the	client root will be
       created and populated if	it does	not already exist.

       To submit all changes that are in the current Git branch	but not	in the
       p4/master branch, use:

	   $ git p4 submit

       To specify a branch other than the current one, use:

	   $ git p4 submit topicbranch

       To specify a single commit or a range of	commits, use:

	   $ git p4 submit --commit <sha1>
	   $ git p4 submit --commit <sha1..sha1>

       The upstream reference is generally refs/remotes/p4/master, but can be
       overridden using	the --origin= command-line option.

       The p4 changes will be created as the user invoking git p4 submit. The
       --preserve-user 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 p4 protect.

       To shelve changes instead of submitting,	use --shelve and

	   $ git p4 submit --shelve
	   $ git p4 submit --update-shelve 1234	--update-shelve	2345

       Unshelving will take a shelved P4 changelist, and produce the
       equivalent git commit in	the branch

       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.

       The origin revision can be changed with the "--origin" option.

       If the target branch in refs/remotes/p4-unshelved already exists, the
       old one will be renamed.

	   $ 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>

   General options
       All commands except clone accept	these options.

       --git-dir <dir>
	   Set the GIT_DIR environment variable. See git(1).

       -v, --verbose
	   Provide more	progress information.

   Sync	options
       These options can be used in the	initial	clone as well as in subsequent
       sync operations.

       --branch	<ref>
	   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.

	   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.

	   The default <ref> is	"master".

	   This	example	imports	a new remote "p4/proj2"	into an	existing Git

		   $ git init
		   $ git p4 sync --branch=refs/remotes/p4/proj2	//depot/proj2

	   Use the branch detection algorithm to find new paths	in p4. It is
	   documented below in "BRANCH DETECTION".

       --changesfile <file>
	   Import exactly the p4 change	numbers	listed in file,	one per	line.
	   Normally, git p4 inspects the current p4 repository state and
	   detects the changes it should import.

	   Do not print	any progress information.

	   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.

	   Import labels from p4 into Git.

	   By default, p4 branches are stored in refs/remotes/p4/, where they
	   will	be treated as remote-tracking branches by git-branch(1)	and
	   other commands. This	option instead puts p4 branches	in
	   refs/heads/p4/. Note	that future sync operations must specify
	   --import-local as well so that they can find	the p4 branches	in

       --max-changes <n>
	   Import at most n changes, rather than the entire range of changes
	   included in the given revision specifier. A typical usage would be
	   use @all as the revision specifier, but then	to use --max-changes
	   1000	to import only the last	1000 revisions rather than the entire
	   revision history.

       --changes-block-size <n>
	   The internal	block size to use when converting a revision specifier
	   such	as @all	into a list of specific	change numbers.	Instead	of
	   using a single call to p4 changes to	find the full list of changes
	   for the conversion, there are a sequence of calls to	p4 changes -m,
	   each	of which requests one block of changes of the given size. The
	   default block size is 500, which should usually be suitable.

	   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
	   //depot/main/foo/bar.c, when	imported from //depot/main/, becomes
	   foo/bar.c. With --keep-path,	the Git	path is	instead

	   Use a client	spec to	find the list of interesting files in p4. See
	   the "CLIENT SPEC" section below.

       -/ <path>
	   Exclude selected depot paths	when cloning or	syncing.

   Clone options
       These options can be used in an initial clone, along with the sync
       options described above.

       --destination <directory>
	   Where to create the Git repository. If not provided,	the last
	   component in	the p4 depot path is used to create a new directory.

	   Perform a bare clone. See git-clone(1).

   Submit options
       These options can be used to modify git p4 submit behavior.

       --origin	<commit>
	   Upstream location from which	commits	are identified to submit to
	   p4. By default, this	is the most recent p4 commit reachable from

	   Detect renames. See git-diff(1). Renames will be represented	in p4
	   using explicit move operations. There is no corresponding option to
	   detect copies, but there are	variables for both moves and copies.

	   Re-author p4	changes	before submitting to p4. This option requires
	   p4 admin privileges.

	   Export tags from Git	as p4 labels. Tags found in Git	are applied to
	   the perforce	working	directory.

       -n, --dry-run
	   Show	just what commits would	be submitted to	p4; do not change
	   state in Git	or p4.

	   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.

	   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.

       --update-shelve CHANGELIST
	   Update an existing shelved changelist with this commit. Implies
	   --shelve. Repeat for	multiple shelved changelists.

	   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.

       --branch	<branch>
	   After submitting, sync this named branch instead of the default
	   p4/master. See the "Sync options" section above for more

       --commit	<sha1>|<sha1..sha1>
	   Submit only the specified commit or range of	commits, instead of
	   the full list of changes that are in	the current Git	branch.

	   Disable the automatic rebase	after all commits have been
	   successfully	submitted. Can also be set with	git-p4.disableRebase.

	   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

       The p4-pre-submit 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 git-p4	submit from launching.
       It can be bypassed with the --no-verify command line option.

       One usage scenario is to	run unit tests in the hook.

       The p4-prepare-changelist 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.

       The purpose of the hook is to edit the message file in place, and it is
       not supressed by	the --no-verify	option.	This hook is called even if
       --prepare-p4-only is set.

       The p4-changelist hook is executed after	the changelist message has
       been edited by the user.	It can be bypassed with	the --no-verify
       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.

       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.

       The p4-post-changelist hook is invoked after the	submit has
       successfully occured in P4. It takes no parameters and is meant
       primarily for notification and cannot affect the	outcome	of the git p4
       submit action.

   Rebase options
       These options can be used to modify git p4 rebase behavior.

	   Import p4 labels.

   Unshelve options
	   Sets	the git	refspec	against	which the shelved P4 changelist	is
	   compared. Defaults to p4/master.

       The p4 depot path argument to git p4 sync and git p4 clone can be one
       or more space-separated p4 depot	paths, with an optional	p4 revision
       specifier on the	end:

	   Import one commit with all files in the #head change	under that

	   Import one commit for each change in	the history of that depot

	   Import only changes 1 through 6.

       "//depot/proj1@all //depot/proj2@all"
	   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 --destination 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.

       See p4 help revisions for the full syntax of p4 revision	specifiers.

       The p4 client specification is maintained with the p4 client command
       and contains among other	fields,	a View that specifies how the depot is
       mapped into the client repository. The clone and	sync commands can
       consult the client spec when given the --use-client-spec	option or when
       the useClientSpec variable is true. After git p4	clone, the
       useClientSpec variable is automatically set in the repository
       configuration file. This	allows future git p4 submit commands to	work
       properly; the submit command looks only at the variable and does	not
       have a command-line option.

       The full	syntax for a p4	view is	documented in p4 help views. git p4
       knows only a subset of the view syntax. It understands multi-line
       mappings, overlays with +, exclusions with - and	double-quotes around
       whitespace. Of the possible wildcards, git p4 only handles ..., and
       only when it is at the end of the path. git p4 will complain if it
       encounters an unhandled wildcard.

       Bugs in the implementation of overlap mappings exist. If	multiple depot
       paths map through overlays to the same location in the repository, git
       p4 can choose the wrong one. This is hard to solve without dedicating a
       client spec just	for git	p4.

       The name	of the client can be given to git p4 in	multiple ways. The
       variable	git-p4.client takes precedence if it exists. Otherwise,	normal
       p4 mechanisms of	determining the	client are used: environment variable
       P4CLIENT, a file	referenced by P4CONFIG,	or the local host name.

       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
       p4 branch command is used to maintain mappings between different	areas
       in the tree, and	indicate related content. git p4 can use these
       mappings	to determine branch relationships.

       If you have a repository	where all the branches of interest exist as
       subdirectories of a single depot	path, you can use --detect-branches
       when cloning or syncing to have git p4 automatically find
       subdirectories in p4, and to generate these as branches in Git.

       For example, if the P4 repository structure is:


       And "p4 branch -o branch1" shows	a View line that looks like:

	   //depot/main/... //depot/branch1/...

       Then this git p4	clone command:

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

       produces	a separate branch in refs/remotes/p4/ for //depot/main,	called
       master, and one for //depot/branch1 called depot/branch1.

       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
       git-p4.branchList 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:

	   git init depot
	   cd depot
	   git config git-p4.branchList	main:branch1
	   git p4 clone	--detect-branches //depot@all .

       The fast-import mechanism used by git p4	creates	one pack file for each
       invocation of git p4 sync. Normally, Git	garbage	compression (git-
       gc(1)) automatically compresses these to	fewer pack files, but explicit
       invocation of git repack	-adf may improve performance.

       The following config settings can be used to modify git p4 behavior.
       They all	are in the git-p4 section.

   General variables
	   User	specified as an	option to all p4 commands, with	-u _user_. The
	   environment variable	P4USER can be used instead.

	   Password specified as an option to all p4 commands, with -P
	   _password_. The environment variable	P4PASS can be used instead.

	   Port	specified as an	option to all p4 commands, with	-p _port_. The
	   environment variable	P4PORT can be used instead.
	   Host	specified as an	option to all p4 commands, with	-h _host_. The
	   environment variable	P4HOST can be used instead.

	   Client specified as an option to all	p4 commands, with -c _client_,
	   including the client	spec.

	   Specifies the number	of times to retry a p4 command (notably, p4
	   sync) 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).

   Clone and sync variables
	   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
	   refs/remote/origin/p4, those	will be	fetched	and used when syncing
	   from	p4. This variable can be set to	false to disable this

	   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.

	   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:

	       git config	git-p4.branchList main:branchA
	       git config --add	git-p4.branchList main:branchB

	   List	of p4 labels to	ignore.	This is	built automatically as
	   unimportable	labels are discovered.

	   Import p4 labels into git, as per --import-labels.

	   Only	p4 labels matching this	regular	expression will	be imported.
	   The default value is	[a-zA-Z0-9_\-.]+$.

	   Specify that	the p4 client spec should be used to identify p4 depot
	   paths of interest. This is equivalent to specifying the option
	   --use-client-spec. See the "CLIENT SPEC" section above. This
	   variable is a boolean, not the name of a p4 client.

	   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.

	   Specify the system that is used for large (binary) files. Please
	   note	that large file	systems	do not support the git p4 submit
	   command. Only Git LFS is implemented	right now (see for more	information). Download and
	   install the Git LFS command line extension to use this option and
	   configure it	like this:

	       git config	git-p4.largeFileSystem GitLFS

	   All files matching a	file extension in the list will	be processed
	   by the large	file system. Do	not prefix the extensions with ..

	   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.

	   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.

	   Boolean variable which defines if large files are automatically
	   pushed to a server.

	   A changelist	that contains only excluded files will be imported as
	   an empty commit if this boolean option is set to true.

	   Map a P4 user to a name and email address in	Git. Use a string with
	   the following format	to create a mapping:

	       git config --add	git-p4.mapUser "p4user = First Last <>"

	   A mapping will override any user information	from P4. Mappings for
	   multiple P4 user can	be defined.

   Submit variables
	   Detect renames. See git-diff(1). This can be	true, false, or	a
	   score as expected by	git diff -M.

	   Detect copies. See git-diff(1). This	can be true, false, or a score
	   as expected by git diff -C.

	   Detect copies harder. See git-diff(1). A boolean.

	   On submit, re-author	changes	to reflect the Git author, regardless
	   of who invokes git p4 submit.

	   When	preserveUser is	true, git p4 normally dies if it cannot	find
	   an author in	the p4 user map. This setting submits the change

	   The submit process invokes the editor before	each p4	change is
	   submitted. If this setting is true, though, the editing step	is

	   After editing the p4	change message,	git p4 makes sure that the
	   description really was changed by looking at	the file modification
	   time. This option disables that test.

	   By default, any branch can be used as the source for	a git p4
	   submit 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.

	   If the user running git p4 submit does not exist in the p4 user
	   map,	git p4 exits. This option can be used to force submission

	   If enabled, git p4 submit 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.

	   Export Git tags to p4 labels, as per	--export-labels.

	   Only	p4 labels matching this	regular	expression will	be exported.
	   The default value is	[a-zA-Z0-9_\-.]+$.

	   Specify submit behavior when	a conflict with	p4 is found, as	per
	   --conflict. The default behavior is ask.

	   Do not rebase the tree against p4/master following a	submit.

	   Do not sync p4/master with Perforce following a submit. Implies

       o   Changesets from p4 are imported using Git fast-import.

       o   Cloning or syncing does not require a p4 client; file contents are
	   collected using p4 print.

       o   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.

       o   Each	commit imported	by git p4 has a	line at	the end	of the log
	   message indicating the p4 depot location and	change number. This
	   line	is used	by later git p4	sync operations	to know	which p4
	   changes are new.

Git 2.28.0			  07/26/2020			     GIT-P4(1)


Want to link to this manual page? Use this URL:

home | help