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