1GIT-P4(1) Git Manual GIT-P4(1)
2
6 git-p4 - Import from and submit to Perforce repositories
7
9 git p4 clone [<sync-options>] [<clone-options>] <p4-depot-path>...
10 git p4 sync [<sync-options>] [<p4-depot-path>...]
11 git p4 rebase
12 git p4 submit [<submit-options>] [<master-branch-name>]
13
15 This command provides a way to interact with p4 repositories using Git.
16 Create a new Git repository from an existing p4 repository using git p4
18 clone, giving it one or more p4 depot paths. Incorporate new commits
19 from p4 changes with git p4 sync. The sync command is also used to
20 include new branches from other p4 depot paths. Submit Git changes back
21 to p4 using git p4 submit. The command git p4 rebase does a sync plus
22 rebases the current branch onto the updated p4 remote branch.
23
25 • Clone a repository:
26 $ git p4 clone //depot/path/project
28 • Do some work in the newly created Git repository:
30 $ cd project
32 $ vi foo.h
33 $ git commit -a -m "edited foo.h"
34 • Update the Git repository with recent changes from p4, rebasing
36 your work on top:
37 $ git p4 rebase
39 • Submit your commits back to p4:
41 $ git p4 submit
43
45 Clone
46 Generally, git p4 clone is used to create a new Git directory from an
47 existing p4 repository:
48 $ git p4 clone //depot/path/project
50 This:
52 1. Creates an empty Git repository in a subdirectory called project.
54 2. Imports the full contents of the head revision from the given p4
56 depot path into a single commit in the Git branch
57 refs/remotes/p4/master.
58 3. Creates a local branch, master from this remote and checks it out.
60 To reproduce the entire p4 history in Git, use the @all modifier on the
62 depot path:
63 $ git p4 clone //depot/path/project@all
65 Sync
67 As development continues in the p4 repository, those changes can be
68 included in the Git repository using:
69 $ git p4 sync
71 This command finds new changes in p4 and imports them as Git commits.
73 P4 repositories can be added to an existing Git repository using git p4
75 sync too:
76 $ mkdir repo-git
78 $ cd repo-git
79 $ git init
80 $ git p4 sync //path/in/your/perforce/depot
81 This imports the specified depot into refs/remotes/p4/master in an
83 existing Git repository. The --branch option can be used to specify a
84 different branch to be used for the p4 content.
85 If a Git repository includes branches refs/remotes/origin/p4, these
87 will be fetched and consulted first during a git p4 sync. Since
88 importing directly from p4 is considerably slower than pulling changes
89 from a Git remote, this can be useful in a multi-developer environment.
90 If there are multiple branches, doing git p4 sync will automatically
92 use the "BRANCH DETECTION" algorithm to try to partition new changes
93 into the right branch. This can be overridden with the --branch option
94 to specify just a single branch to update.
95 Rebase
97 A common working pattern is to fetch the latest changes from the p4
98 depot and merge them with local uncommitted changes. Often, the p4
99 repository is the ultimate location for all code, thus a rebase
100 workflow makes sense. This command does git p4 sync followed by git
101 rebase to move local commits on top of updated p4 changes.
102 $ git p4 rebase
104 Submit
106 Submitting changes from a Git repository back to the p4 repository
107 requires a separate p4 client workspace. This should be specified using
108 the P4CLIENT environment variable or the Git configuration variable
109 git-p4.client. The p4 client must exist, but the client root will be
110 created and populated if it does not already exist.
111 To submit all changes that are in the current Git branch but not in the
113 p4/master branch, use:
114 $ git p4 submit
116 To specify a branch other than the current one, use:
118 $ git p4 submit topicbranch
120 To specify a single commit or a range of commits, use:
122 $ git p4 submit --commit <sha1>
124 $ git p4 submit --commit <sha1..sha1>
125 The upstream reference is generally refs/remotes/p4/master, but can be
127 overridden using the --origin= command-line option.
128 The p4 changes will be created as the user invoking git p4 submit. The
130 --preserve-user option will cause ownership to be modified according to
131 the author of the Git commit. This option requires admin privileges in
132 p4, which can be granted using p4 protect.
133 To shelve changes instead of submitting, use --shelve and
135 --update-shelve:
136 $ git p4 submit --shelve
138 $ git p4 submit --update-shelve 1234 --update-shelve 2345
139 Unshelve
141 Unshelving will take a shelved P4 changelist, and produce the
142 equivalent git commit in the branch
143 refs/remotes/p4-unshelved/<changelist>.
144 The git commit is created relative to the current origin revision (HEAD
146 by default). A parent commit is created based on the origin, and then
147 the unshelve commit is created based on that.
148 The origin revision can be changed with the "--origin" option.
150 If the target branch in refs/remotes/p4-unshelved already exists, the
152 old one will be renamed.
153 $ git p4 sync
155 $ git p4 unshelve 12345
156 $ git show p4-unshelved/12345
157 <submit more changes via p4 to the same files>
158 $ git p4 unshelve 12345
159 <refuses to unshelve until git is in sync with p4 again>
160
162 General options
163 All commands except clone accept these options.
164 --git-dir <dir>
166 Set the GIT_DIR environment variable. See git(1).
167 -v, --verbose
169 Provide more progress information.
170 Sync options
172 These options can be used in the initial clone as well as in subsequent
173 sync operations.
174 --branch <ref>
176 Import changes into <ref> instead of refs/remotes/p4/master. If
177 <ref> starts with refs/, it is used as is. Otherwise, if it does
178 not start with p4/, that prefix is added.
179 By default a <ref> not starting with refs/ is treated as the name
181 of a remote-tracking branch (under refs/remotes/). This behavior
182 can be modified using the --import-local option.
183 The default <ref> is "master".
185 This example imports a new remote "p4/proj2" into an existing Git
187 repository:
188 $ git init
190 $ git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2
191 --detect-branches
193 Use the branch detection algorithm to find new paths in p4. It is
194 documented below in "BRANCH DETECTION".
195 --changesfile <file>
197 Import exactly the p4 change numbers listed in file, one per line.
198 Normally, git p4 inspects the current p4 repository state and
199 detects the changes it should import.
200 --silent
202 Do not print any progress information.
203 --detect-labels
205 Query p4 for labels associated with the depot paths, and add them
206 as tags in Git. Limited usefulness as only imports labels
207 associated with new changelists. Deprecated.
208 --import-labels
210 Import labels from p4 into Git.
211 --import-local
213 By default, p4 branches are stored in refs/remotes/p4/, where they
214 will be treated as remote-tracking branches by git-branch(1) and
215 other commands. This option instead puts p4 branches in
216 refs/heads/p4/. Note that future sync operations must specify
217 --import-local as well so that they can find the p4 branches in
218 refs/heads.
219 --max-changes <n>
221 Import at most n changes, rather than the entire range of changes
222 included in the given revision specifier. A typical usage would be
223 use @all as the revision specifier, but then to use --max-changes
224 1000 to import only the last 1000 revisions rather than the entire
225 revision history.
226 --changes-block-size <n>
228 The internal block size to use when converting a revision specifier
229 such as @all into a list of specific change numbers. Instead of
230 using a single call to p4 changes to find the full list of changes
231 for the conversion, there are a sequence of calls to p4 changes -m,
232 each of which requests one block of changes of the given size. The
233 default block size is 500, which should usually be suitable.
234 --keep-path
236 The mapping of file names from the p4 depot path to Git, by
237 default, involves removing the entire depot path. With this option,
238 the full p4 depot path is retained in Git. For example, path
239 //depot/main/foo/bar.c, when imported from //depot/main/, becomes
240 foo/bar.c. With --keep-path, the Git path is instead
241 depot/main/foo/bar.c.
242 --use-client-spec
244 Use a client spec to find the list of interesting files in p4. See
245 the "CLIENT SPEC" section below.
246 -/ <path>
248 Exclude selected depot paths when cloning or syncing.
249 Clone options
251 These options can be used in an initial clone, along with the sync
252 options described above.
253 --destination <directory>
255 Where to create the Git repository. If not provided, the last
256 component in the p4 depot path is used to create a new directory.
257 --bare
259 Perform a bare clone. See git-clone(1).
260 Submit options
262 These options can be used to modify git p4 submit behavior.
263 --origin <commit>
265 Upstream location from which commits are identified to submit to
266 p4. By default, this is the most recent p4 commit reachable from
267 HEAD.
268 -M
270 Detect renames. See git-diff(1). Renames will be represented in p4
271 using explicit move operations. There is no corresponding option to
272 detect copies, but there are variables for both moves and copies.
273 --preserve-user
275 Re-author p4 changes before submitting to p4. This option requires
276 p4 admin privileges.
277 --export-labels
279 Export tags from Git as p4 labels. Tags found in Git are applied to
280 the perforce working directory.
281 -n, --dry-run
283 Show just what commits would be submitted to p4; do not change
284 state in Git or p4.
285 --prepare-p4-only
287 Apply a commit to the p4 workspace, opening, adding and deleting
288 files in p4 as for a normal submit operation. Do not issue the
289 final "p4 submit", but instead print a message about how to submit
290 manually or revert. This option always stops after the first
291 (oldest) commit. Git tags are not exported to p4.
292 --shelve
294 Instead of submitting create a series of shelved changelists. After
295 creating each shelve, the relevant files are reverted/deleted. If
296 you have multiple commits pending multiple shelves will be created.
297 --update-shelve CHANGELIST
299 Update an existing shelved changelist with this commit. Implies
300 --shelve. Repeat for multiple shelved changelists.
301 --conflict=(ask|skip|quit)
303 Conflicts can occur when applying a commit to p4. When this
304 happens, the default behavior ("ask") is to prompt whether to skip
305 this commit and continue, or quit. This option can be used to
306 bypass the prompt, causing conflicting commits to be automatically
307 skipped, or to quit trying to apply commits, without prompting.
308 --branch <branch>
310 After submitting, sync this named branch instead of the default
311 p4/master. See the "Sync options" section above for more
312 information.
313 --commit (<sha1>|<sha1>..<sha1>)
315 Submit only the specified commit or range of commits, instead of
316 the full list of changes that are in the current Git branch.
317 --disable-rebase
319 Disable the automatic rebase after all commits have been
320 successfully submitted. Can also be set with git-p4.disableRebase.
321 --disable-p4sync
323 Disable the automatic sync of p4/master from Perforce after commits
324 have been submitted. Implies --disable-rebase. Can also be set with
325 git-p4.disableP4Sync. Sync with origin/master still goes ahead if
326 possible.
327
329 p4-pre-submit
330 The p4-pre-submit hook is executed if it exists and is executable. The
331 hook takes no parameters and nothing from standard input. Exiting with
332 non-zero status from this script prevents git-p4 submit from launching.
333 It can be bypassed with the --no-verify command line option.
334 One usage scenario is to run unit tests in the hook.
336 p4-prepare-changelist
338 The p4-prepare-changelist hook is executed right after preparing the
339 default changelist message and before the editor is started. It takes
340 one parameter, the name of the file that contains the changelist text.
341 Exiting with a non-zero status from the script will abort the process.
342 The purpose of the hook is to edit the message file in place, and it is
344 not suppressed by the --no-verify option. This hook is called even if
345 --prepare-p4-only is set.
346 p4-changelist
348 The p4-changelist hook is executed after the changelist message has
349 been edited by the user. It can be bypassed with the --no-verify
350 option. It takes a single parameter, the name of the file that holds
351 the proposed changelist text. Exiting with a non-zero status causes the
352 command to abort.
353 The hook is allowed to edit the changelist file and can be used to
355 normalize the text into some project standard format. It can also be
356 used to refuse the Submit after inspect the message file.
357 p4-post-changelist
359 The p4-post-changelist hook is invoked after the submit has
360 successfully occurred in P4. It takes no parameters and is meant
361 primarily for notification and cannot affect the outcome of the git p4
362 submit action.
363 Rebase options
365 These options can be used to modify git p4 rebase behavior.
366 --import-labels
368 Import p4 labels.
369 Unshelve options
371 --origin
372 Sets the git refspec against which the shelved P4 changelist is
373 compared. Defaults to p4/master.
374
376 The p4 depot path argument to git p4 sync and git p4 clone can be one
377 or more space-separated p4 depot paths, with an optional p4 revision
378 specifier on the end:
379 "//depot/my/project"
381 Import one commit with all files in the #head change under that
382 tree.
383 "//depot/my/project@all"
385 Import one commit for each change in the history of that depot
386 path.
387 "//depot/my/project@1,6"
389 Import only changes 1 through 6.
390 "//depot/proj1@all //depot/proj2@all"
392 Import all changes from both named depot paths into a single
393 repository. Only files below these directories are included. There
394 is not a subdirectory in Git for each "proj1" and "proj2". You must
395 use the --destination option when specifying more than one depot
396 path. The revision specifier must be specified identically on each
397 depot path. If there are files in the depot paths with the same
398 name, the path with the most recently updated version of the file
399 is the one that appears in Git.
400 See p4 help revisions for the full syntax of p4 revision specifiers.
402
404 The p4 client specification is maintained with the p4 client command
405 and contains among other fields, a View that specifies how the depot is
406 mapped into the client repository. The clone and sync commands can
407 consult the client spec when given the --use-client-spec option or when
408 the useClientSpec variable is true. After git p4 clone, the
409 useClientSpec variable is automatically set in the repository
410 configuration file. This allows future git p4 submit commands to work
411 properly; the submit command looks only at the variable and does not
412 have a command-line option.
413 The full syntax for a p4 view is documented in p4 help views. git p4
415 knows only a subset of the view syntax. It understands multi-line
416 mappings, overlays with +, exclusions with - and double-quotes around
417 whitespace. Of the possible wildcards, git p4 only handles ..., and
418 only when it is at the end of the path. git p4 will complain if it
419 encounters an unhandled wildcard.
420 Bugs in the implementation of overlap mappings exist. If multiple depot
422 paths map through overlays to the same location in the repository, git
423 p4 can choose the wrong one. This is hard to solve without dedicating a
424 client spec just for git p4.
425 The name of the client can be given to git p4 in multiple ways. The
427 variable git-p4.client takes precedence if it exists. Otherwise, normal
428 p4 mechanisms of determining the client are used: environment variable
429 P4CLIENT, a file referenced by P4CONFIG, or the local host name.
430
432 P4 does not have the same concept of a branch as Git. Instead, p4
433 organizes its content as a directory tree, where by convention
434 different logical branches are in different locations in the tree. The
435 p4 branch command is used to maintain mappings between different areas
436 in the tree, and indicate related content. git p4 can use these
437 mappings to determine branch relationships.
438 If you have a repository where all the branches of interest exist as
440 subdirectories of a single depot path, you can use --detect-branches
441 when cloning or syncing to have git p4 automatically find
442 subdirectories in p4, and to generate these as branches in Git.
443 For example, if the P4 repository structure is:
445 //depot/main/...
447 //depot/branch1/...
448 And "p4 branch -o branch1" shows a View line that looks like:
450 //depot/main/... //depot/branch1/...
452 Then this git p4 clone command:
454 git p4 clone --detect-branches //depot@all
456 produces a separate branch in refs/remotes/p4/ for //depot/main, called
458 master, and one for //depot/branch1 called depot/branch1.
459 However, it is not necessary to create branches in p4 to be able to use
461 them like branches. Because it is difficult to infer branch
462 relationships automatically, a Git configuration setting
463 git-p4.branchList can be used to explicitly identify branch
464 relationships. It is a list of "source:destination" pairs, like a
465 simple p4 branch specification, where the "source" and "destination"
466 are the path elements in the p4 repository. The example above relied on
467 the presence of the p4 branch. Without p4 branches, the same result
468 will occur with:
469 git init depot
471 cd depot
472 git config git-p4.branchList main:branch1
473 git p4 clone --detect-branches //depot@all .
474
476 The fast-import mechanism used by git p4 creates one pack file for each
477 invocation of git p4 sync. Normally, Git garbage compression (git-
478 gc(1)) automatically compresses these to fewer pack files, but explicit
479 invocation of git repack -adf may improve performance.
480
482 The following config settings can be used to modify git p4 behavior.
483 They all are in the git-p4 section.
484 General variables
486 git-p4.user
487 User specified as an option to all p4 commands, with -u <user>. The
488 environment variable P4USER can be used instead.
489 git-p4.password
491 Password specified as an option to all p4 commands, with -P
492 <password>. The environment variable P4PASS can be used instead.
493 git-p4.port
495 Port specified as an option to all p4 commands, with -p <port>. The
496 environment variable P4PORT can be used instead.
497 git-p4.host
499 Host specified as an option to all p4 commands, with -h <host>. The
500 environment variable P4HOST can be used instead.
501 git-p4.client
503 Client specified as an option to all p4 commands, with -c <client>,
504 including the client spec.
505 git-p4.retries
507 Specifies the number of times to retry a p4 command (notably, p4
508 sync) if the network times out. The default value is 3. Set the
509 value to 0 to disable retries or if your p4 version does not
510 support retries (pre 2012.2).
511 Clone and sync variables
513 git-p4.syncFromOrigin
514 Because importing commits from other Git repositories is much
515 faster than importing them from p4, a mechanism exists to find p4
516 changes first in Git remotes. If branches exist under
517 refs/remote/origin/p4, those will be fetched and used when syncing
518 from p4. This variable can be set to false to disable this
519 behavior.
520 git-p4.branchUser
522 One phase in branch detection involves looking at p4 branches to
523 find new ones to import. By default, all branches are inspected.
524 This option limits the search to just those owned by the single
525 user named in the variable.
526 git-p4.branchList
528 List of branches to be imported when branch detection is enabled.
529 Each entry should be a pair of branch names separated by a colon
530 (:). This example declares that both branchA and branchB were
531 created from main:
532 git config git-p4.branchList main:branchA
534 git config --add git-p4.branchList main:branchB
535 git-p4.ignoredP4Labels
537 List of p4 labels to ignore. This is built automatically as
538 unimportable labels are discovered.
539 git-p4.importLabels
541 Import p4 labels into git, as per --import-labels.
542 git-p4.labelImportRegexp
544 Only p4 labels matching this regular expression will be imported.
545 The default value is [a-zA-Z0-9_\-.]+$.
546 git-p4.useClientSpec
548 Specify that the p4 client spec should be used to identify p4 depot
549 paths of interest. This is equivalent to specifying the option
550 --use-client-spec. See the "CLIENT SPEC" section above. This
551 variable is a boolean, not the name of a p4 client.
552 git-p4.pathEncoding
554 Perforce keeps the encoding of a path as given by the originating
555 OS. Git expects paths encoded as UTF-8. Use this config to tell
556 git-p4 what encoding Perforce had used for the paths. This encoding
557 is used to transcode the paths to UTF-8. As an example, Perforce on
558 Windows often uses "cp1252" to encode path names. If this option is
559 passed into a p4 clone request, it is persisted in the resulting
560 new git repo.
561 git-p4.metadataDecodingStrategy
563 Perforce keeps the encoding of a changelist descriptions and user
564 full names as stored by the client on a given OS. The p4v client
565 uses the OS-local encoding, and so different users can end up
566 storing different changelist descriptions or user full names in
567 different encodings, in the same depot. Git tolerates
568 inconsistent/incorrect encodings in commit messages and author
569 names, but expects them to be specified in utf-8. git-p4 can use
570 three different decoding strategies in handling the encoding
571 uncertainty in Perforce: passthrough simply passes the original
572 bytes through from Perforce to git, creating usable but
573 incorrectly-encoded data when the Perforce data is encoded as
574 anything other than utf-8. strict expects the Perforce data to be
575 encoded as utf-8, and fails to import when this is not true.
576 fallback attempts to interpret the data as utf-8, and otherwise
577 falls back to using a secondary encoding - by default the common
578 windows encoding cp-1252 - with upper-range bytes escaped if
579 decoding with the fallback encoding also fails. Under python2 the
580 default strategy is passthrough for historical reasons, and under
581 python3 the default is fallback. When strict is selected and
582 decoding fails, the error message will propose changing this config
583 parameter as a workaround. If this option is passed into a p4 clone
584 request, it is persisted into the resulting new git repo.
585 git-p4.metadataFallbackEncoding
587 Specify the fallback encoding to use when decoding Perforce author
588 names and changelists descriptions using the fallback strategy (see
589 git-p4.metadataDecodingStrategy). The fallback encoding will only
590 be used when decoding as utf-8 fails. This option defaults to
591 cp1252, a common windows encoding. If this option is passed into a
592 p4 clone request, it is persisted into the resulting new git repo.
593 git-p4.largeFileSystem
595 Specify the system that is used for large (binary) files. Please
596 note that large file systems do not support the git p4 submit
597 command. Only Git LFS is implemented right now (see
598 https://git-lfs.github.com/ for more information). Download and
599 install the Git LFS command line extension to use this option and
600 configure it like this:
601 git config git-p4.largeFileSystem GitLFS
603 git-p4.largeFileExtensions
605 All files matching a file extension in the list will be processed
606 by the large file system. Do not prefix the extensions with ..
607 git-p4.largeFileThreshold
609 All files with an uncompressed size exceeding the threshold will be
610 processed by the large file system. By default the threshold is
611 defined in bytes. Add the suffix k, m, or g to change the unit.
612 git-p4.largeFileCompressedThreshold
614 All files with a compressed size exceeding the threshold will be
615 processed by the large file system. This option might slow down
616 your clone/sync process. By default the threshold is defined in
617 bytes. Add the suffix k, m, or g to change the unit.
618 git-p4.largeFilePush
620 Boolean variable which defines if large files are automatically
621 pushed to a server.
622 git-p4.keepEmptyCommits
624 A changelist that contains only excluded files will be imported as
625 an empty commit if this boolean option is set to true.
626 git-p4.mapUser
628 Map a P4 user to a name and email address in Git. Use a string with
629 the following format to create a mapping:
630 git config --add git-p4.mapUser "p4user = First Last <mail@address.com>"
632 A mapping will override any user information from P4. Mappings for
634 multiple P4 user can be defined.
635 Submit variables
637 git-p4.detectRenames
638 Detect renames. See git-diff(1). This can be true, false, or a
639 score as expected by git diff -M.
640 git-p4.detectCopies
642 Detect copies. See git-diff(1). This can be true, false, or a score
643 as expected by git diff -C.
644 git-p4.detectCopiesHarder
646 Detect copies harder. See git-diff(1). A boolean.
647 git-p4.preserveUser
649 On submit, re-author changes to reflect the Git author, regardless
650 of who invokes git p4 submit.
651 git-p4.allowMissingP4Users
653 When preserveUser is true, git p4 normally dies if it cannot find
654 an author in the p4 user map. This setting submits the change
655 regardless.
656 git-p4.skipSubmitEdit
658 The submit process invokes the editor before each p4 change is
659 submitted. If this setting is true, though, the editing step is
660 skipped.
661 git-p4.skipSubmitEditCheck
663 After editing the p4 change message, git p4 makes sure that the
664 description really was changed by looking at the file modification
665 time. This option disables that test.
666 git-p4.allowSubmit
668 By default, any branch can be used as the source for a git p4
669 submit operation. This configuration variable, if set, permits only
670 the named branches to be used as submit sources. Branch names must
671 be the short names (no "refs/heads/"), and should be separated by
672 commas (","), with no spaces.
673 git-p4.skipUserNameCheck
675 If the user running git p4 submit does not exist in the p4 user
676 map, git p4 exits. This option can be used to force submission
677 regardless.
678 git-p4.attemptRCSCleanup
680 If enabled, git p4 submit will attempt to cleanup RCS keywords
681 ($Header$, etc). These would otherwise cause merge conflicts and
682 prevent the submit going ahead. This option should be considered
683 experimental at present.
684 git-p4.exportLabels
686 Export Git tags to p4 labels, as per --export-labels.
687 git-p4.labelExportRegexp
689 Only p4 labels matching this regular expression will be exported.
690 The default value is [a-zA-Z0-9_\-.]+$.
691 git-p4.conflict
693 Specify submit behavior when a conflict with p4 is found, as per
694 --conflict. The default behavior is ask.
695 git-p4.disableRebase
697 Do not rebase the tree against p4/master following a submit.
698 git-p4.disableP4Sync
700 Do not sync p4/master with Perforce following a submit. Implies
701 git-p4.disableRebase.
702
704 • Changesets from p4 are imported using Git fast-import.
705 • Cloning or syncing does not require a p4 client; file contents are
707 collected using p4 print.
708 • Submitting requires a p4 client, which is not in the same location
710 as the Git repository. Patches are applied, one at a time, to this
711 p4 client and submitted from there.
712 • Each commit imported by git p4 has a line at the end of the log
714 message indicating the p4 depot location and change number. This
715 line is used by later git p4 sync operations to know which p4
716 changes are new.
717
719 Part of the git(1) suite
720Git 2.39.1 2023-01-13 GIT-P4(1)