1git-p4(1) 2========= 3 4NAME 5---- 6git-p4 - Import from and submit to Perforce repositories 7 8 9SYNOPSIS 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 18DESCRIPTION 19----------- 20This command provides a way to interact with p4 repositories 21using Git. 22 23Create a new Git repository from an existing p4 repository using 24'git p4 clone', giving it one or more p4 depot paths. Incorporate 25new commits from p4 changes with 'git p4 sync'. The 'sync' command 26is also used to include new branches from other p4 depot paths. 27Submit Git changes back to p4 using 'git p4 submit'. The command 28'git p4 rebase' does a sync plus rebases the current branch onto 29the updated p4 remote branch. 30 31 32EXAMPLE 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 62COMMANDS 63-------- 64 65Clone 66~~~~~ 67Generally, 'git p4 clone' is used to create a new Git directory 68from an existing p4 repository: 69------------ 70$ git p4 clone //depot/path/project 71------------ 72This: 73 741. Creates an empty Git repository in a subdirectory called 'project'. 75+ 762. Imports the full contents of the head revision from the given p4 77depot path into a single commit in the Git branch 'refs/remotes/p4/master'. 78+ 793. Creates a local branch, 'master' from this remote and checks it out. 80 81To reproduce the entire p4 history in Git, use the '@all' modifier on 82the depot path: 83------------ 84$ git p4 clone //depot/path/project@all 85------------ 86 87 88Sync 89~~~~ 90As development continues in the p4 repository, those changes can 91be included in the Git repository using: 92------------ 93$ git p4 sync 94------------ 95This command finds new changes in p4 and imports them as Git commits. 96 97P4 repositories can be added to an existing Git repository using 98'git p4 sync' too: 99------------ 100$ mkdir repo-git 101$ cd repo-git 102$ git init 103$ git p4 sync //path/in/your/perforce/depot 104------------ 105This imports the specified depot into 106'refs/remotes/p4/master' in an existing Git repository. The 107'--branch' option can be used to specify a different branch to 108be used for the p4 content. 109 110If a Git repository includes branches 'refs/remotes/origin/p4', these 111will be fetched and consulted first during a 'git p4 sync'. Since 112importing directly from p4 is considerably slower than pulling changes 113from a Git remote, this can be useful in a multi-developer environment. 114 115If there are multiple branches, doing 'git p4 sync' will automatically 116use the "BRANCH DETECTION" algorithm to try to partition new changes 117into the right branch. This can be overridden with the '--branch' 118option to specify just a single branch to update. 119 120 121Rebase 122~~~~~~ 123A common working pattern is to fetch the latest changes from the p4 depot 124and merge them with local uncommitted changes. Often, the p4 repository 125is the ultimate location for all code, thus a rebase workflow makes 126sense. This command does 'git p4 sync' followed by 'git rebase' to move 127local commits on top of updated p4 changes. 128------------ 129$ git p4 rebase 130------------ 131 132 133Submit 134~~~~~~ 135Submitting changes from a Git repository back to the p4 repository 136requires a separate p4 client workspace. This should be specified 137using the 'P4CLIENT' environment variable or the Git configuration 138variable 'git-p4.client'. The p4 client must exist, but the client root 139will be created and populated if it does not already exist. 140 141To submit all changes that are in the current Git branch but not in 142the 'p4/master' branch, use: 143------------ 144$ git p4 submit 145------------ 146 147To specify a branch other than the current one, use: 148------------ 149$ git p4 submit topicbranch 150------------ 151 152The upstream reference is generally 'refs/remotes/p4/master', but can 153be overridden using the '--origin=' command-line option. 154 155The p4 changes will be created as the user invoking 'git p4 submit'. The 156'--preserve-user' option will cause ownership to be modified 157according to the author of the Git commit. This option requires admin 158privileges in p4, which can be granted using 'p4 protect'. 159 160 161OPTIONS 162------- 163 164General options 165~~~~~~~~~~~~~~~ 166All commands except clone accept these options. 167 168--git-dir <dir>:: 169 Set the 'GIT_DIR' environment variable. See linkgit:git[1]. 170 171-v:: 172--verbose:: 173 Provide more progress information. 174 175Sync options 176~~~~~~~~~~~~ 177These options can be used in the initial 'clone' as well as in 178subsequent 'sync' operations. 179 180--branch <ref>:: 181 Import changes into <ref> instead of refs/remotes/p4/master. 182 If <ref> starts with refs/, it is used as is. Otherwise, if 183 it does not start with p4/, that prefix is added. 184+ 185By default a <ref> not starting with refs/ is treated as the 186name of a remote-tracking branch (under refs/remotes/). This 187behavior can be modified using the --import-local option. 188+ 189The default <ref> is "master". 190+ 191This example imports a new remote "p4/proj2" into an existing 192Git repository: 193+ 194---- 195 $ git init 196 $ git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2 197---- 198 199--detect-branches:: 200 Use the branch detection algorithm to find new paths in p4. It is 201 documented below in "BRANCH DETECTION". 202 203--changesfile <file>:: 204 Import exactly the p4 change numbers listed in 'file', one per 205 line. Normally, 'git p4' inspects the current p4 repository 206 state and detects the changes it should import. 207 208--silent:: 209 Do not print any progress information. 210 211--detect-labels:: 212 Query p4 for labels associated with the depot paths, and add 213 them as tags in Git. Limited usefulness as only imports labels 214 associated with new changelists. Deprecated. 215 216--import-labels:: 217 Import labels from p4 into Git. 218 219--import-local:: 220 By default, p4 branches are stored in 'refs/remotes/p4/', 221 where they will be treated as remote-tracking branches by 222 linkgit:git-branch[1] and other commands. This option instead 223 puts p4 branches in 'refs/heads/p4/'. Note that future 224 sync operations must specify '--import-local' as well so that 225 they can find the p4 branches in refs/heads. 226 227--max-changes <n>:: 228 Limit the number of imported changes to 'n'. Useful to 229 limit the amount of history when using the '@all' p4 revision 230 specifier. 231 232--keep-path:: 233 The mapping of file names from the p4 depot path to Git, by 234 default, involves removing the entire depot path. With this 235 option, the full p4 depot path is retained in Git. For example, 236 path '//depot/main/foo/bar.c', when imported from 237 '//depot/main/', becomes 'foo/bar.c'. With '--keep-path', the 238 Git path is instead 'depot/main/foo/bar.c'. 239 240--use-client-spec:: 241 Use a client spec to find the list of interesting files in p4. 242 See the "CLIENT SPEC" section below. 243 244-/ <path>:: 245 Exclude selected depot paths when cloning or syncing. 246 247Clone options 248~~~~~~~~~~~~~ 249These options can be used in an initial 'clone', along with the 'sync' 250options described above. 251 252--destination <directory>:: 253 Where to create the Git repository. If not provided, the last 254 component in the p4 depot path is used to create a new 255 directory. 256 257--bare:: 258 Perform a bare clone. See linkgit:git-clone[1]. 259 260Submit options 261~~~~~~~~~~~~~~ 262These options can be used to modify 'git p4 submit' behavior. 263 264--origin <commit>:: 265 Upstream location from which commits are identified to submit to 266 p4. By default, this is the most recent p4 commit reachable 267 from 'HEAD'. 268 269-M:: 270 Detect renames. See linkgit:git-diff[1]. Renames will be 271 represented in p4 using explicit 'move' operations. There 272 is no corresponding option to detect copies, but there are 273 variables for both moves and copies. 274 275--preserve-user:: 276 Re-author p4 changes before submitting to p4. This option 277 requires p4 admin privileges. 278 279--export-labels:: 280 Export tags from Git as p4 labels. Tags found in Git are applied 281 to the perforce working directory. 282 283-n:: 284--dry-run:: 285 Show just what commits would be submitted to p4; do not change 286 state in Git or p4. 287 288--prepare-p4-only:: 289 Apply a commit to the p4 workspace, opening, adding and deleting 290 files in p4 as for a normal submit operation. Do not issue the 291 final "p4 submit", but instead print a message about how to 292 submit manually or revert. This option always stops after the 293 first (oldest) commit. Git tags are not exported to p4. 294 295--conflict=(ask|skip|quit):: 296 Conflicts can occur when applying a commit to p4. When this 297 happens, the default behavior ("ask") is to prompt whether to 298 skip this commit and continue, or quit. This option can be used 299 to bypass the prompt, causing conflicting commits to be automatically 300 skipped, or to quit trying to apply commits, without prompting. 301 302--branch <branch>:: 303 After submitting, sync this named branch instead of the default 304 p4/master. See the "Sync options" section above for more 305 information. 306 307Rebase options 308~~~~~~~~~~~~~~ 309These options can be used to modify 'git p4 rebase' behavior. 310 311--import-labels:: 312 Import p4 labels. 313 314DEPOT PATH SYNTAX 315----------------- 316The p4 depot path argument to 'git p4 sync' and 'git p4 clone' can 317be one or more space-separated p4 depot paths, with an optional 318p4 revision specifier on the end: 319 320"//depot/my/project":: 321 Import one commit with all files in the '#head' change under that tree. 322 323"//depot/my/project@all":: 324 Import one commit for each change in the history of that depot path. 325 326"//depot/my/project@1,6":: 327 Import only changes 1 through 6. 328 329"//depot/proj1@all //depot/proj2@all":: 330 Import all changes from both named depot paths into a single 331 repository. Only files below these directories are included. 332 There is not a subdirectory in Git for each "proj1" and "proj2". 333 You must use the '--destination' option when specifying more 334 than one depot path. The revision specifier must be specified 335 identically on each depot path. If there are files in the 336 depot paths with the same name, the path with the most recently 337 updated version of the file is the one that appears in Git. 338 339See 'p4 help revisions' for the full syntax of p4 revision specifiers. 340 341 342CLIENT SPEC 343----------- 344The p4 client specification is maintained with the 'p4 client' command 345and contains among other fields, a View that specifies how the depot 346is mapped into the client repository. The 'clone' and 'sync' commands 347can consult the client spec when given the '--use-client-spec' option or 348when the useClientSpec variable is true. After 'git p4 clone', the 349useClientSpec variable is automatically set in the repository 350configuration file. This allows future 'git p4 submit' commands to 351work properly; the submit command looks only at the variable and does 352not have a command-line option. 353 354The full syntax for a p4 view is documented in 'p4 help views'. 'git p4' 355knows only a subset of the view syntax. It understands multi-line 356mappings, overlays with '+', exclusions with '-' and double-quotes 357around whitespace. Of the possible wildcards, 'git p4' only handles 358'...', and only when it is at the end of the path. 'git p4' will complain 359if it encounters an unhandled wildcard. 360 361Bugs in the implementation of overlap mappings exist. If multiple depot 362paths map through overlays to the same location in the repository, 363'git p4' can choose the wrong one. This is hard to solve without 364dedicating a client spec just for 'git p4'. 365 366The name of the client can be given to 'git p4' in multiple ways. The 367variable 'git-p4.client' takes precedence if it exists. Otherwise, 368normal p4 mechanisms of determining the client are used: environment 369variable P4CLIENT, a file referenced by P4CONFIG, or the local host name. 370 371 372BRANCH DETECTION 373---------------- 374P4 does not have the same concept of a branch as Git. Instead, 375p4 organizes its content as a directory tree, where by convention 376different logical branches are in different locations in the tree. 377The 'p4 branch' command is used to maintain mappings between 378different areas in the tree, and indicate related content. 'git p4' 379can use these mappings to determine branch relationships. 380 381If you have a repository where all the branches of interest exist as 382subdirectories of a single depot path, you can use '--detect-branches' 383when cloning or syncing to have 'git p4' automatically find 384subdirectories in p4, and to generate these as branches in Git. 385 386For example, if the P4 repository structure is: 387---- 388//depot/main/... 389//depot/branch1/... 390---- 391 392And "p4 branch -o branch1" shows a View line that looks like: 393---- 394//depot/main/... //depot/branch1/... 395---- 396 397Then this 'git p4 clone' command: 398---- 399git p4 clone --detect-branches //depot@all 400---- 401produces a separate branch in 'refs/remotes/p4/' for //depot/main, 402called 'master', and one for //depot/branch1 called 'depot/branch1'. 403 404However, it is not necessary to create branches in p4 to be able to use 405them like branches. Because it is difficult to infer branch 406relationships automatically, a Git configuration setting 407'git-p4.branchList' can be used to explicitly identify branch 408relationships. It is a list of "source:destination" pairs, like a 409simple p4 branch specification, where the "source" and "destination" are 410the path elements in the p4 repository. The example above relied on the 411presence of the p4 branch. Without p4 branches, the same result will 412occur with: 413---- 414git init depot 415cd depot 416git config git-p4.branchList main:branch1 417git p4 clone --detect-branches //depot@all . 418---- 419 420 421PERFORMANCE 422----------- 423The fast-import mechanism used by 'git p4' creates one pack file for 424each invocation of 'git p4 sync'. Normally, Git garbage compression 425(linkgit:git-gc[1]) automatically compresses these to fewer pack files, 426but explicit invocation of 'git repack -adf' may improve performance. 427 428 429CONFIGURATION VARIABLES 430----------------------- 431The following config settings can be used to modify 'git p4' behavior. 432They all are in the 'git-p4' section. 433 434General variables 435~~~~~~~~~~~~~~~~~ 436git-p4.user:: 437 User specified as an option to all p4 commands, with '-u <user>'. 438 The environment variable 'P4USER' can be used instead. 439 440git-p4.password:: 441 Password specified as an option to all p4 commands, with 442 '-P <password>'. 443 The environment variable 'P4PASS' can be used instead. 444 445git-p4.port:: 446 Port specified as an option to all p4 commands, with 447 '-p <port>'. 448 The environment variable 'P4PORT' can be used instead. 449 450git-p4.host:: 451 Host specified as an option to all p4 commands, with 452 '-h <host>'. 453 The environment variable 'P4HOST' can be used instead. 454 455git-p4.client:: 456 Client specified as an option to all p4 commands, with 457 '-c <client>', including the client spec. 458 459Clone and sync variables 460~~~~~~~~~~~~~~~~~~~~~~~~ 461git-p4.syncFromOrigin:: 462 Because importing commits from other Git repositories is much faster 463 than importing them from p4, a mechanism exists to find p4 changes 464 first in Git remotes. If branches exist under 'refs/remote/origin/p4', 465 those will be fetched and used when syncing from p4. This 466 variable can be set to 'false' to disable this behavior. 467 468git-p4.branchUser:: 469 One phase in branch detection involves looking at p4 branches 470 to find new ones to import. By default, all branches are 471 inspected. This option limits the search to just those owned 472 by the single user named in the variable. 473 474git-p4.branchList:: 475 List of branches to be imported when branch detection is 476 enabled. Each entry should be a pair of branch names separated 477 by a colon (:). This example declares that both branchA and 478 branchB were created from main: 479+ 480------------- 481git config git-p4.branchList main:branchA 482git config --add git-p4.branchList main:branchB 483------------- 484 485git-p4.ignoredP4Labels:: 486 List of p4 labels to ignore. This is built automatically as 487 unimportable labels are discovered. 488 489git-p4.importLabels:: 490 Import p4 labels into git, as per --import-labels. 491 492git-p4.labelImportRegexp:: 493 Only p4 labels matching this regular expression will be imported. The 494 default value is '[a-zA-Z0-9_\-.]+$'. 495 496git-p4.useClientSpec:: 497 Specify that the p4 client spec should be used to identify p4 498 depot paths of interest. This is equivalent to specifying the 499 option '--use-client-spec'. See the "CLIENT SPEC" section above. 500 This variable is a boolean, not the name of a p4 client. 501 502Submit variables 503~~~~~~~~~~~~~~~~ 504git-p4.detectRenames:: 505 Detect renames. See linkgit:git-diff[1]. This can be true, 506 false, or a score as expected by 'git diff -M'. 507 508git-p4.detectCopies:: 509 Detect copies. See linkgit:git-diff[1]. This can be true, 510 false, or a score as expected by 'git diff -C'. 511 512git-p4.detectCopiesHarder:: 513 Detect copies harder. See linkgit:git-diff[1]. A boolean. 514 515git-p4.preserveUser:: 516 On submit, re-author changes to reflect the Git author, 517 regardless of who invokes 'git p4 submit'. 518 519git-p4.allowMissingP4Users:: 520 When 'preserveUser' is true, 'git p4' normally dies if it 521 cannot find an author in the p4 user map. This setting 522 submits the change regardless. 523 524git-p4.skipSubmitEdit:: 525 The submit process invokes the editor before each p4 change 526 is submitted. If this setting is true, though, the editing 527 step is skipped. 528 529git-p4.skipSubmitEditCheck:: 530 After editing the p4 change message, 'git p4' makes sure that 531 the description really was changed by looking at the file 532 modification time. This option disables that test. 533 534git-p4.allowSubmit:: 535 By default, any branch can be used as the source for a 'git p4 536 submit' operation. This configuration variable, if set, permits only 537 the named branches to be used as submit sources. Branch names 538 must be the short names (no "refs/heads/"), and should be 539 separated by commas (","), with no spaces. 540 541git-p4.skipUserNameCheck:: 542 If the user running 'git p4 submit' does not exist in the p4 543 user map, 'git p4' exits. This option can be used to force 544 submission regardless. 545 546git-p4.attemptRCSCleanup:: 547 If enabled, 'git p4 submit' will attempt to cleanup RCS keywords 548 ($Header$, etc). These would otherwise cause merge conflicts and prevent 549 the submit going ahead. This option should be considered experimental at 550 present. 551 552git-p4.exportLabels:: 553 Export Git tags to p4 labels, as per --export-labels. 554 555git-p4.labelExportRegexp:: 556 Only p4 labels matching this regular expression will be exported. The 557 default value is '[a-zA-Z0-9_\-.]+$'. 558 559git-p4.conflict:: 560 Specify submit behavior when a conflict with p4 is found, as per 561 --conflict. The default behavior is 'ask'. 562 563IMPLEMENTATION DETAILS 564---------------------- 565* Changesets from p4 are imported using Git fast-import. 566* Cloning or syncing does not require a p4 client; file contents are 567 collected using 'p4 print'. 568* Submitting requires a p4 client, which is not in the same location 569 as the Git repository. Patches are applied, one at a time, to 570 this p4 client and submitted from there. 571* Each commit imported by 'git p4' has a line at the end of the log 572 message indicating the p4 depot location and change number. This 573 line is used by later 'git p4 sync' operations to know which p4 574 changes are new.