@matheusbsbs / matheus-bagliano / commits / 6679c34c47

git-p4: introduce asciidoc documentation

Add proper documentation for git-p4. Delete the old .txt documentation from contrib/fast-import. Cc: Frans Klaver <fransklaver@gmail.com> Cc: Luke Diamand <luke@diamand.org> Signed-off-by: Pete Wyckoff <pw@padd.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Pete Wyckoff committed Dec 24, 2011 at 21:07 UTC 6679c34c47be19ba8e9ea72129dfe768a49c5ab4
2 files changed +455 -302
Documentation/git-p4.txt new
+455
@@ -0,0 +1,455 @@
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/'
181 + will be prepended. The default branch is 'master'.
182 +
183 +--detect-branches::
184 + Use the branch detection algorithm to find new paths in p4. It is
185 + documented below in "BRANCH DETECTION".
186 +
187 +--changesfile <file>::
188 + Import exactly the p4 change numbers listed in 'file', one per
189 + line. Normally, 'git p4' inspects the current p4 repository
190 + state and detects the changes it should import.
191 +
192 +--silent::
193 + Do not print any progress information.
194 +
195 +--verbose::
196 + Provide more progress information.
197 +
198 +--detect-labels::
199 + Query p4 for labels associated with the depot paths, and add
200 + them as tags in git.
201 +
202 +--import-local::
203 + By default, p4 branches are stored in 'refs/remotes/p4/',
204 + where they will be treated as remote-tracking branches by
205 + linkgit:git-branch[1] and other commands. This option instead
206 + puts p4 branches in 'refs/heads/p4/'.
207 +
208 +--max-changes <n>::
209 + Limit the number of imported changes to 'n'. Useful to
210 + limit the amount of history when using the '@all' p4 revision
211 + specifier.
212 +
213 +--keep-path::
214 + The mapping of file names from the p4 depot path to git, by
215 + default, involves removing the entire depot path. With this
216 + option, the full p4 depot path is retained in git. For example,
217 + path '//depot/main/foo/bar.c', when imported from
218 + '//depot/main/', becomes 'foo/bar.c'. With '--keep-path', the
219 + git path is instead 'depot/main/foo/bar.c'.
220 +
221 +--use-client-spec::
222 + Use a client spec to find the list of interesting files in p4.
223 + The client spec is discovered using 'p4 client -o' which checks
224 + the 'P4CLIENT' environment variable and returns a mapping of
225 + depot files to workspace files.
226 +
227 +Clone options
228 +~~~~~~~~~~~~~
229 +These options can be used in an initial 'clone', along with the 'sync'
230 +options described above.
231 +
232 +--destination <directory>::
233 + Where to create the git repository. If not provided, the last
234 + component in the p4 depot path is used to create a new
235 + directory.
236 +
237 +--bare::
238 + Perform a bare clone. See linkgit:git-clone[1].
239 +
240 +-/ <path>::
241 + Exclude selected depot paths when cloning.
242 +
243 +Submit options
244 +~~~~~~~~~~~~~~
245 +These options can be used to modify 'git p4 submit' behavior.
246 +
247 +--verbose::
248 + Provide more progress information.
249 +
250 +--origin <commit>::
251 + Upstream location from which commits are identified to submit to
252 + p4. By default, this is the most recent p4 commit reachable
253 + from 'HEAD'.
254 +
255 +-M[<n>]::
256 + Detect renames. See linkgit:git-diff[1]. Renames will be
257 + represented in p4 using explicit 'move' operations.
258 +
259 +--preserve-user::
260 + Re-author p4 changes before submitting to p4. This option
261 + requires p4 admin privileges.
262 +
263 +
264 +DEPOT PATH SYNTAX
265 +-----------------
266 +The p4 depot path argument to 'git p4 sync' and 'git p4 clone' can
267 +be one or more space-separated p4 depot paths, with an optional
268 +p4 revision specifier on the end:
269 +
270 +"//depot/my/project"::
271 + Import one commit with all files in the '#head' change under that tree.
272 +
273 +"//depot/my/project@all"::
274 + Import one commit for each change in the history of that depot path.
275 +
276 +"//depot/my/project@1,6"::
277 + Import only changes 1 through 6.
278 +
279 +"//depot/proj1 //depot/proj2@all"::
280 + Import all changes from both named depot paths.
281 +
282 +See 'p4 help revisions' for the full syntax of p4 revision specifiers.
283 +
284 +
285 +BRANCH DETECTION
286 +----------------
287 +P4 does not have the same concept of a branch as git. Instead,
288 +p4 organizes its content as a directory tree, where by convention
289 +different logical branches are in different locations in the tree.
290 +The 'p4 branch' command is used to maintain mappings between
291 +different areas in the tree, and indicate related content. 'git p4'
292 +can use these mappings to determine branch relationships.
293 +
294 +If you have a repository where all the branches of interest exist as
295 +subdirectories of a single depot path, you can use '--detect-branches'
296 +when cloning or syncing to have 'git p4' automatically find
297 +subdirectories in p4, and to generate these as branches in git.
298 +
299 +For example, if the P4 repository structure is:
300 +----
301 +//depot/main/...
302 +//depot/branch1/...
303 +----
304 +
305 +And "p4 branch -o branch1" shows a View line that looks like:
306 +----
307 +//depot/main/... //depot/branch1/...
308 +----
309 +
310 +Then this 'git p4 clone' command:
311 +----
312 +git p4 clone --detect-branches //depot@all
313 +----
314 +produces a separate branch in 'refs/remotes/p4/' for //depot/main,
315 +called 'master', and one for //depot/branch1 called 'depot/branch1'.
316 +
317 +However, it is not necessary to create branches in p4 to be able to use
318 +them like branches. Because it is difficult to infer branch
319 +relationships automatically, a git configuration setting
320 +'git-p4.branchList' can be used to explicitly identify branch
321 +relationships. It is a list of "source:destination" pairs, like a
322 +simple p4 branch specification, where the "source" and "destination" are
323 +the path elements in the p4 repository. The example above relied on the
324 +presence of the p4 branch. Without p4 branches, the same result will
325 +occur with:
326 +----
327 +git config git-p4.branchList main:branch1
328 +git p4 clone --detect-branches //depot@all
329 +----
330 +
331 +
332 +PERFORMANCE
333 +-----------
334 +The fast-import mechanism used by 'git p4' creates one pack file for
335 +each invocation of 'git p4 sync'. Normally, git garbage compression
336 +(linkgit:git-gc[1]) automatically compresses these to fewer pack files,
337 +but explicit invocation of 'git repack -adf' may improve performance.
338 +
339 +
340 +CONFIGURATION VARIABLES
341 +-----------------------
342 +The following config settings can be used to modify 'git p4' behavior.
343 +They all are in the 'git-p4' section.
344 +
345 +General variables
346 +~~~~~~~~~~~~~~~~~
347 +git-p4.user::
348 + User specified as an option to all p4 commands, with '-u <user>'.
349 + The environment variable 'P4USER' can be used instead.
350 +
351 +git-p4.password::
352 + Password specified as an option to all p4 commands, with
353 + '-P <password>'.
354 + The environment variable 'P4PASS' can be used instead.
355 +
356 +git-p4.port::
357 + Port specified as an option to all p4 commands, with
358 + '-p <port>'.
359 + The environment variable 'P4PORT' can be used instead.
360 +
361 +git-p4.host::
362 + Host specified as an option to all p4 commands, with
363 + '-h <host>'.
364 + The environment variable 'P4HOST' can be used instead.
365 +
366 +git-p4.client::
367 + Client specified as an option to all p4 commands, with
368 + '-c <client>'. This can also be used as a way to find
369 + the client spec for the 'useClientSpec' option.
370 + The environment variable 'P4CLIENT' can be used instead.
371 +
372 +Clone and sync variables
373 +~~~~~~~~~~~~~~~~~~~~~~~~
374 +git-p4.syncFromOrigin::
375 + Because importing commits from other git repositories is much faster
376 + than importing them from p4, a mechanism exists to find p4 changes
377 + first in git remotes. If branches exist under 'refs/remote/origin/p4',
378 + those will be fetched and used when syncing from p4. This
379 + variable can be set to 'false' to disable this behavior.
380 +
381 +git-p4.branchUser::
382 + One phase in branch detection involves looking at p4 branches
383 + to find new ones to import. By default, all branches are
384 + inspected. This option limits the search to just those owned
385 + by the single user named in the variable.
386 +
387 +git-p4.branchList::
388 + List of branches to be imported when branch detection is
389 + enabled. Each entry should be a pair of branch names separated
390 + by a colon (:). This example declares that both branchA and
391 + branchB were created from main:
392 +-------------
393 +git config git-p4.branchList main:branchA
394 +git config --add git-p4.branchList main:branchB
395 +-------------
396 +
397 +git-p4.useClientSpec::
398 + Specify that the p4 client spec to be used to identify p4 depot
399 + paths of interest. This is equivalent to specifying the option
400 + '--use-client-spec'. The variable 'git-p4.client' can be used
401 + to specify the name of the client.
402 +
403 +Submit variables
404 +~~~~~~~~~~~~~~~~
405 +git-p4.detectRenames::
406 + Detect renames. See linkgit:git-diff[1].
407 +
408 +git-p4.detectCopies::
409 + Detect copies. See linkgit:git-diff[1].
410 +
411 +git-p4.detectCopiesHarder::
412 + Detect copies harder. See linkgit:git-diff[1].
413 +
414 +git-p4.preserveUser::
415 + On submit, re-author changes to reflect the git author,
416 + regardless of who invokes 'git p4 submit'.
417 +
418 +git-p4.allowMissingP4Users::
419 + When 'preserveUser' is true, 'git p4' normally dies if it
420 + cannot find an author in the p4 user map. This setting
421 + submits the change regardless.
422 +
423 +git-p4.skipSubmitEdit::
424 + The submit process invokes the editor before each p4 change
425 + is submitted. If this setting is true, though, the editing
426 + step is skipped.
427 +
428 +git-p4.skipSubmitEditCheck::
429 + After editing the p4 change message, 'git p4' makes sure that
430 + the description really was changed by looking at the file
431 + modification time. This option disables that test.
432 +
433 +git-p4.allowSubmit::
434 + By default, any branch can be used as the source for a 'git p4
435 + submit' operation. This configuration variable, if set, permits only
436 + the named branches to be used as submit sources.
437 +
438 +git-p4.skipUserNameCheck::
439 + If the user running 'git p4 submit' does not exist in the p4
440 + user map, 'git p4' exits. This option can be used to force
441 + submission regardless.
442 +
443 +
444 +IMPLEMENTATION DETAILS
445 +----------------------
446 +* Changesets from p4 are imported using git fast-import.
447 +* Cloning or syncing does not require a p4 client; file contents are
448 + collected using 'p4 print'.
449 +* Submitting requires a p4 client, which is not in the same location
450 + as the git repository. Patches are applied, one at a time, to
451 + this p4 client and submitted from there.
452 +* Each commit imported by 'git p4' has a line at the end of the log
453 + message indicating the p4 depot location and change number. This
454 + line is used by later 'git p4 sync' operations to know which p4
455 + changes are new.
contrib/fast-import/git-p4.txt deleted
-302
@@ -1,302 +0,0 @@
1 -git-p4 - Perforce <-> Git converter using git-fast-import
2 -
3 -Usage
4 -=====
5 -
6 -git-p4 can be used in two different ways:
7 -
8 -1) To import changes from Perforce to a Git repository, using "git-p4 sync".
9 -
10 -2) To submit changes from Git back to Perforce, using "git-p4 submit".
11 -
12 -Importing
13 -=========
14 -
15 -Simply start with
16 -
17 - git-p4 clone //depot/path/project
18 -
19 -or
20 -
21 - git-p4 clone //depot/path/project myproject
22 -
23 -This will:
24 -
25 -1) Create an empty git repository in a subdirectory called "project" (or
26 -"myproject" with the second command)
27 -
28 -2) Import the head revision from the given Perforce path into a git branch
29 -called "p4" (remotes/p4 actually)
30 -
31 -3) Create a master branch based on it and check it out.
32 -
33 -If you want the entire history (not just the head revision) then you can simply
34 -append a "@all" to the depot path:
35 -
36 - git-p4 clone //depot/project/main@all myproject
37 -
38 -
39 -
40 -If you want more control you can also use the git-p4 sync command directly:
41 -
42 - mkdir repo-git
43 - cd repo-git
44 - git init
45 - git-p4 sync //path/in/your/perforce/depot
46 -
47 -This will import the current head revision of the specified depot path into a
48 -"remotes/p4/master" branch of your git repository. You can use the
49 ---branch=mybranch option to import into a different branch.
50 -
51 -If you want to import the entire history of a given depot path simply use:
52 -
53 - git-p4 sync //path/in/depot@all
54 -
55 -
56 -Note:
57 -
58 -To achieve optimal compression you may want to run 'git repack -a -d -f' after
59 -a big import. This may take a while.
60 -
61 -Incremental Imports
62 -===================
63 -
64 -After an initial import you can continue to synchronize your git repository
65 -with newer changes from the Perforce depot by just calling
66 -
67 - git-p4 sync
68 -
69 -in your git repository. By default the "remotes/p4/master" branch is updated.
70 -
71 -Advanced Setup
72 -==============
73 -
74 -Suppose you have a periodically updated git repository somewhere, containing a
75 -complete import of a Perforce project. This repository can be cloned and used
76 -with git-p4. When updating the cloned repository with the "sync" command,
77 -git-p4 will try to fetch changes from the original repository first. The git
78 -protocol used with this is usually faster than importing from Perforce
79 -directly.
80 -
81 -This behaviour can be disabled by setting the "git-p4.syncFromOrigin" git
82 -configuration variable to "false".
83 -
84 -Updating
85 -========
86 -
87 -A common working pattern is to fetch the latest changes from the Perforce depot
88 -and merge them with local uncommitted changes. The recommended way is to use
89 -git's rebase mechanism to preserve linear history. git-p4 provides a convenient
90 -
91 - git-p4 rebase
92 -
93 -command that calls git-p4 sync followed by git rebase to rebase the current
94 -working branch.
95 -
96 -Submitting
97 -==========
98 -
99 -git-p4 has support for submitting changes from a git repository back to the
100 -Perforce depot. This requires a Perforce checkout separate from your git
101 -repository. To submit all changes that are in the current git branch but not in
102 -the "p4" branch (or "origin" if "p4" doesn't exist) simply call
103 -
104 - git-p4 submit
105 -
106 -in your git repository. If you want to submit changes in a specific branch that
107 -is not your current git branch you can also pass that as an argument:
108 -
109 - git-p4 submit mytopicbranch
110 -
111 -You can override the reference branch with the --origin=mysourcebranch option.
112 -
113 -The Perforce changelists will be created with the user who ran git-p4. If you
114 -use --preserve-user then git-p4 will attempt to create Perforce changelists
115 -with the Perforce user corresponding to the git commit author. You need to
116 -have sufficient permissions within Perforce, and the git users need to have
117 -Perforce accounts. Permissions can be granted using 'p4 protect'.
118 -
119 -If a submit fails you may have to "p4 resolve" and submit manually. You can
120 -continue importing the remaining changes with
121 -
122 - git-p4 submit --continue
123 -
124 -Example
125 -=======
126 -
127 -# Clone a repository
128 - git-p4 clone //depot/path/project
129 -# Enter the newly cloned directory
130 - cd project
131 -# Do some work...
132 - vi foo.h
133 -# ... and commit locally to gi
134 - git commit foo.h
135 -# In the meantime somebody submitted changes to the Perforce depot. Rebase your latest
136 -# changes against the latest changes in Perforce:
137 - git-p4 rebase
138 -# Submit your locally committed changes back to Perforce
139 - git-p4 submit
140 -# ... and synchronize with Perforce
141 - git-p4 rebase
142 -
143 -
144 -Configuration parameters
145 -========================
146 -
147 -git-p4.user ($P4USER)
148 -
149 -Allows you to specify the username to use to connect to the Perforce repository.
150 -
151 - git config [--global] git-p4.user public
152 -
153 -git-p4.password ($P4PASS)
154 -
155 -Allows you to specify the password to use to connect to the Perforce repository.
156 -Warning this password will be visible on the command-line invocation of the p4 binary.
157 -
158 - git config [--global] git-p4.password public1234
159 -
160 -git-p4.port ($P4PORT)
161 -
162 -Specify the port to be used to contact the Perforce server. As this will be passed
163 -directly to the p4 binary, it may be in the format host:port as well.
164 -
165 - git config [--global] git-p4.port codes.zimbra.com:2666
166 -
167 -git-p4.host ($P4HOST)
168 -
169 -Specify the host to contact for a Perforce repository.
170 -
171 - git config [--global] git-p4.host perforce.example.com
172 -
173 -git-p4.client ($P4CLIENT)
174 -
175 -Specify the client name to use
176 -
177 - git config [--global] git-p4.client public-view
178 -
179 -git-p4.allowSubmit
180 -
181 - git config [--global] git-p4.allowSubmit false
182 -
183 -git-p4.syncFromOrigin
184 -
185 -A useful setup may be that you have a periodically updated git repository
186 -somewhere that contains a complete import of a Perforce project. That git
187 -repository can be used to clone the working repository from and one would
188 -import from Perforce directly after cloning using git-p4. If the connection to
189 -the Perforce server is slow and the working repository hasn't been synced for a
190 -while it may be desirable to fetch changes from the origin git repository using
191 -the efficient git protocol. git-p4 supports this setup by calling "git fetch origin"
192 -by default if there is an origin branch. You can disable this using:
193 -
194 - git config [--global] git-p4.syncFromOrigin false
195 -
196 -git-p4.useclientspec
197 -
198 - git config [--global] git-p4.useclientspec false
199 -
200 -The P4CLIENT environment variable should be correctly set for p4 to be
201 -able to find the relevant client. This client spec will be used to
202 -both filter the files cloned by git and set the directory layout as
203 -specified in the client (this implies --keep-path style semantics).
204 -
205 -git-p4.skipSubmitEdit
206 -
207 - git config [--global] git-p4.skipSubmitEdit false
208 -
209 -Normally, git-p4 invokes an editor after each commit is applied so
210 -that you can make changes to the submit message. Setting this
211 -variable to true will skip the editing step, submitting the change as is.
212 -
213 -git-p4.skipSubmitEditCheck
214 -
215 - git config [--global] git-p4.skipSubmitEditCheck false
216 -
217 -After the editor is invoked, git-p4 normally makes sure you saved the
218 -change description, as an indication that you did indeed read it over
219 -and edit it. You can quit without saving to abort the submit (or skip
220 -this change and continue). Setting this variable to true will cause
221 -git-p4 not to check if you saved the change description. This variable
222 -only matters if git-p4.skipSubmitEdit has not been set to true.
223 -
224 -git-p4.preserveUser
225 -
226 - git config [--global] git-p4.preserveUser false
227 -
228 -If true, attempt to preserve user names by modifying the p4 changelists. See
229 -the "--preserve-user" submit option.
230 -
231 -git-p4.allowMissingPerforceUsers
232 -
233 - git config [--global] git-p4.allowMissingP4Users false
234 -
235 -If git-p4 is setting the perforce user for a commit (--preserve-user) then
236 -if there is no perforce user corresponding to the git author, git-p4 will
237 -stop. With allowMissingPerforceUsers set to true, git-p4 will use the
238 -current user (i.e. the behavior without --preserve-user) and carry on with
239 -the perforce commit.
240 -
241 -git-p4.skipUserNameCheck
242 -
243 - git config [--global] git-p4.skipUserNameCheck false
244 -
245 -When submitting, git-p4 checks that the git commits are authored by the current
246 -p4 user, and warns if they are not. This disables the check.
247 -
248 -git-p4.detectRenames
249 -
250 -Detect renames when submitting changes to Perforce server. Will enable -M git
251 -argument. Can be optionally set to a number representing the threshold
252 -percentage value of the rename detection.
253 -
254 - git config [--global] git-p4.detectRenames true
255 - git config [--global] git-p4.detectRenames 50
256 -
257 -git-p4.detectCopies
258 -
259 -Detect copies when submitting changes to Perforce server. Will enable -C git
260 -argument. Can be optionally set to a number representing the threshold
261 -percentage value of the copy detection.
262 -
263 - git config [--global] git-p4.detectCopies true
264 - git config [--global] git-p4.detectCopies 80
265 -
266 -git-p4.detectCopiesHarder
267 -
268 -Detect copies even between files that did not change when submitting changes to
269 -Perforce server. Will enable --find-copies-harder git argument.
270 -
271 - git config [--global] git-p4.detectCopies true
272 -
273 -git-p4.branchUser
274 -
275 -Only use branch specifications defined by the selected username.
276 -
277 - git config [--global] git-p4.branchUser username
278 -
279 -git-p4.branchList
280 -
281 -List of branches to be imported when branch detection is enabled.
282 -
283 - git config [--global] git-p4.branchList main:branchA
284 - git config [--global] --add git-p4.branchList main:branchB
285 -
286 -Implementation Details...
287 -=========================
288 -
289 -* Changesets from Perforce are imported using git fast-import.
290 -* The import does not require anything from the Perforce client view as it just uses
291 - "p4 print //depot/path/file#revision" to get the actual file contents.
292 -* Every imported changeset has a special [git-p4...] line at the
293 - end of the log message that gives information about the corresponding
294 - Perforce change number and is also used by git-p4 itself to find out
295 - where to continue importing when doing incremental imports.
296 - Basically when syncing it extracts the perforce change number of the
297 - latest commit in the "p4" branch and uses "p4 changes //depot/path/...@changenum,#head"
298 - to find out which changes need to be imported.
299 -* git-p4 submit uses "git rev-list" to pick the commits between the "p4" branch
300 - and the current branch.
301 - The commits themselves are applied using git diff/format-patch ... | git apply
302 -