Google Git
Sign in
chromium / external / gitster / git-htmldocs / db472bc17bfef8588e1a8f6ce873e5c6f4fa384a / . / git-p4.html
blob: d3f809ad6c53cfa3e726d3e5f60195c395ead57e [file] [log] [blame]
Junio C Hamanodb472bc2012-01-04 00:22:37[diff] [blame^]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
6<meta name="generator" content="AsciiDoc 8.5.2" />
7<title>git-p4(1)</title>
8<style type="text/css">
9/* Debug borders */
10p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
11/*
12 border: 1px solid red;
13*/
14}
15
16body {
17 margin: 1em 5% 1em 5%;
18}
19
20a {
21 color: blue;
22 text-decoration: underline;
23}
24a:visited {
25 color: fuchsia;
26}
27
28em {
29 font-style: italic;
30 color: navy;
31}
32
33strong {
34 font-weight: bold;
35 color: #083194;
36}
37
38tt {
39 color: navy;
40}
41
42h1, h2, h3, h4, h5, h6 {
43 color: #527bbd;
44 font-family: sans-serif;
45 margin-top: 1.2em;
46 margin-bottom: 0.5em;
47 line-height: 1.3;
48}
49
50h1, h2, h3 {
51 border-bottom: 2px solid silver;
52}
53h2 {
54 padding-top: 0.5em;
55}
56h3 {
57 float: left;
58}
59h3 + * {
60 clear: left;
61}
62
63div.sectionbody {
64 font-family: serif;
65 margin-left: 0;
66}
67
68hr {
69 border: 1px solid silver;
70}
71
72p {
73 margin-top: 0.5em;
74 margin-bottom: 0.5em;
75}
76
77ul, ol, li > p {
78 margin-top: 0;
79}
80
81pre {
82 padding: 0;
83 margin: 0;
84}
85
86span#author {
87 color: #527bbd;
88 font-family: sans-serif;
89 font-weight: bold;
90 font-size: 1.1em;
91}
92span#email {
93}
94span#revnumber, span#revdate, span#revremark {
95 font-family: sans-serif;
96}
97
98div#footer {
99 font-family: sans-serif;
100 font-size: small;
101 border-top: 2px solid silver;
102 padding-top: 0.5em;
103 margin-top: 4.0em;
104}
105div#footer-text {
106 float: left;
107 padding-bottom: 0.5em;
108}
109div#footer-badges {
110 float: right;
111 padding-bottom: 0.5em;
112}
113
114div#preamble {
115 margin-top: 1.5em;
116 margin-bottom: 1.5em;
117}
118div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120div.admonitionblock {
121 margin-top: 1.0em;
122 margin-bottom: 1.5em;
123}
124div.admonitionblock {
125 margin-top: 2.0em;
126 margin-bottom: 2.0em;
127 margin-right: 10%;
128 color: #606060;
129}
130
131div.content { /* Block element content. */
132 padding: 0;
133}
134
135/* Block element titles. */
136div.title, caption.title {
137 color: #527bbd;
138 font-family: sans-serif;
139 font-weight: bold;
140 text-align: left;
141 margin-top: 1.0em;
142 margin-bottom: 0.5em;
143}
144div.title + * {
145 margin-top: 0;
146}
147
148td div.title:first-child {
149 margin-top: 0.0em;
150}
151div.content div.title:first-child {
152 margin-top: 0.0em;
153}
154div.content + div.title {
155 margin-top: 0.0em;
156}
157
158div.sidebarblock > div.content {
159 background: #ffffee;
160 border: 1px solid silver;
161 padding: 0.5em;
162}
163
164div.listingblock > div.content {
165 border: 1px solid silver;
166 background: #f4f4f4;
167 padding: 0.5em;
168}
169
170div.quoteblock, div.verseblock {
171 padding-left: 1.0em;
172 margin-left: 1.0em;
173 margin-right: 10%;
174 border-left: 5px solid #dddddd;
175 color: #777777;
176}
177
178div.quoteblock > div.attribution {
179 padding-top: 0.5em;
180 text-align: right;
181}
182
183div.verseblock > div.content {
184 white-space: pre;
185}
186div.verseblock > div.attribution {
187 padding-top: 0.75em;
188 text-align: left;
189}
190/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
191div.verseblock + div.attribution {
192 text-align: left;
193}
194
195div.admonitionblock .icon {
196 vertical-align: top;
197 font-size: 1.1em;
198 font-weight: bold;
199 text-decoration: underline;
200 color: #527bbd;
201 padding-right: 0.5em;
202}
203div.admonitionblock td.content {
204 padding-left: 0.5em;
205 border-left: 3px solid #dddddd;
206}
207
208div.exampleblock > div.content {
209 border-left: 3px solid #dddddd;
210 padding-left: 0.5em;
211}
212
213div.imageblock div.content { padding-left: 0; }
214span.image img { border-style: none; }
215a.image:visited { color: white; }
216
217dl {
218 margin-top: 0.8em;
219 margin-bottom: 0.8em;
220}
221dt {
222 margin-top: 0.5em;
223 margin-bottom: 0;
224 font-style: normal;
225 color: navy;
226}
227dd > *:first-child {
228 margin-top: 0.1em;
229}
230
231ul, ol {
232 list-style-position: outside;
233}
234ol.arabic {
235 list-style-type: decimal;
236}
237ol.loweralpha {
238 list-style-type: lower-alpha;
239}
240ol.upperalpha {
241 list-style-type: upper-alpha;
242}
243ol.lowerroman {
244 list-style-type: lower-roman;
245}
246ol.upperroman {
247 list-style-type: upper-roman;
248}
249
250div.compact ul, div.compact ol,
251div.compact p, div.compact p,
252div.compact div, div.compact div {
253 margin-top: 0.1em;
254 margin-bottom: 0.1em;
255}
256
257div.tableblock > table {
258 border: 3px solid #527bbd;
259}
260thead, p.table.header {
261 font-family: sans-serif;
262 font-weight: bold;
263}
264tfoot {
265 font-weight: bold;
266}
267td > div.verse {
268 white-space: pre;
269}
270p.table {
271 margin-top: 0;
272}
273/* Because the table frame attribute is overriden by CSS in most browsers. */
274div.tableblock > table[frame="void"] {
275 border-style: none;
276}
277div.tableblock > table[frame="hsides"] {
278 border-left-style: none;
279 border-right-style: none;
280}
281div.tableblock > table[frame="vsides"] {
282 border-top-style: none;
283 border-bottom-style: none;
284}
285
286
287div.hdlist {
288 margin-top: 0.8em;
289 margin-bottom: 0.8em;
290}
291div.hdlist tr {
292 padding-bottom: 15px;
293}
294dt.hdlist1.strong, td.hdlist1.strong {
295 font-weight: bold;
296}
297td.hdlist1 {
298 vertical-align: top;
299 font-style: normal;
300 padding-right: 0.8em;
301 color: navy;
302}
303td.hdlist2 {
304 vertical-align: top;
305}
306div.hdlist.compact tr {
307 margin: 0;
308 padding-bottom: 0;
309}
310
311.comment {
312 background: yellow;
313}
314
315.footnote, .footnoteref {
316 font-size: 0.8em;
317}
318
319span.footnote, span.footnoteref {
320 vertical-align: super;
321}
322
323#footnotes {
324 margin: 20px 0 20px 0;
325 padding: 7px 0 0 0;
326}
327
328#footnotes div.footnote {
329 margin: 0 0 5px 0;
330}
331
332#footnotes hr {
333 border: none;
334 border-top: 1px solid silver;
335 height: 1px;
336 text-align: left;
337 margin-left: 0;
338 width: 20%;
339 min-width: 100px;
340}
341
342
343@media print {
344 div#footer-badges { display: none; }
345}
346
347div#toc {
348 margin-bottom: 2.5em;
349}
350
351div#toctitle {
352 color: #527bbd;
353 font-family: sans-serif;
354 font-size: 1.1em;
355 font-weight: bold;
356 margin-top: 1.0em;
357 margin-bottom: 0.1em;
358}
359
360div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
361 margin-top: 0;
362 margin-bottom: 0;
363}
364div.toclevel2 {
365 margin-left: 2em;
366 font-size: 0.9em;
367}
368div.toclevel3 {
369 margin-left: 4em;
370 font-size: 0.9em;
371}
372div.toclevel4 {
373 margin-left: 6em;
374 font-size: 0.9em;
375}
376/* Overrides for manpage documents */
377h1 {
378 padding-top: 0.5em;
379 padding-bottom: 0.5em;
380 border-top: 2px solid silver;
381 border-bottom: 2px solid silver;
382}
383h2 {
384 border-style: none;
385}
386div.sectionbody {
387 margin-left: 5%;
388}
389
390@media print {
391 div#toc { display: none; }
392}
393
394/* Workarounds for IE6's broken and incomplete CSS2. */
395
396div.sidebar-content {
397 background: #ffffee;
398 border: 1px solid silver;
399 padding: 0.5em;
400}
401div.sidebar-title, div.image-title {
402 color: #527bbd;
403 font-family: sans-serif;
404 font-weight: bold;
405 margin-top: 0.0em;
406 margin-bottom: 0.5em;
407}
408
409div.listingblock div.content {
410 border: 1px solid silver;
411 background: #f4f4f4;
412 padding: 0.5em;
413}
414
415div.quoteblock-attribution {
416 padding-top: 0.5em;
417 text-align: right;
418}
419
420div.verseblock-content {
421 white-space: pre;
422}
423div.verseblock-attribution {
424 padding-top: 0.75em;
425 text-align: left;
426}
427
428div.exampleblock-content {
429 border-left: 3px solid #dddddd;
430 padding-left: 0.5em;
431}
432
433/* IE6 sets dynamically generated links as visited. */
434div#toc a:visited { color: blue; }
435</style>
436<script type="text/javascript">
437/*<![CDATA[*/
438window.onload = function(){asciidoc.footnotes();}
439var asciidoc = { // Namespace.
440
441/////////////////////////////////////////////////////////////////////
442// Table Of Contents generator
443/////////////////////////////////////////////////////////////////////
444
445/* Author: Mihai Bazon, September 2002
446 * http://students.infoiasi.ro/~mishoo
447 *
448 * Table Of Content generator
449 * Version: 0.4
450 *
451 * Feel free to use this script under the terms of the GNU General Public
452 * License, as long as you do not remove or alter this notice.
453 */
454
455 /* modified by Troy D. Hanson, September 2006. License: GPL */
456 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
457
458// toclevels = 1..4.
459toc: function (toclevels) {
460
461 function getText(el) {
462 var text = "";
463 for (var i = el.firstChild; i != null; i = i.nextSibling) {
464 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
465 text += i.data;
466 else if (i.firstChild != null)
467 text += getText(i);
468 }
469 return text;
470 }
471
472 function TocEntry(el, text, toclevel) {
473 this.element = el;
474 this.text = text;
475 this.toclevel = toclevel;
476 }
477
478 function tocEntries(el, toclevels) {
479 var result = new Array;
480 var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
481 // Function that scans the DOM tree for header elements (the DOM2
482 // nodeIterator API would be a better technique but not supported by all
483 // browsers).
484 var iterate = function (el) {
485 for (var i = el.firstChild; i != null; i = i.nextSibling) {
486 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
487 var mo = re.exec(i.tagName);
488 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
489 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
490 }
491 iterate(i);
492 }
493 }
494 }
495 iterate(el);
496 return result;
497 }
498
499 var toc = document.getElementById("toc");
500 var entries = tocEntries(document.getElementById("content"), toclevels);
501 for (var i = 0; i < entries.length; ++i) {
502 var entry = entries[i];
503 if (entry.element.id == "")
504 entry.element.id = "_toc_" + i;
505 var a = document.createElement("a");
506 a.href = "#" + entry.element.id;
507 a.appendChild(document.createTextNode(entry.text));
508 var div = document.createElement("div");
509 div.appendChild(a);
510 div.className = "toclevel" + entry.toclevel;
511 toc.appendChild(div);
512 }
513 if (entries.length == 0)
514 toc.parentNode.removeChild(toc);
515},
516
517
518/////////////////////////////////////////////////////////////////////
519// Footnotes generator
520/////////////////////////////////////////////////////////////////////
521
522/* Based on footnote generation code from:
523 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
524 */
525
526footnotes: function () {
527 var cont = document.getElementById("content");
528 var noteholder = document.getElementById("footnotes");
529 var spans = cont.getElementsByTagName("span");
530 var refs = {};
531 var n = 0;
532 for (i=0; i<spans.length; i++) {
533 if (spans[i].className == "footnote") {
534 n++;
535 // Use [\s\S] in place of . so multi-line matches work.
536 // Because JavaScript has no s (dotall) regex flag.
537 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
538 noteholder.innerHTML +=
539 "<div class='footnote' id='_footnote_" + n + "'>" +
540 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
541 n + "</a>. " + note + "</div>";
542 spans[i].innerHTML =
543 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
544 "' title='View footnote' class='footnote'>" + n + "</a>]";
545 var id =spans[i].getAttribute("id");
546 if (id != null) refs["#"+id] = n;
547 }
548 }
549 if (n == 0)
550 noteholder.parentNode.removeChild(noteholder);
551 else {
552 // Process footnoterefs.
553 for (i=0; i<spans.length; i++) {
554 if (spans[i].className == "footnoteref") {
555 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
556 href = href.match(/#.*/)[0]; // Because IE return full URL.
557 n = refs[href];
558 spans[i].innerHTML =
559 "[<a href='#_footnote_" + n +
560 "' title='View footnote' class='footnote'>" + n + "</a>]";
561 }
562 }
563 }
564}
565
566}
567/*]]>*/
568</script>
569</head>
570<body>
571<div id="header">
572<h1>
573git-p4(1) Manual Page
574</h1>
575<h2>NAME</h2>
576<div class="sectionbody">
577<p>git-p4 -
578 Import from and submit to Perforce repositories
579</p>
580</div>
581</div>
582<div id="content">
583<h2 id="_synopsis">SYNOPSIS</h2>
584<div class="sectionbody">
585<div class="verseblock">
586<div class="verseblock-content"><em>git p4 clone</em> [&lt;sync options&gt;] [&lt;clone options&gt;] &lt;p4 depot path&gt;&#8230;
587<em>git p4 sync</em> [&lt;sync options&gt;] [&lt;p4 depot path&gt;&#8230;]
588<em>git p4 rebase</em>
589<em>git p4 submit</em> [&lt;submit options&gt;] [&lt;master branch name&gt;]</div>
590<div class="verseblock-attribution">
591</div></div>
592</div>
593<h2 id="_description">DESCRIPTION</h2>
594<div class="sectionbody">
595<div class="paragraph"><p>This command provides a way to interact with p4 repositories
596using git.</p></div>
597<div class="paragraph"><p>Create a new git repository from an existing p4 repository using
598<em>git p4 clone</em>, giving it one or more p4 depot paths. Incorporate
599new commits from p4 changes with <em>git p4 sync</em>. The <em>sync</em> command
600is also used to include new branches from other p4 depot paths.
601Submit git changes back to p4 using <em>git p4 submit</em>. The command
602<em>git p4 rebase</em> does a sync plus rebases the current branch onto
603the updated p4 remote branch.</p></div>
604</div>
605<h2 id="_example">EXAMPLE</h2>
606<div class="sectionbody">
607<div class="ulist"><ul>
608<li>
609<p>
610Create an alias for <em>git p4</em>, using the full path to the <em>git-p4</em>
611 script if needed:
612</p>
613<div class="listingblock">
614<div class="content">
615<pre><tt>$ git config --global alias.p4 '!git-p4'</tt></pre>
616</div></div>
617</li>
618<li>
619<p>
620Clone a repository:
621</p>
622<div class="listingblock">
623<div class="content">
624<pre><tt>$ git p4 clone //depot/path/project</tt></pre>
625</div></div>
626</li>
627<li>
628<p>
629Do some work in the newly created git repository:
630</p>
631<div class="listingblock">
632<div class="content">
633<pre><tt>$ cd project
634$ vi foo.h
635$ git commit -a -m "edited foo.h"</tt></pre>
636</div></div>
637</li>
638<li>
639<p>
640Update the git repository with recent changes from p4, rebasing your
641 work on top:
642</p>
643<div class="listingblock">
644<div class="content">
645<pre><tt>$ git p4 rebase</tt></pre>
646</div></div>
647</li>
648<li>
649<p>
650Submit your commits back to p4:
651</p>
652<div class="listingblock">
653<div class="content">
654<pre><tt>$ git p4 submit</tt></pre>
655</div></div>
656</li>
657</ul></div>
658</div>
659<h2 id="_commands">COMMANDS</h2>
660<div class="sectionbody">
661<h3 id="_clone">Clone</h3><div style="clear:left"></div>
662<div class="paragraph"><p>Generally, <em>git p4 clone</em> is used to create a new git directory
663from an existing p4 repository:</p></div>
664<div class="listingblock">
665<div class="content">
666<pre><tt>$ git p4 clone //depot/path/project</tt></pre>
667</div></div>
668<div class="paragraph"><p>This:</p></div>
669<div class="olist arabic"><ol class="arabic">
670<li>
671<p>
672Creates an empty git repository in a subdirectory called <em>project</em>.
673</p>
674</li>
675<li>
676<p>
677Imports the full contents of the head revision from the given p4
678depot path into a single commit in the git branch <em>refs/remotes/p4/master</em>.
679</p>
680</li>
681<li>
682<p>
683Creates a local branch, <em>master</em> from this remote and checks it out.
684</p>
685</li>
686</ol></div>
687<div class="paragraph"><p>To reproduce the entire p4 history in git, use the <em>@all</em> modifier on
688the depot path:</p></div>
689<div class="listingblock">
690<div class="content">
691<pre><tt>$ git p4 clone //depot/path/project@all</tt></pre>
692</div></div>
693<h3 id="_sync">Sync</h3><div style="clear:left"></div>
694<div class="paragraph"><p>As development continues in the p4 repository, those changes can
695be included in the git repository using:</p></div>
696<div class="listingblock">
697<div class="content">
698<pre><tt>$ git p4 sync</tt></pre>
699</div></div>
700<div class="paragraph"><p>This command finds new changes in p4 and imports them as git commits.</p></div>
701<div class="paragraph"><p>P4 repositories can be added to an existing git repository using
702<em>git p4 sync</em> too:</p></div>
703<div class="listingblock">
704<div class="content">
705<pre><tt>$ mkdir repo-git
706$ cd repo-git
707$ git init
708$ git p4 sync //path/in/your/perforce/depot</tt></pre>
709</div></div>
710<div class="paragraph"><p>This imports the specified depot into
711<em>refs/remotes/p4/master</em> in an existing git repository. The
712<em>--branch</em> option can be used to specify a different branch to
713be used for the p4 content.</p></div>
714<div class="paragraph"><p>If a git repository includes branches <em>refs/remotes/origin/p4</em>, these
715will be fetched and consulted first during a <em>git p4 sync</em>. Since
716importing directly from p4 is considerably slower than pulling changes
717from a git remote, this can be useful in a multi-developer environment.</p></div>
718<h3 id="_rebase">Rebase</h3><div style="clear:left"></div>
719<div class="paragraph"><p>A common working pattern is to fetch the latest changes from the p4 depot
720and merge them with local uncommitted changes. Often, the p4 repository
721is the ultimate location for all code, thus a rebase workflow makes
722sense. This command does <em>git p4 sync</em> followed by <em>git rebase</em> to move
723local commits on top of updated p4 changes.</p></div>
724<div class="listingblock">
725<div class="content">
726<pre><tt>$ git p4 rebase</tt></pre>
727</div></div>
728<h3 id="_submit">Submit</h3><div style="clear:left"></div>
729<div class="paragraph"><p>Submitting changes from a git repository back to the p4 repository
730requires a separate p4 client workspace. This should be specified
731using the <em>P4CLIENT</em> environment variable or the git configuration
732variable <em>git-p4.client</em>. The p4 client must exist, but the client root
733will be created and populated if it does not already exist.</p></div>
734<div class="paragraph"><p>To submit all changes that are in the current git branch but not in
735the <em>p4/master</em> branch, use:</p></div>
736<div class="listingblock">
737<div class="content">
738<pre><tt>$ git p4 submit</tt></pre>
739</div></div>
740<div class="paragraph"><p>To specify a branch other than the current one, use:</p></div>
741<div class="listingblock">
742<div class="content">
743<pre><tt>$ git p4 submit topicbranch</tt></pre>
744</div></div>
745<div class="paragraph"><p>The upstream reference is generally <em>refs/remotes/p4/master</em>, but can
746be overridden using the <em>--origin=</em> command-line option.</p></div>
747<div class="paragraph"><p>The p4 changes will be created as the user invoking <em>git p4 submit</em>. The
748<em>--preserve-user</em> option will cause ownership to be modified
749according to the author of the git commit. This option requires admin
750privileges in p4, which can be granted using <em>p4 protect</em>.</p></div>
751</div>
752<h2 id="_options">OPTIONS</h2>
753<div class="sectionbody">
754<h3 id="_general_options">General options</h3><div style="clear:left"></div>
755<div class="paragraph"><p>All commands except clone accept this option.</p></div>
756<div class="dlist"><dl>
757<dt class="hdlist1">
758--git-dir &lt;dir&gt;
759</dt>
760<dd>
761<p>
762 Set the <em>GIT_DIR</em> environment variable. See <a href="git.html">git(1)</a>.
763</p>
764</dd>
765</dl></div>
766<h3 id="_sync_options">Sync options</h3><div style="clear:left"></div>
767<div class="paragraph"><p>These options can be used in the initial <em>clone</em> as well as in
768subsequent <em>sync</em> operations.</p></div>
769<div class="dlist"><dl>
770<dt class="hdlist1">
771--branch &lt;branch&gt;
772</dt>
773<dd>
774<p>
775 Import changes into given branch. If the branch starts with
776 <em>refs/</em>, it will be used as is, otherwise the path <em>refs/heads/</em>
777 will be prepended. The default branch is <em>master</em>. If used
778 with an initial clone, no HEAD will be checked out.
779</p>
780<div class="paragraph"><p>This example imports a new remote "p4/proj2" into an existing
781git repository:</p></div>
782</dd>
783</dl></div>
784<div class="listingblock">
785<div class="content">
786<pre><tt> $ git init
787 $ git p4 sync --branch=refs/remotes/p4/proj2 //depot/proj2</tt></pre>
788</div></div>
789<div class="dlist"><dl>
790<dt class="hdlist1">
791--detect-branches
792</dt>
793<dd>
794<p>
795 Use the branch detection algorithm to find new paths in p4. It is
796 documented below in "BRANCH DETECTION".
797</p>
798</dd>
799<dt class="hdlist1">
800--changesfile &lt;file&gt;
801</dt>
802<dd>
803<p>
804 Import exactly the p4 change numbers listed in <em>file</em>, one per
805 line. Normally, <em>git p4</em> inspects the current p4 repository
806 state and detects the changes it should import.
807</p>
808</dd>
809<dt class="hdlist1">
810--silent
811</dt>
812<dd>
813<p>
814 Do not print any progress information.
815</p>
816</dd>
817<dt class="hdlist1">
818--verbose
819</dt>
820<dd>
821<p>
822 Provide more progress information.
823</p>
824</dd>
825<dt class="hdlist1">
826--detect-labels
827</dt>
828<dd>
829<p>
830 Query p4 for labels associated with the depot paths, and add
831 them as tags in git.
832</p>
833</dd>
834<dt class="hdlist1">
835--import-local
836</dt>
837<dd>
838<p>
839 By default, p4 branches are stored in <em>refs/remotes/p4/</em>,
840 where they will be treated as remote-tracking branches by
841 <a href="git-branch.html">git-branch(1)</a> and other commands. This option instead
842 puts p4 branches in <em>refs/heads/p4/</em>. Note that future
843 sync operations must specify <em>--import-local</em> as well so that
844 they can find the p4 branches in refs/heads.
845</p>
846</dd>
847<dt class="hdlist1">
848--max-changes &lt;n&gt;
849</dt>
850<dd>
851<p>
852 Limit the number of imported changes to <em>n</em>. Useful to
853 limit the amount of history when using the <em>@all</em> p4 revision
854 specifier.
855</p>
856</dd>
857<dt class="hdlist1">
858--keep-path
859</dt>
860<dd>
861<p>
862 The mapping of file names from the p4 depot path to git, by
863 default, involves removing the entire depot path. With this
864 option, the full p4 depot path is retained in git. For example,
865 path <em>//depot/main/foo/bar.c</em>, when imported from
866 <em>//depot/main/</em>, becomes <em>foo/bar.c</em>. With <em>--keep-path</em>, the
867 git path is instead <em>depot/main/foo/bar.c</em>.
868</p>
869</dd>
870<dt class="hdlist1">
871--use-client-spec
872</dt>
873<dd>
874<p>
875 Use a client spec to find the list of interesting files in p4.
876 The client spec is discovered using <em>p4 client -o</em> which checks
877 the <em>P4CLIENT</em> environment variable and returns a mapping of
878 depot files to workspace files. Note that a depot path is
879 still required, but files found in the path that match in
880 the client spec view will be laid out according to the client
881 spec.
882</p>
883</dd>
884</dl></div>
885<h3 id="_clone_options">Clone options</h3><div style="clear:left"></div>
886<div class="paragraph"><p>These options can be used in an initial <em>clone</em>, along with the <em>sync</em>
887options described above.</p></div>
888<div class="dlist"><dl>
889<dt class="hdlist1">
890--destination &lt;directory&gt;
891</dt>
892<dd>
893<p>
894 Where to create the git repository. If not provided, the last
895 component in the p4 depot path is used to create a new
896 directory.
897</p>
898</dd>
899<dt class="hdlist1">
900--bare
901</dt>
902<dd>
903<p>
904 Perform a bare clone. See <a href="git-clone.html">git-clone(1)</a>.
905</p>
906</dd>
907<dt class="hdlist1">
908-/ &lt;path&gt;
909</dt>
910<dd>
911<p>
912 Exclude selected depot paths when cloning.
913</p>
914</dd>
915</dl></div>
916<h3 id="_submit_options">Submit options</h3><div style="clear:left"></div>
917<div class="paragraph"><p>These options can be used to modify <em>git p4 submit</em> behavior.</p></div>
918<div class="dlist"><dl>
919<dt class="hdlist1">
920--verbose
921</dt>
922<dd>
923<p>
924 Provide more progress information.
925</p>
926</dd>
927<dt class="hdlist1">
928--origin &lt;commit&gt;
929</dt>
930<dd>
931<p>
932 Upstream location from which commits are identified to submit to
933 p4. By default, this is the most recent p4 commit reachable
934 from <em>HEAD</em>.
935</p>
936</dd>
937<dt class="hdlist1">
938-M[&lt;n&gt;]
939</dt>
940<dd>
941<p>
942 Detect renames. See <a href="git-diff.html">git-diff(1)</a>. Renames will be
943 represented in p4 using explicit <em>move</em> operations. There
944 is no corresponding option to detect copies, but there are
945 variables for both moves and copies.
946</p>
947</dd>
948<dt class="hdlist1">
949--preserve-user
950</dt>
951<dd>
952<p>
953 Re-author p4 changes before submitting to p4. This option
954 requires p4 admin privileges.
955</p>
956</dd>
957</dl></div>
958</div>
959<h2 id="_depot_path_syntax">DEPOT PATH SYNTAX</h2>
960<div class="sectionbody">
961<div class="paragraph"><p>The p4 depot path argument to <em>git p4 sync</em> and <em>git p4 clone</em> can
962be one or more space-separated p4 depot paths, with an optional
963p4 revision specifier on the end:</p></div>
964<div class="dlist"><dl>
965<dt class="hdlist1">
966"//depot/my/project"
967</dt>
968<dd>
969<p>
970 Import one commit with all files in the <em>#head</em> change under that tree.
971</p>
972</dd>
973<dt class="hdlist1">
974"//depot/my/project@all"
975</dt>
976<dd>
977<p>
978 Import one commit for each change in the history of that depot path.
979</p>
980</dd>
981<dt class="hdlist1">
982"//depot/my/project@1,6"
983</dt>
984<dd>
985<p>
986 Import only changes 1 through 6.
987</p>
988</dd>
989<dt class="hdlist1">
990"//depot/proj1@all //depot/proj2@all"
991</dt>
992<dd>
993<p>
994 Import all changes from both named depot paths into a single
995 repository. Only files below these directories are included.
996 There is not a subdirectory in git for each "proj1" and "proj2".
997 You must use the <em>--destination</em> option when specifying more
998 than one depot path. The revision specifier must be specified
999 identically on each depot path. If there are files in the
1000 depot paths with the same name, the path with the most recently
1001 updated version of the file is the one that appears in git.
1002</p>
1003</dd>
1004</dl></div>
1005<div class="paragraph"><p>See <em>p4 help revisions</em> for the full syntax of p4 revision specifiers.</p></div>
1006</div>
1007<h2 id="_branch_detection">BRANCH DETECTION</h2>
1008<div class="sectionbody">
1009<div class="paragraph"><p>P4 does not have the same concept of a branch as git. Instead,
1010p4 organizes its content as a directory tree, where by convention
1011different logical branches are in different locations in the tree.
1012The <em>p4 branch</em> command is used to maintain mappings between
1013different areas in the tree, and indicate related content. <em>git p4</em>
1014can use these mappings to determine branch relationships.</p></div>
1015<div class="paragraph"><p>If you have a repository where all the branches of interest exist as
1016subdirectories of a single depot path, you can use <em>--detect-branches</em>
1017when cloning or syncing to have <em>git p4</em> automatically find
1018subdirectories in p4, and to generate these as branches in git.</p></div>
1019<div class="paragraph"><p>For example, if the P4 repository structure is:</p></div>
1020<div class="listingblock">
1021<div class="content">
1022<pre><tt>//depot/main/...
1023//depot/branch1/...</tt></pre>
1024</div></div>
1025<div class="paragraph"><p>And "p4 branch -o branch1" shows a View line that looks like:</p></div>
1026<div class="listingblock">
1027<div class="content">
1028<pre><tt>//depot/main/... //depot/branch1/...</tt></pre>
1029</div></div>
1030<div class="paragraph"><p>Then this <em>git p4 clone</em> command:</p></div>
1031<div class="listingblock">
1032<div class="content">
1033<pre><tt>git p4 clone --detect-branches //depot@all</tt></pre>
1034</div></div>
1035<div class="paragraph"><p>produces a separate branch in <em>refs/remotes/p4/</em> for //depot/main,
1036called <em>master</em>, and one for //depot/branch1 called <em>depot/branch1</em>.</p></div>
1037<div class="paragraph"><p>However, it is not necessary to create branches in p4 to be able to use
1038them like branches. Because it is difficult to infer branch
1039relationships automatically, a git configuration setting
1040<em>git-p4.branchList</em> can be used to explicitly identify branch
1041relationships. It is a list of "source:destination" pairs, like a
1042simple p4 branch specification, where the "source" and "destination" are
1043the path elements in the p4 repository. The example above relied on the
1044presence of the p4 branch. Without p4 branches, the same result will
1045occur with:</p></div>
1046<div class="listingblock">
1047<div class="content">
1048<pre><tt>git config git-p4.branchList main:branch1
1049git p4 clone --detect-branches //depot@all</tt></pre>
1050</div></div>
1051</div>
1052<h2 id="_performance">PERFORMANCE</h2>
1053<div class="sectionbody">
1054<div class="paragraph"><p>The fast-import mechanism used by <em>git p4</em> creates one pack file for
1055each invocation of <em>git p4 sync</em>. Normally, git garbage compression
1056(<a href="git-gc.html">git-gc(1)</a>) automatically compresses these to fewer pack files,
1057but explicit invocation of <em>git repack -adf</em> may improve performance.</p></div>
1058</div>
1059<h2 id="_configuration_variables">CONFIGURATION VARIABLES</h2>
1060<div class="sectionbody">
1061<div class="paragraph"><p>The following config settings can be used to modify <em>git p4</em> behavior.
1062They all are in the <em>git-p4</em> section.</p></div>
1063<h3 id="_general_variables">General variables</h3><div style="clear:left"></div>
1064<div class="dlist"><dl>
1065<dt class="hdlist1">
1066git-p4.user
1067</dt>
1068<dd>
1069<p>
1070 User specified as an option to all p4 commands, with <em>-u &lt;user&gt;</em>.
1071 The environment variable <em>P4USER</em> can be used instead.
1072</p>
1073</dd>
1074<dt class="hdlist1">
1075git-p4.password
1076</dt>
1077<dd>
1078<p>
1079 Password specified as an option to all p4 commands, with
1080 <em>-P &lt;password&gt;</em>.
1081 The environment variable <em>P4PASS</em> can be used instead.
1082</p>
1083</dd>
1084<dt class="hdlist1">
1085git-p4.port
1086</dt>
1087<dd>
1088<p>
1089 Port specified as an option to all p4 commands, with
1090 <em>-p &lt;port&gt;</em>.
1091 The environment variable <em>P4PORT</em> can be used instead.
1092</p>
1093</dd>
1094<dt class="hdlist1">
1095git-p4.host
1096</dt>
1097<dd>
1098<p>
1099 Host specified as an option to all p4 commands, with
1100 <em>-h &lt;host&gt;</em>.
1101 The environment variable <em>P4HOST</em> can be used instead.
1102</p>
1103</dd>
1104<dt class="hdlist1">
1105git-p4.client
1106</dt>
1107<dd>
1108<p>
1109 Client specified as an option to all p4 commands, with
1110 <em>-c &lt;client&gt;</em>. This can also be used as a way to find
1111 the client spec for the <em>useClientSpec</em> option.
1112 The environment variable <em>P4CLIENT</em> can be used instead.
1113</p>
1114</dd>
1115</dl></div>
1116<h3 id="_clone_and_sync_variables">Clone and sync variables</h3><div style="clear:left"></div>
1117<div class="dlist"><dl>
1118<dt class="hdlist1">
1119git-p4.syncFromOrigin
1120</dt>
1121<dd>
1122<p>
1123 Because importing commits from other git repositories is much faster
1124 than importing them from p4, a mechanism exists to find p4 changes
1125 first in git remotes. If branches exist under <em>refs/remote/origin/p4</em>,
1126 those will be fetched and used when syncing from p4. This
1127 variable can be set to <em>false</em> to disable this behavior.
1128</p>
1129</dd>
1130<dt class="hdlist1">
1131git-p4.branchUser
1132</dt>
1133<dd>
1134<p>
1135 One phase in branch detection involves looking at p4 branches
1136 to find new ones to import. By default, all branches are
1137 inspected. This option limits the search to just those owned
1138 by the single user named in the variable.
1139</p>
1140</dd>
1141<dt class="hdlist1">
1142git-p4.branchList
1143</dt>
1144<dd>
1145<p>
1146 List of branches to be imported when branch detection is
1147 enabled. Each entry should be a pair of branch names separated
1148 by a colon (:). This example declares that both branchA and
1149 branchB were created from main:
1150</p>
1151</dd>
1152</dl></div>
1153<div class="listingblock">
1154<div class="content">
1155<pre><tt>git config git-p4.branchList main:branchA
1156git config --add git-p4.branchList main:branchB</tt></pre>
1157</div></div>
1158<div class="dlist"><dl>
1159<dt class="hdlist1">
1160git-p4.useClientSpec
1161</dt>
1162<dd>
1163<p>
1164 Specify that the p4 client spec to be used to identify p4 depot
1165 paths of interest. This is equivalent to specifying the option
1166 <em>--use-client-spec</em>. The variable <em>git-p4.client</em> can be used
1167 to specify the name of the client.
1168</p>
1169</dd>
1170</dl></div>
1171<h3 id="_submit_variables">Submit variables</h3><div style="clear:left"></div>
1172<div class="dlist"><dl>
1173<dt class="hdlist1">
1174git-p4.detectRenames
1175</dt>
1176<dd>
1177<p>
1178 Detect renames. See <a href="git-diff.html">git-diff(1)</a>.
1179</p>
1180</dd>
1181<dt class="hdlist1">
1182git-p4.detectCopies
1183</dt>
1184<dd>
1185<p>
1186 Detect copies. See <a href="git-diff.html">git-diff(1)</a>.
1187</p>
1188</dd>
1189<dt class="hdlist1">
1190git-p4.detectCopiesHarder
1191</dt>
1192<dd>
1193<p>
1194 Detect copies harder. See <a href="git-diff.html">git-diff(1)</a>.
1195</p>
1196</dd>
1197<dt class="hdlist1">
1198git-p4.preserveUser
1199</dt>
1200<dd>
1201<p>
1202 On submit, re-author changes to reflect the git author,
1203 regardless of who invokes <em>git p4 submit</em>.
1204</p>
1205</dd>
1206<dt class="hdlist1">
1207git-p4.allowMissingP4Users
1208</dt>
1209<dd>
1210<p>
1211 When <em>preserveUser</em> is true, <em>git p4</em> normally dies if it
1212 cannot find an author in the p4 user map. This setting
1213 submits the change regardless.
1214</p>
1215</dd>
1216<dt class="hdlist1">
1217git-p4.skipSubmitEdit
1218</dt>
1219<dd>
1220<p>
1221 The submit process invokes the editor before each p4 change
1222 is submitted. If this setting is true, though, the editing
1223 step is skipped.
1224</p>
1225</dd>
1226<dt class="hdlist1">
1227git-p4.skipSubmitEditCheck
1228</dt>
1229<dd>
1230<p>
1231 After editing the p4 change message, <em>git p4</em> makes sure that
1232 the description really was changed by looking at the file
1233 modification time. This option disables that test.
1234</p>
1235</dd>
1236<dt class="hdlist1">
1237git-p4.allowSubmit
1238</dt>
1239<dd>
1240<p>
1241 By default, any branch can be used as the source for a <em>git p4
1242 submit</em> operation. This configuration variable, if set, permits only
1243 the named branches to be used as submit sources. Branch names
1244 must be the short names (no "refs/heads/"), and should be
1245 separated by commas (","), with no spaces.
1246</p>
1247</dd>
1248<dt class="hdlist1">
1249git-p4.skipUserNameCheck
1250</dt>
1251<dd>
1252<p>
1253 If the user running <em>git p4 submit</em> does not exist in the p4
1254 user map, <em>git p4</em> exits. This option can be used to force
1255 submission regardless.
1256</p>
1257</dd>
1258</dl></div>
1259</div>
1260<h2 id="_implementation_details">IMPLEMENTATION DETAILS</h2>
1261<div class="sectionbody">
1262<div class="ulist"><ul>
1263<li>
1264<p>
1265Changesets from p4 are imported using git fast-import.
1266</p>
1267</li>
1268<li>
1269<p>
1270Cloning or syncing does not require a p4 client; file contents are
1271 collected using <em>p4 print</em>.
1272</p>
1273</li>
1274<li>
1275<p>
1276Submitting requires a p4 client, which is not in the same location
1277 as the git repository. Patches are applied, one at a time, to
1278 this p4 client and submitted from there.
1279</p>
1280</li>
1281<li>
1282<p>
1283Each commit imported by <em>git p4</em> has a line at the end of the log
1284 message indicating the p4 depot location and change number. This
1285 line is used by later <em>git p4 sync</em> operations to know which p4
1286 changes are new.
1287</p>
1288</li>
1289</ul></div>
1290</div>
1291</div>
1292<div id="footnotes"><hr /></div>
1293<div id="footer">
1294<div id="footer-text">
1295Last updated 2012-01-03 16:22:22 PDT
1296</div>
1297</div>
1298</body>
1299</html>