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