man1/git-p4.1

   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-05-17
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.41.0.rc0.4.g004e0f790f
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-P4" "1" "2023\-05\-17" "Git 2\&.41\&.0\&.rc0\&.4\&.g00" "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