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