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