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