man pages section 1: User Commands

Exit Print View

Updated: July 2014

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


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

     o   Create an alias for git p4, using the full path to the
         git-p4 script if needed:

             $ git config --global alias.p4 '!git-p4'

     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

Git          Last change: 02/22/2012                    1

Git Manual                                              GIT-P4(1)

     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

      2. Imports the full contents of the head revision from the
         given p4 depot path into a single commit in the git
         branch refs/remotes/p4/master.

      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

     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

     If a git repository includes branches
     refs/remotes/origin/p4, these will be fetched and consulted

Git          Last change: 02/22/2012                    2

Git Manual                                              GIT-P4(1)

     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.

     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

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

     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.

  General options
     All commands except clone accept this option.

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

Git          Last change: 02/22/2012                    3

Git Manual                                              GIT-P4(1)

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

     --branch <branch>
         Import changes into given branch. If the branch starts
         with refs/, it will be used as is, otherwise the path
         refs/heads/ will be prepended. The default branch is
         master. If used with an initial clone, no HEAD will be
         checked out.

         This example imports a new remote "p4/proj2" into an
         existing git repository:

             $ 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

         Do not print any progress information.

         Provide more progress information.

         Query p4 for labels associated with the depot paths, and
         add them as tags in 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 refs/heads.

     --max-changes <n>
         Limit the number of imported changes to n. Useful to
         limit the amount of history when using the @all p4
         revision specifier.

Git          Last change: 02/22/2012                    4

Git Manual                                              GIT-P4(1)

         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.

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

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

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

         Provide more progress information.

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

         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.

     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

Git          Last change: 02/22/2012                    5

Git Manual                                              GIT-P4(1)

     optional p4 revision specifier on the end:

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

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

         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

     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. Git-p4 can consult the client spec when given
     the --use-client-spec option or useClientSpec variable.

     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.

     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

Git          Last change: 02/22/2012                    6

Git Manual                                              GIT-P4(1)

     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

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

Git          Last change: 02/22/2012                    7

Git Manual                                              GIT-P4(1)

     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

         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
         Host specified as an option to all p4 commands, with -h
         <host>. The environment variable P4HOST can be used

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

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

         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

         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          Last change: 02/22/2012                    8

Git Manual                                              GIT-P4(1)

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

         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.

  Submit variables
         Detect renames. See git-diff(1).

         Detect copies. See git-diff(1).

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

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

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

         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

         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

Git          Last change: 02/22/2012                    9

Git Manual                                              GIT-P4(1)

         force submission regardless.

     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.

     See attributes(5) for descriptions of the following

     |Availability   | developer/versioning/git |
     |Stability      | Uncommitted              |
     This software was built from source available at  The original
     community source was downloaded from  http://git-

     Further information about this software can be found on the
     open source community website at

Git          Last change: 02/22/2012                   10