| blob | a5db3dbd32bdb668ec05bf767c41bf15d30f9579 |
1 '\" t
2 .\" Title: git-p4
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
5 .\" Date: 2023-08-09
6 .\" Manual: Git Manual
7 .\" Source: Git 2.42.0.rc1
8 .\" Language: English
9 .\"
10 .TH "GIT\-P4" "1" "2023\-08\-09" "Git 2\&.42\&.0\&.rc1" "Git Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 git-p4 \- Import from and submit to Perforce repositories
32 .SH "SYNOPSIS"
33 .sp
34 .nf
35 \fIgit p4 clone\fR [<sync\-options>] [<clone\-options>] <p4\-depot\-path>\&...
36 \fIgit p4 sync\fR [<sync\-options>] [<p4\-depot\-path>\&...]
37 \fIgit p4 rebase\fR
38 \fIgit p4 submit\fR [<submit\-options>] [<master\-branch\-name>]
39 .fi
40 .sp
41 .SH "DESCRIPTION"
42 .sp
43 This command provides a way to interact with p4 repositories using Git\&.
44 .sp
45 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\&.
46 .SH "EXAMPLES"
47 .sp
48 .RS 4
49 .ie n \{\
50 \h'-04'\(bu\h'+03'\c
51 .\}
52 .el \{\
53 .sp -1
54 .IP \(bu 2.3
55 .\}
56 Clone a repository:
57 .sp
58 .if n \{\
59 .RS 4
60 .\}
61 .nf
62 $ git p4 clone //depot/path/project
63 .fi
64 .if n \{\
65 .RE
66 .\}
67 .sp
68 .RE
69 .sp
70 .RS 4
71 .ie n \{\
72 \h'-04'\(bu\h'+03'\c
73 .\}
74 .el \{\
75 .sp -1
76 .IP \(bu 2.3
77 .\}
78 Do some work in the newly created Git repository:
79 .sp
80 .if n \{\
81 .RS 4
82 .\}
83 .nf
84 $ cd project
85 $ vi foo\&.h
86 $ git commit \-a \-m "edited foo\&.h"
87 .fi
88 .if n \{\
89 .RE
90 .\}
91 .sp
92 .RE
93 .sp
94 .RS 4
95 .ie n \{\
96 \h'-04'\(bu\h'+03'\c
97 .\}
98 .el \{\
99 .sp -1
100 .IP \(bu 2.3
101 .\}
102 Update the Git repository with recent changes from p4, rebasing your work on top:
103 .sp
104 .if n \{\
105 .RS 4
106 .\}
107 .nf
108 $ git p4 rebase
109 .fi
110 .if n \{\
111 .RE
112 .\}
113 .sp
114 .RE
115 .sp
116 .RS 4
117 .ie n \{\
118 \h'-04'\(bu\h'+03'\c
119 .\}
120 .el \{\
121 .sp -1
122 .IP \(bu 2.3
123 .\}
124 Submit your commits back to p4:
125 .sp
126 .if n \{\
127 .RS 4
128 .\}
129 .nf
130 $ git p4 submit
131 .fi
132 .if n \{\
133 .RE
134 .\}
135 .sp
136 .RE
137 .SH "COMMANDS"
138 .SS "Clone"
139 .sp
140 Generally, \fIgit p4 clone\fR is used to create a new Git directory from an existing p4 repository:
141 .sp
142 .if n \{\
143 .RS 4
144 .\}
145 .nf
146 $ git p4 clone //depot/path/project
147 .fi
148 .if n \{\
149 .RE
150 .\}
151 .sp
152 .sp
153 This:
154 .sp
155 .RS 4
156 .ie n \{\
157 \h'-04' 1.\h'+01'\c
158 .\}
159 .el \{\
160 .sp -1
161 .IP " 1." 4.2
162 .\}
163 Creates an empty Git repository in a subdirectory called
164 \fIproject\fR\&.
165 .RE
166 .sp
167 .RS 4
168 .ie n \{\
169 \h'-04' 2.\h'+01'\c
170 .\}
171 .el \{\
172 .sp -1
173 .IP " 2." 4.2
174 .\}
175 Imports the full contents of the head revision from the given p4 depot path into a single commit in the Git branch
176 \fIrefs/remotes/p4/master\fR\&.
177 .RE
178 .sp
179 .RS 4
180 .ie n \{\
181 \h'-04' 3.\h'+01'\c
182 .\}
183 .el \{\
184 .sp -1
185 .IP " 3." 4.2
186 .\}
187 Creates a local branch,
188 \fImaster\fR
189 from this remote and checks it out\&.
190 .RE
191 .sp
192 To reproduce the entire p4 history in Git, use the \fI@all\fR modifier on the depot path:
193 .sp
194 .if n \{\
195 .RS 4
196 .\}
197 .nf
198 $ git p4 clone //depot/path/project@all
199 .fi
200 .if n \{\
201 .RE
202 .\}
203 .sp
204 .SS "Sync"
205 .sp
206 As development continues in the p4 repository, those changes can be included in the Git repository using:
207 .sp
208 .if n \{\
209 .RS 4
210 .\}
211 .nf
212 $ git p4 sync
213 .fi
214 .if n \{\
215 .RE
216 .\}
217 .sp
218 .sp
219 This command finds new changes in p4 and imports them as Git commits\&.
220 .sp
221 P4 repositories can be added to an existing Git repository using \fIgit p4 sync\fR too:
222 .sp
223 .if n \{\
224 .RS 4
225 .\}
226 .nf
227 $ mkdir repo\-git
228 $ cd repo\-git
229 $ git init
230 $ git p4 sync //path/in/your/perforce/depot
231 .fi
232 .if n \{\
233 .RE
234 .\}
235 .sp
236 .sp
237 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\&.
238 .sp
239 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\&.
240 .sp
241 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\&.
242 .SS "Rebase"
243 .sp
244 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\&.
245 .sp
246 .if n \{\
247 .RS 4
248 .\}
249 .nf
250 $ git p4 rebase
251 .fi
252 .if n \{\
253 .RE
254 .\}
255 .sp
256 .SS "Submit"
257 .sp
258 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\&.
259 .sp
260 To submit all changes that are in the current Git branch but not in the \fIp4/master\fR branch, use:
261 .sp
262 .if n \{\
263 .RS 4
264 .\}
265 .nf
266 $ git p4 submit
267 .fi
268 .if n \{\
269 .RE
270 .\}
271 .sp
272 .sp
273 To specify a branch other than the current one, use:
274 .sp
275 .if n \{\
276 .RS 4
277 .\}
278 .nf
279 $ git p4 submit topicbranch
280 .fi
281 .if n \{\
282 .RE
283 .\}
284 .sp
285 .sp
286 To specify a single commit or a range of commits, use:
287 .sp
288 .if n \{\
289 .RS 4
290 .\}
291 .nf
292 $ git p4 submit \-\-commit <sha1>
293 $ git p4 submit \-\-commit <sha1\&.\&.sha1>
294 .fi
295 .if n \{\
296 .RE
297 .\}
298 .sp
299 .sp
300 The upstream reference is generally \fIrefs/remotes/p4/master\fR, but can be overridden using the \fB\-\-origin=\fR command\-line option\&.
301 .sp
302 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\&.
303 .sp
304 To shelve changes instead of submitting, use \fB\-\-shelve\fR and \fB\-\-update\-shelve\fR:
305 .sp
306 .if n \{\
307 .RS 4
308 .\}
309 .nf
310 $ git p4 submit \-\-shelve
311 $ git p4 submit \-\-update\-shelve 1234 \-\-update\-shelve 2345
312 .fi
313 .if n \{\
314 .RE
315 .\}
316 .sp
317 .SS "Unshelve"
318 .sp
319 Unshelving will take a shelved P4 changelist, and produce the equivalent git commit in the branch refs/remotes/p4\-unshelved/<changelist>\&.
320 .sp
321 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\&.
322 .sp
323 The origin revision can be changed with the "\-\-origin" option\&.
324 .sp
325 If the target branch in refs/remotes/p4\-unshelved already exists, the old one will be renamed\&.
326 .sp
327 .if n \{\
328 .RS 4
329 .\}
330 .nf
331 $ git p4 sync
332 $ git p4 unshelve 12345
333 $ git show p4\-unshelved/12345
334 <submit more changes via p4 to the same files>
335 $ git p4 unshelve 12345
336 <refuses to unshelve until git is in sync with p4 again>
337 .fi
338 .if n \{\
339 .RE
340 .\}
341 .sp
342 .SH "OPTIONS"
343 .SS "General options"
344 .sp
345 All commands except clone accept these options\&.
346 .PP
347 \-\-git\-dir <dir>
348 .RS 4
349 Set the
350 \fBGIT_DIR\fR
351 environment variable\&. See
352 \fBgit\fR(1)\&.
353 .RE
354 .PP
355 \-v, \-\-verbose
356 .RS 4
357 Provide more progress information\&.
358 .RE
359 .SS "Sync options"
360 .sp
361 These options can be used in the initial \fIclone\fR as well as in subsequent \fIsync\fR operations\&.
362 .PP
363 \-\-branch <ref>
364 .RS 4
365 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\&.
366 .sp
367 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\&.
368 .sp
369 The default <ref> is "master"\&.
370 .sp
371 This example imports a new remote "p4/proj2" into an existing Git repository:
372 .sp
373 .if n \{\
374 .RS 4
375 .\}
376 .nf
377 $ git init
378 $ git p4 sync \-\-branch=refs/remotes/p4/proj2 //depot/proj2
379 .fi
380 .if n \{\
381 .RE
382 .\}
383 .sp
384 .RE
385 .PP
386 \-\-detect\-branches
387 .RS 4
388 Use the branch detection algorithm to find new paths in p4\&. It is documented below in "BRANCH DETECTION"\&.
389 .RE
390 .PP
391 \-\-changesfile <file>
392 .RS 4
393 Import exactly the p4 change numbers listed in
394 \fIfile\fR, one per line\&. Normally,
395 \fIgit p4\fR
396 inspects the current p4 repository state and detects the changes it should import\&.
397 .RE
398 .PP
399 \-\-silent
400 .RS 4
401 Do not print any progress information\&.
402 .RE
403 .PP
404 \-\-detect\-labels
405 .RS 4
406 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\&.
407 .RE
408 .PP
409 \-\-import\-labels
410 .RS 4
411 Import labels from p4 into Git\&.
412 .RE
413 .PP
414 \-\-import\-local
415 .RS 4
416 By default, p4 branches are stored in
417 \fIrefs/remotes/p4/\fR, where they will be treated as remote\-tracking branches by
418 \fBgit-branch\fR(1)
419 and other commands\&. This option instead puts p4 branches in
420 \fIrefs/heads/p4/\fR\&. Note that future sync operations must specify
421 \fB\-\-import\-local\fR
422 as well so that they can find the p4 branches in refs/heads\&.
423 .RE
424 .PP
425 \-\-max\-changes <n>
426 .RS 4
427 Import at most
428 \fIn\fR
429 changes, rather than the entire range of changes included in the given revision specifier\&. A typical usage would be use
430 \fI@all\fR
431 as the revision specifier, but then to use
432 \fI\-\-max\-changes 1000\fR
433 to import only the last 1000 revisions rather than the entire revision history\&.
434 .RE
435 .PP
436 \-\-changes\-block\-size <n>
437 .RS 4
438 The internal block size to use when converting a revision specifier such as
439 \fI@all\fR
440 into a list of specific change numbers\&. Instead of using a single call to
441 \fIp4 changes\fR
442 to find the full list of changes for the conversion, there are a sequence of calls to
443 \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\&.
444 .RE
445 .PP
446 \-\-keep\-path
447 .RS 4
448 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
449 \fI//depot/main/foo/bar\&.c\fR, when imported from
450 \fI//depot/main/\fR, becomes
451 \fIfoo/bar\&.c\fR\&. With
452 \fB\-\-keep\-path\fR, the Git path is instead
453 \fIdepot/main/foo/bar\&.c\fR\&.
454 .RE
455 .PP
456 \-\-use\-client\-spec
457 .RS 4
458 Use a client spec to find the list of interesting files in p4\&. See the "CLIENT SPEC" section below\&.
459 .RE
460 .PP
461 \-/ <path>
462 .RS 4
463 Exclude selected depot paths when cloning or syncing\&.
464 .RE
465 .SS "Clone options"
466 .sp
467 These options can be used in an initial \fIclone\fR, along with the \fIsync\fR options described above\&.
468 .PP
469 \-\-destination <directory>
470 .RS 4
471 Where to create the Git repository\&. If not provided, the last component in the p4 depot path is used to create a new directory\&.
472 .RE
473 .PP
474 \-\-bare
475 .RS 4
476 Perform a bare clone\&. See
477 \fBgit-clone\fR(1)\&.
478 .RE
479 .SS "Submit options"
480 .sp
481 These options can be used to modify \fIgit p4 submit\fR behavior\&.
482 .PP
483 \-\-origin <commit>
484 .RS 4
485 Upstream location from which commits are identified to submit to p4\&. By default, this is the most recent p4 commit reachable from
486 \fBHEAD\fR\&.
487 .RE
488 .PP
489 \-M
490 .RS 4
491 Detect renames\&. See
492 \fBgit-diff\fR(1)\&. Renames will be represented in p4 using explicit
493 \fImove\fR
494 operations\&. There is no corresponding option to detect copies, but there are variables for both moves and copies\&.
495 .RE
496 .PP
497 \-\-preserve\-user
498 .RS 4
499 Re\-author p4 changes before submitting to p4\&. This option requires p4 admin privileges\&.
500 .RE
501 .PP
502 \-\-export\-labels
503 .RS 4
504 Export tags from Git as p4 labels\&. Tags found in Git are applied to the perforce working directory\&.
505 .RE
506 .PP
507 \-n, \-\-dry\-run
508 .RS 4
509 Show just what commits would be submitted to p4; do not change state in Git or p4\&.
510 .RE
511 .PP
512 \-\-prepare\-p4\-only
513 .RS 4
514 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\&.
515 .RE
516 .PP
517 \-\-shelve
518 .RS 4
519 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\&.
520 .RE
521 .PP
522 \-\-update\-shelve CHANGELIST
523 .RS 4
524 Update an existing shelved changelist with this commit\&. Implies \-\-shelve\&. Repeat for multiple shelved changelists\&.
525 .RE
526 .PP
527 \-\-conflict=(ask|skip|quit)
528 .RS 4
529 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\&.
530 .RE
531 .PP
532 \-\-branch <branch>
533 .RS 4
534 After submitting, sync this named branch instead of the default p4/master\&. See the "Sync options" section above for more information\&.
535 .RE
536 .PP
537 \-\-commit (<sha1>|<sha1>\&.\&.<sha1>)
538 .RS 4
539 Submit only the specified commit or range of commits, instead of the full list of changes that are in the current Git branch\&.
540 .RE
541 .PP
542 \-\-disable\-rebase
543 .RS 4
544 Disable the automatic rebase after all commits have been successfully submitted\&. Can also be set with git\-p4\&.disableRebase\&.
545 .RE
546 .PP
547 \-\-disable\-p4sync
548 .RS 4
549 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\&.
550 .RE
551 .SH "HOOKS FOR SUBMIT"
552 .SS "p4\-pre\-submit"
553 .sp
554 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\&.
555 .sp
556 One usage scenario is to run unit tests in the hook\&.
557 .SS "p4\-prepare\-changelist"
558 .sp
559 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\&.
560 .sp
561 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\&.
562 .SS "p4\-changelist"
563 .sp
564 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\&.
565 .sp
566 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\&.
567 .SS "p4\-post\-changelist"
568 .sp
569 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\&.
570 .SS "Rebase options"
571 .sp
572 These options can be used to modify \fIgit p4 rebase\fR behavior\&.
573 .PP
574 \-\-import\-labels
575 .RS 4
576 Import p4 labels\&.
577 .RE
578 .SS "Unshelve options"
579 .PP
580 \-\-origin
581 .RS 4
582 Sets the git refspec against which the shelved P4 changelist is compared\&. Defaults to p4/master\&.
583 .RE
584 .SH "DEPOT PATH SYNTAX"
585 .sp
586 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:
587 .PP
588 "//depot/my/project"
589 .RS 4
590 Import one commit with all files in the
591 \fI#head\fR
592 change under that tree\&.
593 .RE
594 .PP
595 "//depot/my/project@all"
596 .RS 4
597 Import one commit for each change in the history of that depot path\&.
598 .RE
599 .PP
600 "//depot/my/project@1,6"
601 .RS 4
602 Import only changes 1 through 6\&.
603 .RE
604 .PP
605 "//depot/proj1@all //depot/proj2@all"
606 .RS 4
607 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
608 \fB\-\-destination\fR
609 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\&.
610 .RE
611 .sp
612 See \fIp4 help revisions\fR for the full syntax of p4 revision specifiers\&.
613 .SH "CLIENT SPEC"
614 .sp
615 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\&.
616 .sp
617 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\&.
618 .sp
619 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\&.
620 .sp
621 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\&.
622 .SH "BRANCH DETECTION"
623 .sp
624 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\&.
625 .sp
626 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\&.
627 .sp
628 For example, if the P4 repository structure is:
629 .sp
630 .if n \{\
631 .RS 4
632 .\}
633 .nf
634 //depot/main/\&.\&.\&.
635 //depot/branch1/\&.\&.\&.
636 .fi
637 .if n \{\
638 .RE
639 .\}
640 .sp
641 .sp
642 And "p4 branch \-o branch1" shows a View line that looks like:
643 .sp
644 .if n \{\
645 .RS 4
646 .\}
647 .nf
648 //depot/main/\&.\&.\&. //depot/branch1/\&.\&.\&.
649 .fi
650 .if n \{\
651 .RE
652 .\}
653 .sp
654 .sp
655 Then this \fIgit p4 clone\fR command:
656 .sp
657 .if n \{\
658 .RS 4
659 .\}
660 .nf
661 git p4 clone \-\-detect\-branches //depot@all
662 .fi
663 .if n \{\
664 .RE
665 .\}
666 .sp
667 .sp
668 produces a separate branch in \fIrefs/remotes/p4/\fR for //depot/main, called \fImaster\fR, and one for //depot/branch1 called \fIdepot/branch1\fR\&.
669 .sp
670 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:
671 .sp
672 .if n \{\
673 .RS 4
674 .\}
675 .nf
676 git init depot
677 cd depot
678 git config git\-p4\&.branchList main:branch1
679 git p4 clone \-\-detect\-branches //depot@all \&.
680 .fi
681 .if n \{\
682 .RE
683 .\}
684 .sp
685 .SH "PERFORMANCE"
686 .sp
687 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\&.
688 .SH "CONFIGURATION VARIABLES"
689 .sp
690 The following config settings can be used to modify \fIgit p4\fR behavior\&. They all are in the \fIgit\-p4\fR section\&.
691 .SS "General variables"
692 .PP
693 git\-p4\&.user
694 .RS 4
695 User specified as an option to all p4 commands, with
696 \fI\-u <user>\fR\&. The environment variable
697 \fBP4USER\fR
698 can be used instead\&.
699 .RE
700 .PP
701 git\-p4\&.password
702 .RS 4
703 Password specified as an option to all p4 commands, with
704 \fI\-P <password>\fR\&. The environment variable
705 \fBP4PASS\fR
706 can be used instead\&.
707 .RE
708 .PP
709 git\-p4\&.port
710 .RS 4
711 Port specified as an option to all p4 commands, with
712 \fI\-p <port>\fR\&. The environment variable
713 \fBP4PORT\fR
714 can be used instead\&.
715 .RE
716 .PP
717 git\-p4\&.host
718 .RS 4
719 Host specified as an option to all p4 commands, with
720 \fI\-h <host>\fR\&. The environment variable
721 \fBP4HOST\fR
722 can be used instead\&.
723 .RE
724 .PP
725 git\-p4\&.client
726 .RS 4
727 Client specified as an option to all p4 commands, with
728 \fI\-c <client>\fR, including the client spec\&.
729 .RE
730 .PP
731 git\-p4\&.retries
732 .RS 4
733 Specifies the number of times to retry a p4 command (notably,
734 \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)\&.
735 .RE
736 .SS "Clone and sync variables"
737 .PP
738 git\-p4\&.syncFromOrigin
739 .RS 4
740 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
741 \fIrefs/remote/origin/p4\fR, those will be fetched and used when syncing from p4\&. This variable can be set to
742 \fIfalse\fR
743 to disable this behavior\&.
744 .RE
745 .PP
746 git\-p4\&.branchUser
747 .RS 4
748 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\&.
749 .RE
750 .PP
751 git\-p4\&.branchList
752 .RS 4
753 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:
754 .sp
755 .if n \{\
756 .RS 4
757 .\}
758 .nf
759 git config git\-p4\&.branchList main:branchA
760 git config \-\-add git\-p4\&.branchList main:branchB
761 .fi
762 .if n \{\
763 .RE
764 .\}
765 .sp
766 .RE
767 .PP
768 git\-p4\&.ignoredP4Labels
769 .RS 4
770 List of p4 labels to ignore\&. This is built automatically as unimportable labels are discovered\&.
771 .RE
772 .PP
773 git\-p4\&.importLabels
774 .RS 4
775 Import p4 labels into git, as per \-\-import\-labels\&.
776 .RE
777 .PP
778 git\-p4\&.labelImportRegexp
779 .RS 4
780 Only p4 labels matching this regular expression will be imported\&. The default value is
781 \fI[a\-zA\-Z0\-9_\e\-\&.]+$\fR\&.
782 .RE
783 .PP
784 git\-p4\&.useClientSpec
785 .RS 4
786 Specify that the p4 client spec should be used to identify p4 depot paths of interest\&. This is equivalent to specifying the option
787 \fB\-\-use\-client\-spec\fR\&. See the "CLIENT SPEC" section above\&. This variable is a boolean, not the name of a p4 client\&.
788 .RE
789 .PP
790 git\-p4\&.pathEncoding
791 .RS 4
792 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\&.
793 .RE
794 .PP
795 git\-p4\&.metadataDecodingStrategy
796 .RS 4
797 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:
798 \fIpassthrough\fR
799 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\&.
800 \fIstrict\fR
801 expects the Perforce data to be encoded as utf\-8, and fails to import when this is not true\&.
802 \fIfallback\fR
803 attempts to interpret the data as utf\-8, and otherwise falls back to using a secondary encoding \- by default the common windows encoding
804 \fIcp\-1252\fR
805 \- with upper\-range bytes escaped if decoding with the fallback encoding also fails\&. Under python2 the default strategy is
806 \fIpassthrough\fR
807 for historical reasons, and under python3 the default is
808 \fIfallback\fR\&. When
809 \fIstrict\fR
810 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\&.
811 .RE
812 .PP
813 git\-p4\&.metadataFallbackEncoding
814 .RS 4
815 Specify the fallback encoding to use when decoding Perforce author names and changelists descriptions using the
816 \fIfallback\fR
817 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\&.
818 .RE
819 .PP
820 git\-p4\&.largeFileSystem
821 .RS 4
822 Specify the system that is used for large (binary) files\&. Please note that large file systems do not support the
823 \fIgit p4 submit\fR
824 command\&. Only Git LFS is implemented right now (see
825 \m[blue]\fBhttps://git\-lfs\&.github\&.com/\fR\m[]
826 for more information)\&. Download and install the Git LFS command line extension to use this option and configure it like this:
827 .sp
828 .if n \{\
829 .RS 4
830 .\}
831 .nf
832 git config git\-p4\&.largeFileSystem GitLFS
833 .fi
834 .if n \{\
835 .RE
836 .\}
837 .sp
838 .RE
839 .PP
840 git\-p4\&.largeFileExtensions
841 .RS 4
842 All files matching a file extension in the list will be processed by the large file system\&. Do not prefix the extensions with
843 \fI\&.\fR\&.
844 .RE
845 .PP
846 git\-p4\&.largeFileThreshold
847 .RS 4
848 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\&.
849 .RE
850 .PP
851 git\-p4\&.largeFileCompressedThreshold
852 .RS 4
853 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\&.
854 .RE
855 .PP
856 git\-p4\&.largeFilePush
857 .RS 4
858 Boolean variable which defines if large files are automatically pushed to a server\&.
859 .RE
860 .PP
861 git\-p4\&.keepEmptyCommits
862 .RS 4
863 A changelist that contains only excluded files will be imported as an empty commit if this boolean option is set to true\&.
864 .RE
865 .PP
866 git\-p4\&.mapUser
867 .RS 4
868 Map a P4 user to a name and email address in Git\&. Use a string with the following format to create a mapping:
869 .sp
870 .if n \{\
871 .RS 4
872 .\}
873 .nf
874 git config \-\-add git\-p4\&.mapUser "p4user = First Last <mail@address\&.com>"
875 .fi
876 .if n \{\
877 .RE
878 .\}
879 .sp
880 A mapping will override any user information from P4\&. Mappings for multiple P4 user can be defined\&.
881 .RE
882 .SS "Submit variables"
883 .PP
884 git\-p4\&.detectRenames
885 .RS 4
886 Detect renames\&. See
887 \fBgit-diff\fR(1)\&. This can be true, false, or a score as expected by
888 \fIgit diff \-M\fR\&.
889 .RE
890 .PP
891 git\-p4\&.detectCopies
892 .RS 4
893 Detect copies\&. See
894 \fBgit-diff\fR(1)\&. This can be true, false, or a score as expected by
895 \fIgit diff \-C\fR\&.
896 .RE
897 .PP
898 git\-p4\&.detectCopiesHarder
899 .RS 4
900 Detect copies harder\&. See
901 \fBgit-diff\fR(1)\&. A boolean\&.
902 .RE
903 .PP
904 git\-p4\&.preserveUser
905 .RS 4
906 On submit, re\-author changes to reflect the Git author, regardless of who invokes
907 \fIgit p4 submit\fR\&.
908 .RE
909 .PP
910 git\-p4\&.allowMissingP4Users
911 .RS 4
912 When
913 \fIpreserveUser\fR
914 is true,
915 \fIgit p4\fR
916 normally dies if it cannot find an author in the p4 user map\&. This setting submits the change regardless\&.
917 .RE
918 .PP
919 git\-p4\&.skipSubmitEdit
920 .RS 4
921 The submit process invokes the editor before each p4 change is submitted\&. If this setting is true, though, the editing step is skipped\&.
922 .RE
923 .PP
924 git\-p4\&.skipSubmitEditCheck
925 .RS 4
926 After editing the p4 change message,
927 \fIgit p4\fR
928 makes sure that the description really was changed by looking at the file modification time\&. This option disables that test\&.
929 .RE
930 .PP
931 git\-p4\&.allowSubmit
932 .RS 4
933 By default, any branch can be used as the source for a
934 \fIgit p4 submit\fR
935 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\&.
936 .RE
937 .PP
938 git\-p4\&.skipUserNameCheck
939 .RS 4
940 If the user running
941 \fIgit p4 submit\fR
942 does not exist in the p4 user map,
943 \fIgit p4\fR
944 exits\&. This option can be used to force submission regardless\&.
945 .RE
946 .PP
947 git\-p4\&.attemptRCSCleanup
948 .RS 4
949 If enabled,
950 \fIgit p4 submit\fR
951 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\&.
952 .RE
953 .PP
954 git\-p4\&.exportLabels
955 .RS 4
956 Export Git tags to p4 labels, as per \-\-export\-labels\&.
957 .RE
958 .PP
959 git\-p4\&.labelExportRegexp
960 .RS 4
961 Only p4 labels matching this regular expression will be exported\&. The default value is
962 \fI[a\-zA\-Z0\-9_\e\-\&.]+$\fR\&.
963 .RE
964 .PP
965 git\-p4\&.conflict
966 .RS 4
967 Specify submit behavior when a conflict with p4 is found, as per \-\-conflict\&. The default behavior is
968 \fIask\fR\&.
969 .RE
970 .PP
971 git\-p4\&.disableRebase
972 .RS 4
973 Do not rebase the tree against p4/master following a submit\&.
974 .RE
975 .PP
976 git\-p4\&.disableP4Sync
977 .RS 4
978 Do not sync p4/master with Perforce following a submit\&. Implies git\-p4\&.disableRebase\&.
979 .RE
980 .SH "IMPLEMENTATION DETAILS"
981 .sp
982 .RS 4
983 .ie n \{\
984 \h'-04'\(bu\h'+03'\c
985 .\}
986 .el \{\
987 .sp -1
988 .IP \(bu 2.3
989 .\}
990 Changesets from p4 are imported using Git fast\-import\&.
991 .RE
992 .sp
993 .RS 4
994 .ie n \{\
995 \h'-04'\(bu\h'+03'\c
996 .\}
997 .el \{\
998 .sp -1
999 .IP \(bu 2.3
1000 .\}
1001 Cloning or syncing does not require a p4 client; file contents are collected using
1002 \fIp4 print\fR\&.
1003 .RE
1004 .sp
1005 .RS 4
1006 .ie n \{\
1007 \h'-04'\(bu\h'+03'\c
1008 .\}
1009 .el \{\
1010 .sp -1
1011 .IP \(bu 2.3
1012 .\}
1013 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\&.
1014 .RE
1015 .sp
1016 .RS 4
1017 .ie n \{\
1018 \h'-04'\(bu\h'+03'\c
1019 .\}
1020 .el \{\
1021 .sp -1
1022 .IP \(bu 2.3
1023 .\}
1024 Each commit imported by
1025 \fIgit p4\fR
1026 has a line at the end of the log message indicating the p4 depot location and change number\&. This line is used by later
1027 \fIgit p4 sync\fR
1028 operations to know which p4 changes are new\&.
1029 .RE
1030 .SH "GIT"
1031 .sp
1032 Part of the \fBgit\fR(1) suite