logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

git-p4.1 (32811B)


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