git-p4import.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
   4 <head>\r
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />\r
   6 <meta name="generator" content="AsciiDoc 7.0.2" />\r
   7 <style type="text/css">\r
   8 /* Debug borders */\r
   9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {\r
  10 /*\r
  11   border: 1px solid red;\r
  12 */\r
  13 }\r
  14 \r
  15 body {\r
  16   margin: 1em 5% 1em 5%;\r
  17 }\r
  18 \r
  19 a { color: blue; }\r
  20 a:visited { color: fuchsia; }\r
  21 \r
  22 em {\r
  23   font-style: italic;\r
  24 }\r
  25 \r
  26 strong {\r
  27   font-weight: bold;\r
  28 }\r
  29 \r
  30 tt {\r
  31   color: navy;\r
  32 }\r
  33 \r
  34 h1, h2, h3, h4, h5, h6 {\r
  35   color: #527bbd;\r
  36   font-family: sans-serif;\r
  37   margin-top: 1.2em;\r
  38   margin-bottom: 0.5em;\r
  39   line-height: 1.3;\r
  40 }\r
  41 \r
  42 h1 {\r
  43   border-bottom: 2px solid silver;\r
  44 }\r
  45 h2 {\r
  46   border-bottom: 2px solid silver;\r
  47   padding-top: 0.5em;\r
  48 }\r
  49 \r
  50 div.sectionbody {\r
  51   font-family: serif;\r
  52   margin-left: 0;\r
  53 }\r
  54 \r
  55 hr {\r
  56   border: 1px solid silver;\r
  57 }\r
  58 \r
  59 p {\r
  60   margin-top: 0.5em;\r
  61   margin-bottom: 0.5em;\r
  62 }\r
  63 \r
  64 pre {\r
  65   padding: 0;\r
  66   margin: 0;\r
  67 }\r
  68 \r
  69 span#author {\r
  70   color: #527bbd;\r
  71   font-family: sans-serif;\r
  72   font-weight: bold;\r
  73   font-size: 1.2em;\r
  74 }\r
  75 span#email {\r
  76 }\r
  77 span#revision {\r
  78   font-family: sans-serif;\r
  79 }\r
  80 \r
  81 div#footer {\r
  82   font-family: sans-serif;\r
  83   font-size: small;\r
  84   border-top: 2px solid silver;\r
  85   padding-top: 0.5em;\r
  86   margin-top: 4.0em;\r
  87 }\r
  88 div#footer-text {\r
  89   float: left;\r
  90   padding-bottom: 0.5em;\r
  91 }\r
  92 div#footer-badges {\r
  93   float: right;\r
  94   padding-bottom: 0.5em;\r
  95 }\r
  96 \r
  97 div#preamble,\r
  98 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,\r
  99 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,\r
 100 div.admonitionblock {\r
 101   margin-right: 10%;\r
 102   margin-top: 1.5em;\r
 103   margin-bottom: 1.5em;\r
 104 }\r
 105 div.admonitionblock {\r
 106   margin-top: 2.5em;\r
 107   margin-bottom: 2.5em;\r
 108 }\r
 109 \r
 110 div.content { /* Block element content. */\r
 111   padding: 0;\r
 112 }\r
 113 \r
 114 /* Block element titles. */\r
 115 div.title, caption.title {\r
 116   font-family: sans-serif;\r
 117   font-weight: bold;\r
 118   text-align: left;\r
 119   margin-top: 1.0em;\r
 120   margin-bottom: 0.5em;\r
 121 }\r
 122 div.title + * {\r
 123   margin-top: 0;\r
 124 }\r
 125 \r
 126 td div.title:first-child {\r
 127   margin-top: 0.0em;\r
 128 }\r
 129 div.content div.title:first-child {\r
 130   margin-top: 0.0em;\r
 131 }\r
 132 div.content + div.title {\r
 133   margin-top: 0.0em;\r
 134 }\r
 135 \r
 136 div.sidebarblock > div.content {\r
 137   background: #ffffee;\r
 138   border: 1px solid silver;\r
 139   padding: 0.5em;\r
 140 }\r
 141 \r
 142 div.listingblock > div.content {\r
 143   border: 1px solid silver;\r
 144   background: #f4f4f4;\r
 145   padding: 0.5em;\r
 146 }\r
 147 \r
 148 div.quoteblock > div.content {\r
 149   padding-left: 2.0em;\r
 150 }\r
 151 div.quoteblock .attribution {\r
 152   text-align: right;\r
 153 }\r
 154 \r
 155 div.admonitionblock .icon {\r
 156   vertical-align: top;\r
 157   font-size: 1.1em;\r
 158   font-weight: bold;\r
 159   text-decoration: underline;\r
 160   color: #527bbd;\r
 161   padding-right: 0.5em;\r
 162 }\r
 163 div.admonitionblock td.content {\r
 164   padding-left: 0.5em;\r
 165   border-left: 2px solid silver;\r
 166 }\r
 167 \r
 168 div.exampleblock > div.content {\r
 169   border-left: 2px solid silver;\r
 170   padding: 0.5em;\r
 171 }\r
 172 \r
 173 div.verseblock div.content {\r
 174   white-space: pre;\r
 175 }\r
 176 \r
 177 div.imageblock div.content { padding-left: 0; }\r
 178 div.imageblock img { border: 1px solid silver; }\r
 179 span.image img { border-style: none; }\r
 180 \r
 181 dl {\r
 182   margin-top: 0.8em;\r
 183   margin-bottom: 0.8em;\r
 184 }\r
 185 dt {\r
 186   margin-top: 0.5em;\r
 187   margin-bottom: 0;\r
 188   font-style: italic;\r
 189 }\r
 190 dd > *:first-child {\r
 191   margin-top: 0;\r
 192 }\r
 193 \r
 194 ul, ol {\r
 195     list-style-position: outside;\r
 196 }\r
 197 ol.olist2 {\r
 198   list-style-type: lower-alpha;\r
 199 }\r
 200 \r
 201 div.tableblock > table {\r
 202   border-color: #527bbd;\r
 203   border-width: 3px;\r
 204 }\r
 205 thead {\r
 206   font-family: sans-serif;\r
 207   font-weight: bold;\r
 208 }\r
 209 tfoot {\r
 210   font-weight: bold;\r
 211 }\r
 212 \r
 213 div.hlist {\r
 214   margin-top: 0.8em;\r
 215   margin-bottom: 0.8em;\r
 216 }\r
 217 td.hlist1 {\r
 218   vertical-align: top;\r
 219   font-style: italic;\r
 220   padding-right: 0.8em;\r
 221 }\r
 222 td.hlist2 {\r
 223   vertical-align: top;\r
 224 }\r
 225 \r
 226 @media print {\r
 227   div#footer-badges { display: none; }\r
 228 }\r
 229 include::./stylesheets/xhtml11-manpage.css[]\r
 230 /* Workarounds for IE6's broken and incomplete CSS2. */\r
 231 \r
 232 div.sidebar-content {\r
 233   background: #ffffee;\r
 234   border: 1px solid silver;\r
 235   padding: 0.5em;\r
 236 }\r
 237 div.sidebar-title, div.image-title {\r
 238   font-family: sans-serif;\r
 239   font-weight: bold;\r
 240   margin-top: 0.0em;\r
 241   margin-bottom: 0.5em;\r
 242 }\r
 243 \r
 244 div.listingblock div.content {\r
 245   border: 1px solid silver;\r
 246   background: #f4f4f4;\r
 247   padding: 0.5em;\r
 248 }\r
 249 \r
 250 div.quoteblock-content {\r
 251   padding-left: 2.0em;\r
 252 }\r
 253 \r
 254 div.exampleblock-content {\r
 255   border-left: 2px solid silver;\r
 256   padding-left: 0.5em;\r
 257 }\r
 258 </style>\r
 259 <title>git-p4import(1)</title>\r
 260 </head>\r
 261 <body>\r
 262 <div id="header">\r
 263 <h1>\r
 264 git-p4import(1) Manual Page\r
 265 </h1>\r
 266 <h2>NAME</h2>\r
 267 <div class="sectionbody">\r
 268 <p>git-p4import -\r
 269    Import a Perforce repository into git\r
 270 </p>\r
 271 </div>\r
 272 </div>\r
 273 <h2>SYNOPSIS</h2>\r
 274 <div class="sectionbody">\r
 275 <p><tt>git-p4import</tt> [-q|-v] [--authors &lt;file&gt;] [-t &lt;timezone&gt;] &lt;//p4repo/path&gt; &lt;branch&gt;</p>\r
 276 <p><tt>git-p4import</tt> --stitch &lt;//p4repo/path&gt;</p>\r
 277 <p><tt>git-p4import</tt></p>\r
 278 </div>\r
 279 <h2>DESCRIPTION</h2>\r
 280 <div class="sectionbody">\r
 281 <p>Import a Perforce repository into an existing git repository.  When\r
 282 a &lt;//p4repo/path&gt; and &lt;branch&gt; are specified a new branch with the\r
 283 given name will be created and the initial import will begin.</p>\r
 284 <p>Once the initial import is complete you can do an incremental import\r
 285 of new commits from the Perforce repository.  You do this by checking\r
 286 out the appropriate git branch and then running <tt>git-p4import</tt> without\r
 287 any options.</p>\r
 288 <p>The standard p4 client is used to communicate with the Perforce\r
 289 repository; it must be configured correctly in order for <tt>git-p4import</tt>\r
 290 to operate (see below).</p>\r
 291 </div>\r
 292 <h2>OPTIONS</h2>\r
 293 <div class="sectionbody">\r
 294 <dl>\r
 295 <dt>\r
 296 -q\r
 297 </dt>\r
 298 <dd>\r
 299 <p>\r
 300         Do not display any progress information.\r
 301 </p>\r
 302 </dd>\r
 303 <dt>\r
 304 -v\r
 305 </dt>\r
 306 <dd>\r
 307 <p>\r
 308         Give extra progress information.\r
 309 </p>\r
 310 </dd>\r
 311 <dt>\r
 312 --authors\r
 313 </dt>\r
 314 <dd>\r
 315 <p>\r
 316         Specify an authors file containing a mapping of Perforce user\r
 317         ids to full names and email addresses (see Notes below).\r
 318 </p>\r
 319 </dd>\r
 320 <dt>\r
 321 --stitch\r
 322 </dt>\r
 323 <dd>\r
 324 <p>\r
 325         Import the contents of the given perforce branch into the\r
 326         currently checked out git branch.\r
 327 </p>\r
 328 </dd>\r
 329 <dt>\r
 330 --log\r
 331 </dt>\r
 332 <dd>\r
 333 <p>\r
 334         Store debugging information in the specified file.\r
 335 </p>\r
 336 </dd>\r
 337 <dt>\r
 338 -t\r
 339 </dt>\r
 340 <dd>\r
 341 <p>\r
 342         Specify that the remote repository is in the specified timezone.\r
 343         Timezone must be in the format "US/Pacific" or "Europe/London"\r
 344         etc.  You only need to specify this once, it will be saved in\r
 345         the git config file for the repository.\r
 346 </p>\r
 347 </dd>\r
 348 <dt>\r
 349 &lt;//p4repo/path&gt;\r
 350 </dt>\r
 351 <dd>\r
 352 <p>\r
 353         The Perforce path that will be imported into the specified branch.\r
 354 </p>\r
 355 </dd>\r
 356 <dt>\r
 357 &lt;branch&gt;\r
 358 </dt>\r
 359 <dd>\r
 360 <p>\r
 361         The new branch that will be created to hold the Perforce imports.\r
 362 </p>\r
 363 </dd>\r
 364 </dl>\r
 365 </div>\r
 366 <h2>P4 Client</h2>\r
 367 <div class="sectionbody">\r
 368 <p>You must make the <tt>p4</tt> client command available in your $PATH and\r
 369 configure it to communicate with the target Perforce repository.\r
 370 Typically this means you must set the "$P4PORT" and "$P4CLIENT"\r
 371 environment variables.</p>\r
 372 <p>You must also configure a <tt>p4</tt> client "view" which maps the Perforce\r
 373 branch into the top level of your git repository, for example:</p>\r
 374 <div class="listingblock">\r
 375 <div class="content">\r
 376 <pre><tt>Client: myhost\r
 377 \r
 378 Root:   /home/sean/import\r
 379 \r
 380 Options:   noallwrite clobber nocompress unlocked modtime rmdir\r
 381 \r
 382 View:\r
 383         //public/jam/... //myhost/jam/...</tt></pre>\r
 384 </div></div>\r
 385 <p>With the above <tt>p4</tt> client setup, you could import the "jam"\r
 386 perforce branch into a branch named "jammy", like so:</p>\r
 387 <div class="listingblock">\r
 388 <div class="content">\r
 389 <pre><tt>$ mkdir -p /home/sean/import/jam\r
 390 $ cd /home/sean/import/jam\r
 391 $ git init-db\r
 392 $ git p4import //public/jam jammy</tt></pre>\r
 393 </div></div>\r
 394 </div>\r
 395 <h2>Multiple Branches</h2>\r
 396 <div class="sectionbody">\r
 397 <p>Note that by creating multiple "views" you can use <tt>git-p4import</tt>\r
 398 to import additional branches into the same git repository.\r
 399 However, the <tt>p4</tt> client has a limitation in that it silently\r
 400 ignores all but the last "view" that maps into the same local\r
 401 directory.  So the following will <strong>not</strong> work:</p>\r
 402 <div class="listingblock">\r
 403 <div class="content">\r
 404 <pre><tt>View:\r
 405         //public/jam/... //myhost/jam/...\r
 406         //public/other/... //myhost/jam/...\r
 407         //public/guest/... //myhost/jam/...</tt></pre>\r
 408 </div></div>\r
 409 <p>If you want more than one Perforce branch to be imported into the\r
 410 same directory you must employ a workaround.  A simple option is\r
 411 to adjust your <tt>p4</tt> client before each import to only include a\r
 412 single view.</p>\r
 413 <p>Another option is to create multiple symlinks locally which all\r
 414 point to the same directory in your git repository and then use\r
 415 one per "view" instead of listing the actual directory.</p>\r
 416 </div>\r
 417 <h2>Tags</h2>\r
 418 <div class="sectionbody">\r
 419 <p>A git tag of the form p4/xx is created for every change imported from\r
 420 the Perforce repository where xx is the Perforce changeset number.\r
 421 Therefore after the import you can use git to access any commit by its\r
 422 Perforce number, eg. git show p4/327.</p>\r
 423 <p>The tag associated with the HEAD commit is also how <tt>git-p4import</tt>\r
 424 determines if there are new changes to incrementally import from the\r
 425 Perforce repository.</p>\r
 426 <p>If you import from a repository with many thousands of changes\r
 427 you will have an equal number of p4/xxxx git tags.  Git tags can\r
 428 be expensive in terms of disk space and repository operations.\r
 429 If you don't need to perform further incremental imports, you\r
 430 may delete the tags.</p>\r
 431 </div>\r
 432 <h2>Notes</h2>\r
 433 <div class="sectionbody">\r
 434 <p>You can interrupt the import (eg. ctrl-c) at any time and restart it\r
 435 without worry.</p>\r
 436 <p>Author information is automatically determined by querying the\r
 437 Perforce "users" table using the id associated with each change.\r
 438 However, if you want to manually supply these mappings you can do\r
 439 so with the "--authors" option.  It accepts a file containing a list\r
 440 of mappings with each line containing one mapping in the format:</p>\r
 441 <div class="listingblock">\r
 442 <div class="content">\r
 443 <pre><tt>    perforce_id = Full Name &lt;email@address.com&gt;</tt></pre>\r
 444 </div></div>\r
 445 </div>\r
 446 <h2>Author</h2>\r
 447 <div class="sectionbody">\r
 448 <p>Written by Sean Estabrooks &lt;seanlkml@sympatico.ca&gt;</p>\r
 449 </div>\r
 450 <h2>GIT</h2>\r
 451 <div class="sectionbody">\r
 452 <p>Part of the <a href="git.html">git(7)</a> suite</p>\r
 453 </div>\r
 454 <div id="footer">\r
 455 <div id="footer-text">\r
 456 Last updated 07-Jun-2006 19:51:30 UTC\r
 457 </div>\r
 458 </div>\r
 459 </body>\r
 460 </html>\r