doc/source/en/TortoiseGit/git_doc/git-svn.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
   3 \r
   4 <article lang="en" id="git-svn(1)">\r
   5 <articleinfo>\r
   6     <title>git-svn(1)</title>\r
   7 <indexterm>\r
   8 <primary>git-svn(1)</primary>\r
   9 </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>git-svn - Bidirectional operation between a Subversion repository and git</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <blockquote>\r
  18 <literallayout><emphasis>git svn</emphasis> &lt;command&gt; [options] [arguments]</literallayout>\r
  19 </blockquote>\r
  20 </simplesect>\r
  21 <simplesect id="_description">\r
  22 <title>DESCRIPTION</title>\r
  23 <simpara><emphasis>git svn</emphasis> is a simple conduit for changesets between Subversion and git.\r
  24 It provides a bidirectional flow of changes between a Subversion and a git\r
  25 repository.</simpara>\r
  26 <simpara><emphasis>git svn</emphasis> can track a standard Subversion repository,\r
  27 following the common "trunk/branches/tags" layout, with the --stdlayout option.\r
  28 It can also follow branches and tags in any layout with the -T/-t/-b options\r
  29 (see options to <emphasis>init</emphasis> below, and also the <emphasis>clone</emphasis> command).</simpara>\r
  30 <simpara>Once tracking a Subversion repository (with any of the above methods), the git\r
  31 repository can be updated from Subversion by the <emphasis>fetch</emphasis> command and\r
  32 Subversion updated from git by the <emphasis>dcommit</emphasis> command.</simpara>\r
  33 </simplesect>\r
  34 <simplesect id="_commands">\r
  35 <title>COMMANDS</title>\r
  36 <variablelist>\r
  37 <varlistentry>\r
  38 <term>\r
  39 <emphasis>init</emphasis>\r
  40 </term>\r
  41 <listitem>\r
  42 <simpara>\r
  43         Initializes an empty git repository with additional\r
  44         metadata directories for <emphasis>git svn</emphasis>.  The Subversion URL\r
  45         may be specified as a command-line argument, or as full\r
  46         URL arguments to -T/-t/-b.  Optionally, the target\r
  47         directory to operate on can be specified as a second\r
  48         argument.  Normally this command initializes the current\r
  49         directory.\r
  50 </simpara>\r
  51 <variablelist>\r
  52 <varlistentry>\r
  53 <term>\r
  54 -T&lt;trunk_subdir&gt;\r
  55 </term>\r
  56 <term>\r
  57 --trunk=&lt;trunk_subdir&gt;\r
  58 </term>\r
  59 <term>\r
  60 -t&lt;tags_subdir&gt;\r
  61 </term>\r
  62 <term>\r
  63 --tags=&lt;tags_subdir&gt;\r
  64 </term>\r
  65 <term>\r
  66 -b&lt;branches_subdir&gt;\r
  67 </term>\r
  68 <term>\r
  69 --branches=&lt;branches_subdir&gt;\r
  70 </term>\r
  71 <term>\r
  72 -s\r
  73 </term>\r
  74 <term>\r
  75 --stdlayout\r
  76 </term>\r
  77 <listitem>\r
  78 <simpara>\r
  79         These are optional command-line options for init.  Each of\r
  80         these flags can point to a relative repository path\r
  81         (--tags=project/tags) or a full url\r
  82         (--tags=https://foo.org/project/tags).\r
  83         You can specify more than one --tags and/or --branches options, in case\r
  84         your Subversion repository places tags or branches under multiple paths.\r
  85         The option --stdlayout is\r
  86         a shorthand way of setting trunk,tags,branches as the relative paths,\r
  87         which is the Subversion default. If any of the other options are given\r
  88         as well, they take precedence.\r
  89 </simpara>\r
  90 </listitem>\r
  91 </varlistentry>\r
  92 <varlistentry>\r
  93 <term>\r
  94 --no-metadata\r
  95 </term>\r
  96 <listitem>\r
  97 <simpara>\r
  98         Set the <emphasis>noMetadata</emphasis> option in the [svn-remote] config.\r
  99         This option is not recommended, please read the <emphasis>svn.noMetadata</emphasis>\r
 100         section of this manpage before using this option.\r
 101 </simpara>\r
 102 </listitem>\r
 103 </varlistentry>\r
 104 <varlistentry>\r
 105 <term>\r
 106 --use-svm-props\r
 107 </term>\r
 108 <listitem>\r
 109 <simpara>\r
 110         Set the <emphasis>useSvmProps</emphasis> option in the [svn-remote] config.\r
 111 </simpara>\r
 112 </listitem>\r
 113 </varlistentry>\r
 114 <varlistentry>\r
 115 <term>\r
 116 --use-svnsync-props\r
 117 </term>\r
 118 <listitem>\r
 119 <simpara>\r
 120         Set the <emphasis>useSvnsyncProps</emphasis> option in the [svn-remote] config.\r
 121 </simpara>\r
 122 </listitem>\r
 123 </varlistentry>\r
 124 <varlistentry>\r
 125 <term>\r
 126 --rewrite-root=&lt;URL&gt;\r
 127 </term>\r
 128 <listitem>\r
 129 <simpara>\r
 130         Set the <emphasis>rewriteRoot</emphasis> option in the [svn-remote] config.\r
 131 </simpara>\r
 132 </listitem>\r
 133 </varlistentry>\r
 134 <varlistentry>\r
 135 <term>\r
 136 --rewrite-uuid=&lt;UUID&gt;\r
 137 </term>\r
 138 <listitem>\r
 139 <simpara>\r
 140         Set the <emphasis>rewriteUUID</emphasis> option in the [svn-remote] config.\r
 141 </simpara>\r
 142 </listitem>\r
 143 </varlistentry>\r
 144 <varlistentry>\r
 145 <term>\r
 146 --username=&lt;user&gt;\r
 147 </term>\r
 148 <listitem>\r
 149 <simpara>\r
 150         For transports that SVN handles authentication for (http,\r
 151         https, and plain svn), specify the username.  For other\r
 152         transports (eg svn+ssh://), you must include the username in\r
 153         the URL, eg svn+ssh://foo@svn.bar.com/project\r
 154 </simpara>\r
 155 </listitem>\r
 156 </varlistentry>\r
 157 <varlistentry>\r
 158 <term>\r
 159 --prefix=&lt;prefix&gt;\r
 160 </term>\r
 161 <listitem>\r
 162 <simpara>\r
 163         This allows one to specify a prefix which is prepended\r
 164         to the names of remotes if trunk/branches/tags are\r
 165         specified.  The prefix does not automatically include a\r
 166         trailing slash, so be sure you include one in the\r
 167         argument if that is what you want.  If --branches/-b is\r
 168         specified, the prefix must include a trailing slash.\r
 169         Setting a prefix is useful if you wish to track multiple\r
 170         projects that share a common repository.\r
 171 </simpara>\r
 172 </listitem>\r
 173 </varlistentry>\r
 174 <varlistentry>\r
 175 <term>\r
 176 --ignore-paths=&lt;regex&gt;\r
 177 </term>\r
 178 <listitem>\r
 179 <simpara>\r
 180         When passed to <emphasis>init</emphasis> or <emphasis>clone</emphasis> this regular expression will\r
 181         be preserved as a config key.  See <emphasis>fetch</emphasis> for a description\r
 182         of <emphasis>--ignore-paths</emphasis>.\r
 183 </simpara>\r
 184 </listitem>\r
 185 </varlistentry>\r
 186 <varlistentry>\r
 187 <term>\r
 188 --no-minimize-url\r
 189 </term>\r
 190 <listitem>\r
 191 <simpara>\r
 192         When tracking multiple directories (using --stdlayout,\r
 193         --branches, or --tags options), git svn will attempt to connect\r
 194         to the root (or highest allowed level) of the Subversion\r
 195         repository.  This default allows better tracking of history if\r
 196         entire projects are moved within a repository, but may cause\r
 197         issues on repositories where read access restrictions are in\r
 198         place.  Passing <emphasis>--no-minimize-url</emphasis> will allow git svn to\r
 199         accept URLs as-is without attempting to connect to a higher\r
 200         level directory.  This option is off by default when only\r
 201         one URL/branch is tracked (it would do little good).\r
 202 </simpara>\r
 203 </listitem>\r
 204 </varlistentry>\r
 205 </variablelist>\r
 206 </listitem>\r
 207 </varlistentry>\r
 208 <varlistentry>\r
 209 <term>\r
 210 <emphasis>fetch</emphasis>\r
 211 </term>\r
 212 <listitem>\r
 213 <simpara>\r
 214         Fetch unfetched revisions from the Subversion remote we are\r
 215         tracking.  The name of the [svn-remote "&#8230;"] section in the\r
 216         .git/config file may be specified as an optional command-line\r
 217         argument.\r
 218 </simpara>\r
 219 <variablelist>\r
 220 <varlistentry>\r
 221 <term>\r
 222 --localtime\r
 223 </term>\r
 224 <listitem>\r
 225 <simpara>\r
 226         Store Git commit times in the local timezone instead of UTC.  This\r
 227         makes <emphasis>git log</emphasis> (even without --date=local) show the same times\r
 228         that <emphasis>svn log</emphasis> would in the local timezone.\r
 229 </simpara>\r
 230 <simpara>This doesn't interfere with interoperating with the Subversion\r
 231 repository you cloned from, but if you wish for your local Git\r
 232 repository to be able to interoperate with someone else's local Git\r
 233 repository, either don't use this option or you should both use it in\r
 234 the same local timezone.</simpara>\r
 235 </listitem>\r
 236 </varlistentry>\r
 237 <varlistentry>\r
 238 <term>\r
 239 --parent\r
 240 </term>\r
 241 <listitem>\r
 242 <simpara>\r
 243         Fetch only from the SVN parent of the current HEAD.\r
 244 </simpara>\r
 245 </listitem>\r
 246 </varlistentry>\r
 247 <varlistentry>\r
 248 <term>\r
 249 --ignore-paths=&lt;regex&gt;\r
 250 </term>\r
 251 <listitem>\r
 252 <simpara>\r
 253         This allows one to specify a Perl regular expression that will\r
 254         cause skipping of all matching paths from checkout from SVN.\r
 255         The <emphasis>--ignore-paths</emphasis> option should match for every <emphasis>fetch</emphasis>\r
 256         (including automatic fetches due to <emphasis>clone</emphasis>, <emphasis>dcommit</emphasis>,\r
 257         <emphasis>rebase</emphasis>, etc) on a given repository.\r
 258 </simpara>\r
 259 <blockquote>\r
 260 <literallayout>config key: svn-remote.&lt;name&gt;.ignore-paths</literallayout>\r
 261 </blockquote>\r
 262 <simpara>If the ignore-paths config key is set and the command line option is\r
 263 also given, both regular expressions will be used.</simpara>\r
 264 <simpara>Examples:</simpara>\r
 265 <variablelist>\r
 266 <varlistentry>\r
 267 <term>\r
 268 Skip "doc*" directory for every fetch\r
 269 </term>\r
 270 <listitem>\r
 271 <screen>--ignore-paths="^doc"</screen>\r
 272 </listitem>\r
 273 </varlistentry>\r
 274 <varlistentry>\r
 275 <term>\r
 276 Skip "branches" and "tags" of first level directories\r
 277 </term>\r
 278 <listitem>\r
 279 <screen>--ignore-paths="^[^/]+/(?:branches|tags)"</screen>\r
 280 </listitem>\r
 281 </varlistentry>\r
 282 </variablelist>\r
 283 </listitem>\r
 284 </varlistentry>\r
 285 </variablelist>\r
 286 </listitem>\r
 287 </varlistentry>\r
 288 <varlistentry>\r
 289 <term>\r
 290 <emphasis>clone</emphasis>\r
 291 </term>\r
 292 <listitem>\r
 293 <simpara>\r
 294         Runs <emphasis>init</emphasis> and <emphasis>fetch</emphasis>.  It will automatically create a\r
 295         directory based on the basename of the URL passed to it;\r
 296         or if a second argument is passed; it will create a directory\r
 297         and work within that.  It accepts all arguments that the\r
 298         <emphasis>init</emphasis> and <emphasis>fetch</emphasis> commands accept; with the exception of\r
 299         <emphasis>--fetch-all</emphasis> and <emphasis>--parent</emphasis>.  After a repository is cloned,\r
 300         the <emphasis>fetch</emphasis> command will be able to update revisions without\r
 301         affecting the working tree; and the <emphasis>rebase</emphasis> command will be\r
 302         able to update the working tree with the latest changes.\r
 303 </simpara>\r
 304 <variablelist>\r
 305 <varlistentry>\r
 306 <term>\r
 307 --preserve-empty-dirs\r
 308 </term>\r
 309 <listitem>\r
 310 <simpara>\r
 311         Create a placeholder file in the local Git repository for each\r
 312         empty directory fetched from Subversion.  This includes directories\r
 313         that become empty by removing all entries in the Subversion\r
 314         repository (but not the directory itself).  The placeholder files\r
 315         are also tracked and removed when no longer necessary.\r
 316 </simpara>\r
 317 </listitem>\r
 318 </varlistentry>\r
 319 <varlistentry>\r
 320 <term>\r
 321 --placeholder-filename=&lt;filename&gt;\r
 322 </term>\r
 323 <listitem>\r
 324 <simpara>\r
 325         Set the name of placeholder files created by --preserve-empty-dirs.\r
 326         Default: ".gitignore"\r
 327 </simpara>\r
 328 </listitem>\r
 329 </varlistentry>\r
 330 </variablelist>\r
 331 </listitem>\r
 332 </varlistentry>\r
 333 <varlistentry>\r
 334 <term>\r
 335 <emphasis>rebase</emphasis>\r
 336 </term>\r
 337 <listitem>\r
 338 <simpara>\r
 339         This fetches revisions from the SVN parent of the current HEAD\r
 340         and rebases the current (uncommitted to SVN) work against it.\r
 341 </simpara>\r
 342 <simpara>This works similarly to <emphasis>svn update</emphasis> or <emphasis>git pull</emphasis> except that\r
 343 it preserves linear history with <emphasis>git rebase</emphasis> instead of\r
 344 <emphasis>git merge</emphasis> for ease of dcommitting with <emphasis>git svn</emphasis>.</simpara>\r
 345 <simpara>This accepts all options that <emphasis>git svn fetch</emphasis> and <emphasis>git rebase</emphasis>\r
 346 accept.  However, <emphasis>--fetch-all</emphasis> only fetches from the current\r
 347 [svn-remote], and not all [svn-remote] definitions.</simpara>\r
 348 <simpara>Like <emphasis>git rebase</emphasis>; this requires that the working tree be clean\r
 349 and have no uncommitted changes.</simpara>\r
 350 <variablelist>\r
 351 <varlistentry>\r
 352 <term>\r
 353 -l\r
 354 </term>\r
 355 <term>\r
 356 --local\r
 357 </term>\r
 358 <listitem>\r
 359 <simpara>\r
 360         Do not fetch remotely; only run <emphasis>git rebase</emphasis> against the\r
 361         last fetched commit from the upstream SVN.\r
 362 </simpara>\r
 363 </listitem>\r
 364 </varlistentry>\r
 365 </variablelist>\r
 366 </listitem>\r
 367 </varlistentry>\r
 368 <varlistentry>\r
 369 <term>\r
 370 <emphasis>dcommit</emphasis>\r
 371 </term>\r
 372 <listitem>\r
 373 <simpara>\r
 374         Commit each diff from a specified head directly to the SVN\r
 375         repository, and then rebase or reset (depending on whether or\r
 376         not there is a diff between SVN and head).  This will create\r
 377         a revision in SVN for each commit in git.\r
 378         It is recommended that you run <emphasis>git svn</emphasis> fetch and rebase (not\r
 379         pull or merge) your commits against the latest changes in the\r
 380         SVN repository.\r
 381         An optional revision or branch argument may be specified, and\r
 382         causes <emphasis>git svn</emphasis> to do all work on that revision/branch\r
 383         instead of HEAD.\r
 384         This is advantageous over <emphasis>set-tree</emphasis> (below) because it produces\r
 385         cleaner, more linear history.\r
 386 </simpara>\r
 387 <variablelist>\r
 388 <varlistentry>\r
 389 <term>\r
 390 --no-rebase\r
 391 </term>\r
 392 <listitem>\r
 393 <simpara>\r
 394         After committing, do not rebase or reset.\r
 395 </simpara>\r
 396 </listitem>\r
 397 </varlistentry>\r
 398 <varlistentry>\r
 399 <term>\r
 400 --commit-url &lt;URL&gt;\r
 401 </term>\r
 402 <listitem>\r
 403 <simpara>\r
 404         Commit to this SVN URL (the full path).  This is intended to\r
 405         allow existing <emphasis>git svn</emphasis> repositories created with one transport\r
 406         method (e.g. <emphasis>svn://</emphasis> or <emphasis>http://</emphasis> for anonymous read) to be\r
 407         reused if a user is later given access to an alternate transport\r
 408         method (e.g. <emphasis>svn+ssh://</emphasis> or <emphasis>https://</emphasis>) for commit.\r
 409 </simpara>\r
 410 <blockquote>\r
 411 <literallayout>config key: svn-remote.&lt;name&gt;.commiturl\r
 412 config key: svn.commiturl (overwrites all svn-remote.&lt;name&gt;.commiturl options)</literallayout>\r
 413 </blockquote>\r
 414 <simpara>Using this option for any other purpose (don't ask) is very strongly\r
 415 discouraged.</simpara>\r
 416 </listitem>\r
 417 </varlistentry>\r
 418 <varlistentry>\r
 419 <term>\r
 420 --mergeinfo=&lt;mergeinfo&gt;\r
 421 </term>\r
 422 <listitem>\r
 423 <simpara>\r
 424         Add the given merge information during the dcommit\r
 425         (e.g. <emphasis>--mergeinfo="/branches/foo:1-10"</emphasis>). All svn server versions can\r
 426         store this information (as a property), and svn clients starting from\r
 427         version 1.5 can make use of it. To specify merge information from multiple\r
 428         branches, use a single space character between the branches\r
 429         (<emphasis>--mergeinfo="/branches/foo:1-10 /branches/bar:3,5-6,8"</emphasis>)\r
 430 </simpara>\r
 431 <blockquote>\r
 432 <literallayout>config key: svn.pushmergeinfo</literallayout>\r
 433 </blockquote>\r
 434 <simpara>This option will cause git-svn to attempt to automatically populate the\r
 435 svn:mergeinfo property in the SVN repository when possible. Currently, this can\r
 436 only be done when dcommitting non-fast-forward merges where all parents but the\r
 437 first have already been pushed into SVN.</simpara>\r
 438 </listitem>\r
 439 </varlistentry>\r
 440 <varlistentry>\r
 441 <term>\r
 442 --interactive\r
 443 </term>\r
 444 <listitem>\r
 445 <simpara>\r
 446         Ask the user to confirm that a patch set should actually be sent to SVN.\r
 447         For each patch, one may answer "yes" (accept this patch), "no" (discard this\r
 448         patch), "all" (accept all patches), or "quit".\r
 449        <?asciidoc-br?>\r
 450         <emphasis>git svn dcommit</emphasis> returns immediately if answer if "no" or "quit", without\r
 451         commiting anything to SVN.\r
 452 </simpara>\r
 453 </listitem>\r
 454 </varlistentry>\r
 455 </variablelist>\r
 456 </listitem>\r
 457 </varlistentry>\r
 458 <varlistentry>\r
 459 <term>\r
 460 <emphasis>branch</emphasis>\r
 461 </term>\r
 462 <listitem>\r
 463 <simpara>\r
 464         Create a branch in the SVN repository.\r
 465 </simpara>\r
 466 <variablelist>\r
 467 <varlistentry>\r
 468 <term>\r
 469 -m\r
 470 </term>\r
 471 <term>\r
 472 --message\r
 473 </term>\r
 474 <listitem>\r
 475 <simpara>\r
 476         Allows to specify the commit message.\r
 477 </simpara>\r
 478 </listitem>\r
 479 </varlistentry>\r
 480 <varlistentry>\r
 481 <term>\r
 482 -t\r
 483 </term>\r
 484 <term>\r
 485 --tag\r
 486 </term>\r
 487 <listitem>\r
 488 <simpara>\r
 489         Create a tag by using the tags_subdir instead of the branches_subdir\r
 490         specified during git svn init.\r
 491 </simpara>\r
 492 </listitem>\r
 493 </varlistentry>\r
 494 <varlistentry>\r
 495 <term>\r
 496 -d\r
 497 </term>\r
 498 <term>\r
 499 --destination\r
 500 </term>\r
 501 <listitem>\r
 502 <simpara>\r
 503         If more than one --branches (or --tags) option was given to the <emphasis>init</emphasis>\r
 504         or <emphasis>clone</emphasis> command, you must provide the location of the branch (or\r
 505         tag) you wish to create in the SVN repository.  The value of this\r
 506         option must match one of the paths specified by a --branches (or\r
 507         --tags) option.  You can see these paths with the commands\r
 508 </simpara>\r
 509 <literallayout class="monospaced">git config --get-all svn-remote.&lt;name&gt;.branches\r
 510 git config --get-all svn-remote.&lt;name&gt;.tags</literallayout>\r
 511 <simpara>where &lt;name&gt; is the name of the SVN repository as specified by the -R option to\r
 512 <emphasis>init</emphasis> (or "svn" by default).</simpara>\r
 513 </listitem>\r
 514 </varlistentry>\r
 515 <varlistentry>\r
 516 <term>\r
 517 --username\r
 518 </term>\r
 519 <listitem>\r
 520 <simpara>\r
 521         Specify the SVN username to perform the commit as.  This option overrides\r
 522         the <emphasis>username</emphasis> configuration property.\r
 523 </simpara>\r
 524 </listitem>\r
 525 </varlistentry>\r
 526 <varlistentry>\r
 527 <term>\r
 528 --commit-url\r
 529 </term>\r
 530 <listitem>\r
 531 <simpara>\r
 532         Use the specified URL to connect to the destination Subversion\r
 533         repository.  This is useful in cases where the source SVN\r
 534         repository is read-only.  This option overrides configuration\r
 535         property <emphasis>commiturl</emphasis>.\r
 536 </simpara>\r
 537 <literallayout class="monospaced">git config --get-all svn-remote.&lt;name&gt;.commiturl</literallayout>\r
 538 </listitem>\r
 539 </varlistentry>\r
 540 </variablelist>\r
 541 </listitem>\r
 542 </varlistentry>\r
 543 <varlistentry>\r
 544 <term>\r
 545 <emphasis>tag</emphasis>\r
 546 </term>\r
 547 <listitem>\r
 548 <simpara>\r
 549         Create a tag in the SVN repository. This is a shorthand for\r
 550         <emphasis>branch -t</emphasis>.\r
 551 </simpara>\r
 552 </listitem>\r
 553 </varlistentry>\r
 554 <varlistentry>\r
 555 <term>\r
 556 <emphasis>log</emphasis>\r
 557 </term>\r
 558 <listitem>\r
 559 <simpara>\r
 560         This should make it easy to look up svn log messages when svn\r
 561         users refer to -r/--revision numbers.\r
 562 </simpara>\r
 563 <simpara>The following features from svn log are supported:</simpara>\r
 564 <variablelist>\r
 565 <varlistentry>\r
 566 <term>\r
 567 -r &lt;n&gt;[:&lt;n&gt;]\r
 568 </term>\r
 569 <term>\r
 570 --revision=&lt;n&gt;[:&lt;n&gt;]\r
 571 </term>\r
 572 <listitem>\r
 573 <simpara>\r
 574         is supported, non-numeric args are not:\r
 575         HEAD, NEXT, BASE, PREV, etc &#8230;\r
 576 </simpara>\r
 577 </listitem>\r
 578 </varlistentry>\r
 579 <varlistentry>\r
 580 <term>\r
 581 -v\r
 582 </term>\r
 583 <term>\r
 584 --verbose\r
 585 </term>\r
 586 <listitem>\r
 587 <simpara>\r
 588         it's not completely compatible with the --verbose\r
 589         output in svn log, but reasonably close.\r
 590 </simpara>\r
 591 </listitem>\r
 592 </varlistentry>\r
 593 <varlistentry>\r
 594 <term>\r
 595 --limit=&lt;n&gt;\r
 596 </term>\r
 597 <listitem>\r
 598 <simpara>\r
 599         is NOT the same as --max-count, doesn't count\r
 600         merged/excluded commits\r
 601 </simpara>\r
 602 </listitem>\r
 603 </varlistentry>\r
 604 <varlistentry>\r
 605 <term>\r
 606 --incremental\r
 607 </term>\r
 608 <listitem>\r
 609 <simpara>\r
 610         supported\r
 611 </simpara>\r
 612 </listitem>\r
 613 </varlistentry>\r
 614 </variablelist>\r
 615 <simpara>New features:</simpara>\r
 616 <variablelist>\r
 617 <varlistentry>\r
 618 <term>\r
 619 --show-commit\r
 620 </term>\r
 621 <listitem>\r
 622 <simpara>\r
 623         shows the git commit sha1, as well\r
 624 </simpara>\r
 625 </listitem>\r
 626 </varlistentry>\r
 627 <varlistentry>\r
 628 <term>\r
 629 --oneline\r
 630 </term>\r
 631 <listitem>\r
 632 <simpara>\r
 633         our version of --pretty=oneline\r
 634 </simpara>\r
 635 </listitem>\r
 636 </varlistentry>\r
 637 </variablelist>\r
 638 <note><simpara>SVN itself only stores times in UTC and nothing else. The regular svn\r
 639 client converts the UTC time to the local time (or based on the TZ=\r
 640 environment). This command has the same behaviour.</simpara></note>\r
 641 <simpara>Any other arguments are passed directly to <emphasis>git log</emphasis></simpara>\r
 642 </listitem>\r
 643 </varlistentry>\r
 644 <varlistentry>\r
 645 <term>\r
 646 <emphasis>blame</emphasis>\r
 647 </term>\r
 648 <listitem>\r
 649 <simpara>\r
 650        Show what revision and author last modified each line of a file. The\r
 651        output of this mode is format-compatible with the output of\r
 652        svn blame by default. Like the SVN blame command,\r
 653        local uncommitted changes in the working tree are ignored;\r
 654        the version of the file in the HEAD revision is annotated. Unknown\r
 655        arguments are passed directly to <emphasis>git blame</emphasis>.\r
 656 </simpara>\r
 657 <variablelist>\r
 658 <varlistentry>\r
 659 <term>\r
 660 --git-format\r
 661 </term>\r
 662 <listitem>\r
 663 <simpara>\r
 664         Produce output in the same format as <emphasis>git blame</emphasis>, but with\r
 665         SVN revision numbers instead of git commit hashes. In this mode,\r
 666         changes that haven't been committed to SVN (including local\r
 667         working-copy edits) are shown as revision 0.\r
 668 </simpara>\r
 669 </listitem>\r
 670 </varlistentry>\r
 671 </variablelist>\r
 672 </listitem>\r
 673 </varlistentry>\r
 674 <varlistentry>\r
 675 <term>\r
 676 <emphasis>find-rev</emphasis>\r
 677 </term>\r
 678 <listitem>\r
 679 <simpara>\r
 680         When given an SVN revision number of the form <emphasis>rN</emphasis>, returns the\r
 681         corresponding git commit hash (this can optionally be followed by a\r
 682         tree-ish to specify which branch should be searched).  When given a\r
 683         tree-ish, returns the corresponding SVN revision number.\r
 684 </simpara>\r
 685 </listitem>\r
 686 </varlistentry>\r
 687 <varlistentry>\r
 688 <term>\r
 689 <emphasis>set-tree</emphasis>\r
 690 </term>\r
 691 <listitem>\r
 692 <simpara>\r
 693         You should consider using <emphasis>dcommit</emphasis> instead of this command.\r
 694         Commit specified commit or tree objects to SVN.  This relies on\r
 695         your imported fetch data being up-to-date.  This makes\r
 696         absolutely no attempts to do patching when committing to SVN, it\r
 697         simply overwrites files with those specified in the tree or\r
 698         commit.  All merging is assumed to have taken place\r
 699         independently of <emphasis>git svn</emphasis> functions.\r
 700 </simpara>\r
 701 </listitem>\r
 702 </varlistentry>\r
 703 <varlistentry>\r
 704 <term>\r
 705 <emphasis>create-ignore</emphasis>\r
 706 </term>\r
 707 <listitem>\r
 708 <simpara>\r
 709         Recursively finds the svn:ignore property on directories and\r
 710         creates matching .gitignore files. The resulting files are staged to\r
 711         be committed, but are not committed. Use -r/--revision to refer to a\r
 712         specific revision.\r
 713 </simpara>\r
 714 </listitem>\r
 715 </varlistentry>\r
 716 <varlistentry>\r
 717 <term>\r
 718 <emphasis>show-ignore</emphasis>\r
 719 </term>\r
 720 <listitem>\r
 721 <simpara>\r
 722         Recursively finds and lists the svn:ignore property on\r
 723         directories.  The output is suitable for appending to\r
 724         the $GIT_DIR/info/exclude file.\r
 725 </simpara>\r
 726 </listitem>\r
 727 </varlistentry>\r
 728 <varlistentry>\r
 729 <term>\r
 730 <emphasis>mkdirs</emphasis>\r
 731 </term>\r
 732 <listitem>\r
 733 <simpara>\r
 734         Attempts to recreate empty directories that core git cannot track\r
 735         based on information in $GIT_DIR/svn/&lt;refname&gt;/unhandled.log files.\r
 736         Empty directories are automatically recreated when using\r
 737         "git svn clone" and "git svn rebase", so "mkdirs" is intended\r
 738         for use after commands like "git checkout" or "git reset".\r
 739         (See the svn-remote.&lt;name&gt;.automkdirs config file option for\r
 740         more information.)\r
 741 </simpara>\r
 742 </listitem>\r
 743 </varlistentry>\r
 744 <varlistentry>\r
 745 <term>\r
 746 <emphasis>commit-diff</emphasis>\r
 747 </term>\r
 748 <listitem>\r
 749 <simpara>\r
 750         Commits the diff of two tree-ish arguments from the\r
 751         command-line.  This command does not rely on being inside an <emphasis>git svn\r
 752         init</emphasis>-ed repository.  This command takes three arguments, (a) the\r
 753         original tree to diff against, (b) the new tree result, (c) the\r
 754         URL of the target Subversion repository.  The final argument\r
 755         (URL) may be omitted if you are working from a <emphasis>git svn</emphasis>-aware\r
 756         repository (that has been <emphasis>init</emphasis>-ed with <emphasis>git svn</emphasis>).\r
 757         The -r&lt;revision&gt; option is required for this.\r
 758 </simpara>\r
 759 </listitem>\r
 760 </varlistentry>\r
 761 <varlistentry>\r
 762 <term>\r
 763 <emphasis>info</emphasis>\r
 764 </term>\r
 765 <listitem>\r
 766 <simpara>\r
 767         Shows information about a file or directory similar to what\r
 768         svn info provides.  Does not currently support a -r/--revision\r
 769         argument.  Use the --url option to output only the value of the\r
 770         <emphasis>URL:</emphasis> field.\r
 771 </simpara>\r
 772 </listitem>\r
 773 </varlistentry>\r
 774 <varlistentry>\r
 775 <term>\r
 776 <emphasis>proplist</emphasis>\r
 777 </term>\r
 778 <listitem>\r
 779 <simpara>\r
 780         Lists the properties stored in the Subversion repository about a\r
 781         given file or directory.  Use -r/--revision to refer to a specific\r
 782         Subversion revision.\r
 783 </simpara>\r
 784 </listitem>\r
 785 </varlistentry>\r
 786 <varlistentry>\r
 787 <term>\r
 788 <emphasis>propget</emphasis>\r
 789 </term>\r
 790 <listitem>\r
 791 <simpara>\r
 792         Gets the Subversion property given as the first argument, for a\r
 793         file.  A specific revision can be specified with -r/--revision.\r
 794 </simpara>\r
 795 </listitem>\r
 796 </varlistentry>\r
 797 <varlistentry>\r
 798 <term>\r
 799 <emphasis>show-externals</emphasis>\r
 800 </term>\r
 801 <listitem>\r
 802 <simpara>\r
 803         Shows the Subversion externals.  Use -r/--revision to specify a\r
 804         specific revision.\r
 805 </simpara>\r
 806 </listitem>\r
 807 </varlistentry>\r
 808 <varlistentry>\r
 809 <term>\r
 810 <emphasis>gc</emphasis>\r
 811 </term>\r
 812 <listitem>\r
 813 <simpara>\r
 814         Compress $GIT_DIR/svn/&lt;refname&gt;/unhandled.log files in .git/svn\r
 815         and remove $GIT_DIR/svn/&lt;refname&gt;index files in .git/svn.\r
 816 </simpara>\r
 817 </listitem>\r
 818 </varlistentry>\r
 819 <varlistentry>\r
 820 <term>\r
 821 <emphasis>reset</emphasis>\r
 822 </term>\r
 823 <listitem>\r
 824 <simpara>\r
 825         Undoes the effects of <emphasis>fetch</emphasis> back to the specified revision.\r
 826         This allows you to re-<emphasis>fetch</emphasis> an SVN revision.  Normally the\r
 827         contents of an SVN revision should never change and <emphasis>reset</emphasis>\r
 828         should not be necessary.  However, if SVN permissions change,\r
 829         or if you alter your --ignore-paths option, a <emphasis>fetch</emphasis> may fail\r
 830         with "not found in commit" (file not previously visible) or\r
 831         "checksum mismatch" (missed a modification).  If the problem\r
 832         file cannot be ignored forever (with --ignore-paths) the only\r
 833         way to repair the repo is to use <emphasis>reset</emphasis>.\r
 834 </simpara>\r
 835 <simpara>Only the rev_map and refs/remotes/git-svn are changed.  Follow <emphasis>reset</emphasis>\r
 836 with a <emphasis>fetch</emphasis> and then <emphasis>git reset</emphasis> or <emphasis>git rebase</emphasis> to move local\r
 837 branches onto the new tree.</simpara>\r
 838 <variablelist>\r
 839 <varlistentry>\r
 840 <term>\r
 841 -r &lt;n&gt;\r
 842 </term>\r
 843 <term>\r
 844 --revision=&lt;n&gt;\r
 845 </term>\r
 846 <listitem>\r
 847 <simpara>\r
 848         Specify the most recent revision to keep.  All later revisions\r
 849         are discarded.\r
 850 </simpara>\r
 851 </listitem>\r
 852 </varlistentry>\r
 853 <varlistentry>\r
 854 <term>\r
 855 -p\r
 856 </term>\r
 857 <term>\r
 858 --parent\r
 859 </term>\r
 860 <listitem>\r
 861 <simpara>\r
 862         Discard the specified revision as well, keeping the nearest\r
 863         parent instead.\r
 864 </simpara>\r
 865 </listitem>\r
 866 </varlistentry>\r
 867 <varlistentry>\r
 868 <term>\r
 869 Example:\r
 870 </term>\r
 871 <listitem>\r
 872 <simpara>\r
 873 Assume you have local changes in "master", but you need to refetch "r2".\r
 874 </simpara>\r
 875 <screen>    r1---r2---r3 remotes/git-svn\r
 876                 \\r
 877                  A---B master</screen>\r
 878 <simpara>Fix the ignore-paths or SVN permissions problem that caused "r2" to\r
 879 be incomplete in the first place.  Then:</simpara>\r
 880 <blockquote>\r
 881 <literallayout>git svn reset -r2 -p\r
 882 git svn fetch</literallayout>\r
 883 </blockquote>\r
 884 <screen>    r1---r2'--r3' remotes/git-svn\r
 885       \\r
 886        r2---r3---A---B master</screen>\r
 887 <simpara>Then fixup "master" with <emphasis>git rebase</emphasis>.\r
 888 Do NOT use <emphasis>git merge</emphasis> or your history will not be compatible with a\r
 889 future <emphasis>dcommit</emphasis>!</simpara>\r
 890 <blockquote>\r
 891 <literallayout>git rebase --onto remotes/git-svn A^ master</literallayout>\r
 892 </blockquote>\r
 893 <screen>    r1---r2'--r3' remotes/git-svn\r
 894                 \\r
 895                  A'--B' master</screen>\r
 896 </listitem>\r
 897 </varlistentry>\r
 898 </variablelist>\r
 899 </listitem>\r
 900 </varlistentry>\r
 901 </variablelist>\r
 902 </simplesect>\r
 903 <simplesect id="_options">\r
 904 <title>OPTIONS</title>\r
 905 <variablelist>\r
 906 <varlistentry>\r
 907 <term>\r
 908 --shared[=(false|true|umask|group|all|world|everybody)]\r
 909 </term>\r
 910 <term>\r
 911 --template=&lt;template_directory&gt;\r
 912 </term>\r
 913 <listitem>\r
 914 <simpara>\r
 915         Only used with the <emphasis>init</emphasis> command.\r
 916         These are passed directly to <emphasis>git init</emphasis>.\r
 917 </simpara>\r
 918 </listitem>\r
 919 </varlistentry>\r
 920 <varlistentry>\r
 921 <term>\r
 922 -r &lt;arg&gt;\r
 923 </term>\r
 924 <term>\r
 925 --revision &lt;arg&gt;\r
 926 </term>\r
 927 <listitem>\r
 928 <simpara>\r
 929            Used with the <emphasis>fetch</emphasis> command.\r
 930 </simpara>\r
 931 <simpara>This allows revision ranges for partial/cauterized history\r
 932 to be supported.  $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges),\r
 933 $NUMBER:HEAD, and BASE:$NUMBER are all supported.</simpara>\r
 934 <simpara>This can allow you to make partial mirrors when running fetch;\r
 935 but is generally not recommended because history will be skipped\r
 936 and lost.</simpara>\r
 937 </listitem>\r
 938 </varlistentry>\r
 939 <varlistentry>\r
 940 <term>\r
 941 -\r
 942 </term>\r
 943 <term>\r
 944 --stdin\r
 945 </term>\r
 946 <listitem>\r
 947 <simpara>\r
 948         Only used with the <emphasis>set-tree</emphasis> command.\r
 949 </simpara>\r
 950 <simpara>Read a list of commits from stdin and commit them in reverse\r
 951 order.  Only the leading sha1 is read from each line, so\r
 952 <emphasis>git rev-list --pretty=oneline</emphasis> output can be used.</simpara>\r
 953 </listitem>\r
 954 </varlistentry>\r
 955 <varlistentry>\r
 956 <term>\r
 957 --rmdir\r
 958 </term>\r
 959 <listitem>\r
 960 <simpara>\r
 961         Only used with the <emphasis>dcommit</emphasis>, <emphasis>set-tree</emphasis> and <emphasis>commit-diff</emphasis> commands.\r
 962 </simpara>\r
 963 <simpara>Remove directories from the SVN tree if there are no files left\r
 964 behind.  SVN can version empty directories, and they are not\r
 965 removed by default if there are no files left in them.  git\r
 966 cannot version empty directories.  Enabling this flag will make\r
 967 the commit to SVN act like git.</simpara>\r
 968 <blockquote>\r
 969 <literallayout>config key: svn.rmdir</literallayout>\r
 970 </blockquote>\r
 971 </listitem>\r
 972 </varlistentry>\r
 973 <varlistentry>\r
 974 <term>\r
 975 -e\r
 976 </term>\r
 977 <term>\r
 978 --edit\r
 979 </term>\r
 980 <listitem>\r
 981 <simpara>\r
 982         Only used with the <emphasis>dcommit</emphasis>, <emphasis>set-tree</emphasis> and <emphasis>commit-diff</emphasis> commands.\r
 983 </simpara>\r
 984 <simpara>Edit the commit message before committing to SVN.  This is off by\r
 985 default for objects that are commits, and forced on when committing\r
 986 tree objects.</simpara>\r
 987 <blockquote>\r
 988 <literallayout>config key: svn.edit</literallayout>\r
 989 </blockquote>\r
 990 </listitem>\r
 991 </varlistentry>\r
 992 <varlistentry>\r
 993 <term>\r
 994 -l&lt;num&gt;\r
 995 </term>\r
 996 <term>\r
 997 --find-copies-harder\r
 998 </term>\r
 999 <listitem>\r
1000 <simpara>\r
1001         Only used with the <emphasis>dcommit</emphasis>, <emphasis>set-tree</emphasis> and <emphasis>commit-diff</emphasis> commands.\r
1002 </simpara>\r
1003 <simpara>They are both passed directly to <emphasis>git diff-tree</emphasis>; see\r
1004 <xref linkend="git-diff-tree(1)" /> for more information.</simpara>\r
1005 <blockquote>\r
1006 <literallayout>config key: svn.l\r
1007 config key: svn.findcopiesharder</literallayout>\r
1008 </blockquote>\r
1009 </listitem>\r
1010 </varlistentry>\r
1011 <varlistentry>\r
1012 <term>\r
1013 -A&lt;filename&gt;\r
1014 </term>\r
1015 <term>\r
1016 --authors-file=&lt;filename&gt;\r
1017 </term>\r
1018 <listitem>\r
1019 <simpara>\r
1020         Syntax is compatible with the file used by <emphasis>git cvsimport</emphasis>:\r
1021 </simpara>\r
1022 <screen>        loginname = Joe User &lt;user@example.com&gt;</screen>\r
1023 <simpara>If this option is specified and <emphasis>git svn</emphasis> encounters an SVN\r
1024 committer name that does not exist in the authors-file, <emphasis>git svn</emphasis>\r
1025 will abort operation. The user will then have to add the\r
1026 appropriate entry.  Re-running the previous <emphasis>git svn</emphasis> command\r
1027 after the authors-file is modified should continue operation.</simpara>\r
1028 <blockquote>\r
1029 <literallayout>config key: svn.authorsfile</literallayout>\r
1030 </blockquote>\r
1031 </listitem>\r
1032 </varlistentry>\r
1033 <varlistentry>\r
1034 <term>\r
1035 --authors-prog=&lt;filename&gt;\r
1036 </term>\r
1037 <listitem>\r
1038 <simpara>\r
1039         If this option is specified, for each SVN committer name that\r
1040         does not exist in the authors file, the given file is executed\r
1041         with the committer name as the first argument.  The program is\r
1042         expected to return a single line of the form "Name &lt;email&gt;",\r
1043         which will be treated as if included in the authors file.\r
1044 </simpara>\r
1045 </listitem>\r
1046 </varlistentry>\r
1047 <varlistentry>\r
1048 <term>\r
1049 -q\r
1050 </term>\r
1051 <term>\r
1052 --quiet\r
1053 </term>\r
1054 <listitem>\r
1055 <simpara>\r
1056         Make <emphasis>git svn</emphasis> less verbose. Specify a second time to make it\r
1057         even less verbose.\r
1058 </simpara>\r
1059 </listitem>\r
1060 </varlistentry>\r
1061 <varlistentry>\r
1062 <term>\r
1063 --repack[=&lt;n&gt;]\r
1064 </term>\r
1065 <term>\r
1066 --repack-flags=&lt;flags&gt;\r
1067 </term>\r
1068 <listitem>\r
1069 <simpara>\r
1070         These should help keep disk usage sane for large fetches with\r
1071         many revisions.\r
1072 </simpara>\r
1073 <simpara>--repack takes an optional argument for the number of revisions\r
1074 to fetch before repacking.  This defaults to repacking every\r
1075 1000 commits fetched if no argument is specified.</simpara>\r
1076 <simpara>--repack-flags are passed directly to <emphasis>git repack</emphasis>.</simpara>\r
1077 <blockquote>\r
1078 <literallayout>config key: svn.repack\r
1079 config key: svn.repackflags</literallayout>\r
1080 </blockquote>\r
1081 </listitem>\r
1082 </varlistentry>\r
1083 <varlistentry>\r
1084 <term>\r
1085 -m\r
1086 </term>\r
1087 <term>\r
1088 --merge\r
1089 </term>\r
1090 <term>\r
1091 -s&lt;strategy&gt;\r
1092 </term>\r
1093 <term>\r
1094 --strategy=&lt;strategy&gt;\r
1095 </term>\r
1096 <listitem>\r
1097 <simpara>\r
1098         These are only used with the <emphasis>dcommit</emphasis> and <emphasis>rebase</emphasis> commands.\r
1099 </simpara>\r
1100 <simpara>Passed directly to <emphasis>git rebase</emphasis> when using <emphasis>dcommit</emphasis> if a\r
1101 <emphasis>git reset</emphasis> cannot be used (see <emphasis>dcommit</emphasis>).</simpara>\r
1102 </listitem>\r
1103 </varlistentry>\r
1104 <varlistentry>\r
1105 <term>\r
1106 -n\r
1107 </term>\r
1108 <term>\r
1109 --dry-run\r
1110 </term>\r
1111 <listitem>\r
1112 <simpara>\r
1113         This can be used with the <emphasis>dcommit</emphasis>, <emphasis>rebase</emphasis>, <emphasis>branch</emphasis> and\r
1114         <emphasis>tag</emphasis> commands.\r
1115 </simpara>\r
1116 <simpara>For <emphasis>dcommit</emphasis>, print out the series of git arguments that would show\r
1117 which diffs would be committed to SVN.</simpara>\r
1118 <simpara>For <emphasis>rebase</emphasis>, display the local branch associated with the upstream svn\r
1119 repository associated with the current branch and the URL of svn\r
1120 repository that will be fetched from.</simpara>\r
1121 <simpara>For <emphasis>branch</emphasis> and <emphasis>tag</emphasis>, display the urls that will be used for copying when\r
1122 creating the branch or tag.</simpara>\r
1123 </listitem>\r
1124 </varlistentry>\r
1125 <varlistentry>\r
1126 <term>\r
1127 --use-log-author\r
1128 </term>\r
1129 <listitem>\r
1130 <simpara>\r
1131         When retrieving svn commits into git (as part of <emphasis>fetch</emphasis>, <emphasis>rebase</emphasis>, or\r
1132         <emphasis>dcommit</emphasis> operations), look for the first <emphasis>From:</emphasis> or <emphasis>Signed-off-by:</emphasis> line\r
1133         in the log message and use that as the author string.\r
1134 </simpara>\r
1135 </listitem>\r
1136 </varlistentry>\r
1137 <varlistentry>\r
1138 <term>\r
1139 --add-author-from\r
1140 </term>\r
1141 <listitem>\r
1142 <simpara>\r
1143         When committing to svn from git (as part of <emphasis>commit-diff</emphasis>, <emphasis>set-tree</emphasis> or <emphasis>dcommit</emphasis>\r
1144         operations), if the existing log message doesn't already have a\r
1145         <emphasis>From:</emphasis> or <emphasis>Signed-off-by:</emphasis> line, append a <emphasis>From:</emphasis> line based on the\r
1146         git commit's author string.  If you use this, then <emphasis>--use-log-author</emphasis>\r
1147         will retrieve a valid author string for all commits.\r
1148 </simpara>\r
1149 </listitem>\r
1150 </varlistentry>\r
1151 </variablelist>\r
1152 </simplesect>\r
1153 <simplesect id="_advanced_options">\r
1154 <title>ADVANCED OPTIONS</title>\r
1155 <variablelist>\r
1156 <varlistentry>\r
1157 <term>\r
1158 -i&lt;GIT_SVN_ID&gt;\r
1159 </term>\r
1160 <term>\r
1161 --id &lt;GIT_SVN_ID&gt;\r
1162 </term>\r
1163 <listitem>\r
1164 <simpara>\r
1165         This sets GIT_SVN_ID (instead of using the environment).  This\r
1166         allows the user to override the default refname to fetch from\r
1167         when tracking a single URL.  The <emphasis>log</emphasis> and <emphasis>dcommit</emphasis> commands\r
1168         no longer require this switch as an argument.\r
1169 </simpara>\r
1170 </listitem>\r
1171 </varlistentry>\r
1172 <varlistentry>\r
1173 <term>\r
1174 -R&lt;remote name&gt;\r
1175 </term>\r
1176 <term>\r
1177 --svn-remote &lt;remote name&gt;\r
1178 </term>\r
1179 <listitem>\r
1180 <simpara>\r
1181         Specify the [svn-remote "&lt;remote name&gt;"] section to use,\r
1182         this allows SVN multiple repositories to be tracked.\r
1183         Default: "svn"\r
1184 </simpara>\r
1185 </listitem>\r
1186 </varlistentry>\r
1187 <varlistentry>\r
1188 <term>\r
1189 --follow-parent\r
1190 </term>\r
1191 <listitem>\r
1192 <simpara>\r
1193         This is especially helpful when we're tracking a directory\r
1194         that has been moved around within the repository, or if we\r
1195         started tracking a branch and never tracked the trunk it was\r
1196         descended from. This feature is enabled by default, use\r
1197         --no-follow-parent to disable it.\r
1198 </simpara>\r
1199 <blockquote>\r
1200 <literallayout>config key: svn.followparent</literallayout>\r
1201 </blockquote>\r
1202 </listitem>\r
1203 </varlistentry>\r
1204 </variablelist>\r
1205 </simplesect>\r
1206 <simplesect id="_config_file_only_options">\r
1207 <title>CONFIG FILE-ONLY OPTIONS</title>\r
1208 <variablelist>\r
1209 <varlistentry>\r
1210 <term>\r
1211 svn.noMetadata\r
1212 </term>\r
1213 <term>\r
1214 svn-remote.&lt;name&gt;.noMetadata\r
1215 </term>\r
1216 <listitem>\r
1217 <simpara>\r
1218         This gets rid of the <emphasis>git-svn-id:</emphasis> lines at the end of every commit.\r
1219 </simpara>\r
1220 <simpara>This option can only be used for one-shot imports as <emphasis>git svn</emphasis>\r
1221 will not be able to fetch again without metadata. Additionally,\r
1222 if you lose your .git/svn/<emphasis role="strong">*/.rev_map.</emphasis> files, <emphasis>git svn</emphasis> will not\r
1223 be able to rebuild them.</simpara>\r
1224 <simpara>The <emphasis>git svn log</emphasis> command will not work on repositories using\r
1225 this, either.  Using this conflicts with the <emphasis>useSvmProps</emphasis>\r
1226 option for (hopefully) obvious reasons.</simpara>\r
1227 <simpara>This option is NOT recommended as it makes it difficult to track down\r
1228 old references to SVN revision numbers in existing documentation, bug\r
1229 reports and archives.  If you plan to eventually migrate from SVN to git\r
1230 and are certain about dropping SVN history, consider\r
1231 <xref linkend="git-filter-branch(1)" /> instead.  filter-branch also allows\r
1232 reformatting of metadata for ease-of-reading and rewriting authorship\r
1233 info for non-"svn.authorsFile" users.</simpara>\r
1234 </listitem>\r
1235 </varlistentry>\r
1236 <varlistentry>\r
1237 <term>\r
1238 svn.useSvmProps\r
1239 </term>\r
1240 <term>\r
1241 svn-remote.&lt;name&gt;.useSvmProps\r
1242 </term>\r
1243 <listitem>\r
1244 <simpara>\r
1245         This allows <emphasis>git svn</emphasis> to re-map repository URLs and UUIDs from\r
1246         mirrors created using SVN::Mirror (or svk) for metadata.\r
1247 </simpara>\r
1248 <simpara>If an SVN revision has a property, "svm:headrev", it is likely\r
1249 that the revision was created by SVN::Mirror (also used by SVK).\r
1250 The property contains a repository UUID and a revision.  We want\r
1251 to make it look like we are mirroring the original URL, so\r
1252 introduce a helper function that returns the original identity\r
1253 URL and UUID, and use it when generating metadata in commit\r
1254 messages.</simpara>\r
1255 </listitem>\r
1256 </varlistentry>\r
1257 <varlistentry>\r
1258 <term>\r
1259 svn.useSvnsyncProps\r
1260 </term>\r
1261 <term>\r
1262 svn-remote.&lt;name&gt;.useSvnsyncprops\r
1263 </term>\r
1264 <listitem>\r
1265 <simpara>\r
1266         Similar to the useSvmProps option; this is for users\r
1267         of the svnsync(1) command distributed with SVN 1.4.x and\r
1268         later.\r
1269 </simpara>\r
1270 </listitem>\r
1271 </varlistentry>\r
1272 <varlistentry>\r
1273 <term>\r
1274 svn-remote.&lt;name&gt;.rewriteRoot\r
1275 </term>\r
1276 <listitem>\r
1277 <simpara>\r
1278         This allows users to create repositories from alternate\r
1279         URLs.  For example, an administrator could run <emphasis>git svn</emphasis> on the\r
1280         server locally (accessing via file://) but wish to distribute\r
1281         the repository with a public http:// or svn:// URL in the\r
1282         metadata so users of it will see the public URL.\r
1283 </simpara>\r
1284 </listitem>\r
1285 </varlistentry>\r
1286 <varlistentry>\r
1287 <term>\r
1288 svn-remote.&lt;name&gt;.rewriteUUID\r
1289 </term>\r
1290 <listitem>\r
1291 <simpara>\r
1292         Similar to the useSvmProps option; this is for users who need\r
1293         to remap the UUID manually. This may be useful in situations\r
1294         where the original UUID is not available via either useSvmProps\r
1295         or useSvnsyncProps.\r
1296 </simpara>\r
1297 </listitem>\r
1298 </varlistentry>\r
1299 <varlistentry>\r
1300 <term>\r
1301 svn-remote.&lt;name&gt;.pushurl\r
1302 </term>\r
1303 <listitem>\r
1304 <simpara>\r
1305         Similar to git's <emphasis>remote.&lt;name&gt;.pushurl</emphasis>, this key is designed\r
1306         to be used in cases where <emphasis>url</emphasis> points to an SVN repository\r
1307         via a read-only transport, to provide an alternate read/write\r
1308         transport. It is assumed that both keys point to the same\r
1309         repository. Unlike <emphasis>commiturl</emphasis>, <emphasis>pushurl</emphasis> is a base path. If\r
1310         either <emphasis>commiturl</emphasis> or <emphasis>pushurl</emphasis> could be used, <emphasis>commiturl</emphasis>\r
1311         takes precedence.\r
1312 </simpara>\r
1313 </listitem>\r
1314 </varlistentry>\r
1315 <varlistentry>\r
1316 <term>\r
1317 svn.brokenSymlinkWorkaround\r
1318 </term>\r
1319 <listitem>\r
1320 <simpara>\r
1321         This disables potentially expensive checks to workaround\r
1322         broken symlinks checked into SVN by broken clients.  Set this\r
1323         option to "false" if you track a SVN repository with many\r
1324         empty blobs that are not symlinks.  This option may be changed\r
1325         while <emphasis>git svn</emphasis> is running and take effect on the next\r
1326         revision fetched.  If unset, <emphasis>git svn</emphasis> assumes this option to\r
1327         be "true".\r
1328 </simpara>\r
1329 </listitem>\r
1330 </varlistentry>\r
1331 <varlistentry>\r
1332 <term>\r
1333 svn.pathnameencoding\r
1334 </term>\r
1335 <listitem>\r
1336 <simpara>\r
1337         This instructs git svn to recode pathnames to a given encoding.\r
1338         It can be used by windows users and by those who work in non-utf8\r
1339         locales to avoid corrupted file names with non-ASCII characters.\r
1340         Valid encodings are the ones supported by Perl's Encode module.\r
1341 </simpara>\r
1342 </listitem>\r
1343 </varlistentry>\r
1344 <varlistentry>\r
1345 <term>\r
1346 svn-remote.&lt;name&gt;.automkdirs\r
1347 </term>\r
1348 <listitem>\r
1349 <simpara>\r
1350         Normally, the "git svn clone" and "git svn rebase" commands\r
1351         attempt to recreate empty directories that are in the\r
1352         Subversion repository.  If this option is set to "false", then\r
1353         empty directories will only be created if the "git svn mkdirs"\r
1354         command is run explicitly.  If unset, <emphasis>git svn</emphasis> assumes this\r
1355         option to be "true".\r
1356 </simpara>\r
1357 </listitem>\r
1358 </varlistentry>\r
1359 </variablelist>\r
1360 <simpara>Since the noMetadata, rewriteRoot, rewriteUUID, useSvnsyncProps and useSvmProps\r
1361 options all affect the metadata generated and used by <emphasis>git svn</emphasis>; they\r
1362 <emphasis role="strong">must</emphasis> be set in the configuration file before any history is imported\r
1363 and these settings should never be changed once they are set.</simpara>\r
1364 <simpara>Additionally, only one of these options can be used per svn-remote\r
1365 section because they affect the <emphasis>git-svn-id:</emphasis> metadata line, except\r
1366 for rewriteRoot and rewriteUUID which can be used together.</simpara>\r
1367 </simplesect>\r
1368 <simplesect id="_basic_examples">\r
1369 <title>BASIC EXAMPLES</title>\r
1370 <simpara>Tracking and contributing to the trunk of a Subversion-managed project:</simpara>\r
1371 <screen># Clone a repo (like git clone):\r
1372         git svn clone http://svn.example.com/project/trunk\r
1373 # Enter the newly cloned directory:\r
1374         cd trunk\r
1375 # You should be on master branch, double-check with 'git branch'\r
1376         git branch\r
1377 # Do some work and commit locally to git:\r
1378         git commit ...\r
1379 # Something is committed to SVN, rebase your local changes against the\r
1380 # latest changes in SVN:\r
1381         git svn rebase\r
1382 # Now commit your changes (that were committed previously using git) to SVN,\r
1383 # as well as automatically updating your working HEAD:\r
1384         git svn dcommit\r
1385 # Append svn:ignore settings to the default git exclude file:\r
1386         git svn show-ignore &gt;&gt; .git/info/exclude</screen>\r
1387 <simpara>Tracking and contributing to an entire Subversion-managed project\r
1388 (complete with a trunk, tags and branches):</simpara>\r
1389 <screen># Clone a repo (like git clone):\r
1390         git svn clone http://svn.example.com/project -T trunk -b branches -t tags\r
1391 # View all branches and tags you have cloned:\r
1392         git branch -r\r
1393 # Create a new branch in SVN\r
1394     git svn branch waldo\r
1395 # Reset your master to trunk (or any other branch, replacing 'trunk'\r
1396 # with the appropriate name):\r
1397         git reset --hard remotes/trunk\r
1398 # You may only dcommit to one branch/tag/trunk at a time.  The usage\r
1399 # of dcommit/rebase/show-ignore should be the same as above.</screen>\r
1400 <simpara>The initial <emphasis>git svn clone</emphasis> can be quite time-consuming\r
1401 (especially for large Subversion repositories). If multiple\r
1402 people (or one person with multiple machines) want to use\r
1403 <emphasis>git svn</emphasis> to interact with the same Subversion repository, you can\r
1404 do the initial <emphasis>git svn clone</emphasis> to a repository on a server and\r
1405 have each person clone that repository with <emphasis>git clone</emphasis>:</simpara>\r
1406 <screen># Do the initial import on a server\r
1407         ssh server "cd /pub &amp;&amp; git svn clone http://svn.example.com/project\r
1408 # Clone locally - make sure the refs/remotes/ space matches the server\r
1409         mkdir project\r
1410         cd project\r
1411         git init\r
1412         git remote add origin server:/pub/project\r
1413         git config --replace-all remote.origin.fetch '+refs/remotes/*:refs/remotes/*'\r
1414         git fetch\r
1415 # Prevent fetch/pull from remote git server in the future,\r
1416 # we only want to use git svn for future updates\r
1417         git config --remove-section remote.origin\r
1418 # Create a local branch from one of the branches just fetched\r
1419         git checkout -b master FETCH_HEAD\r
1420 # Initialize 'git svn' locally (be sure to use the same URL and -T/-b/-t options as were used on server)\r
1421         git svn init http://svn.example.com/project\r
1422 # Pull the latest changes from Subversion\r
1423         git svn rebase</screen>\r
1424 </simplesect>\r
1425 <simplesect id="_rebase_vs_pull_merge">\r
1426 <title>REBASE VS. PULL/MERGE</title>\r
1427 <simpara>Originally, <emphasis>git svn</emphasis> recommended that the <emphasis>remotes/git-svn</emphasis> branch be\r
1428 pulled or merged from.  This is because the author favored\r
1429 <emphasis>git svn set-tree B</emphasis> to commit a single head rather than the\r
1430 <emphasis>git svn set-tree A..B</emphasis> notation to commit multiple commits.</simpara>\r
1431 <simpara>If you use <emphasis>git svn set-tree A..B</emphasis> to commit several diffs and you do\r
1432 not have the latest remotes/git-svn merged into my-branch, you should\r
1433 use <emphasis>git svn rebase</emphasis> to update your work branch instead of <emphasis>git pull</emphasis> or\r
1434 <emphasis>git merge</emphasis>.  <emphasis>pull</emphasis>/<emphasis>merge</emphasis> can cause non-linear history to be flattened\r
1435 when committing into SVN, which can lead to merge commits reversing\r
1436 previous commits in SVN.</simpara>\r
1437 </simplesect>\r
1438 <simplesect id="_merge_tracking">\r
1439 <title>MERGE TRACKING</title>\r
1440 <simpara>While <emphasis>git svn</emphasis> can track\r
1441 copy history (including branches and tags) for repositories adopting a\r
1442 standard layout, it cannot yet represent merge history that happened\r
1443 inside git back upstream to SVN users.  Therefore it is advised that\r
1444 users keep history as linear as possible inside git to ease\r
1445 compatibility with SVN (see the CAVEATS section below).</simpara>\r
1446 </simplesect>\r
1447 <simplesect id="_caveats">\r
1448 <title>CAVEATS</title>\r
1449 <simpara>For the sake of simplicity and interoperating with Subversion,\r
1450 it is recommended that all <emphasis>git svn</emphasis> users clone, fetch and dcommit\r
1451 directly from the SVN server, and avoid all <emphasis>git clone</emphasis>/<emphasis>pull</emphasis>/<emphasis>merge</emphasis>/<emphasis>push</emphasis>\r
1452 operations between git repositories and branches.  The recommended\r
1453 method of exchanging code between git branches and users is\r
1454 <emphasis>git format-patch</emphasis> and <emphasis>git am</emphasis>, or just 'dcommit'ing to the SVN repository.</simpara>\r
1455 <simpara>Running <emphasis>git merge</emphasis> or <emphasis>git pull</emphasis> is NOT recommended on a branch you\r
1456 plan to <emphasis>dcommit</emphasis> from because Subversion users cannot see any\r
1457 merges you've made.  Furthermore, if you merge or pull from a git branch\r
1458 that is a mirror of an SVN branch, <emphasis>dcommit</emphasis> may commit to the wrong\r
1459 branch.</simpara>\r
1460 <simpara>If you do merge, note the following rule: <emphasis>git svn dcommit</emphasis> will\r
1461 attempt to commit on top of the SVN commit named in</simpara>\r
1462 <screen>git log --grep=^git-svn-id: --first-parent -1</screen>\r
1463 <simpara>You <emphasis>must</emphasis> therefore ensure that the most recent commit of the branch\r
1464 you want to dcommit to is the <emphasis>first</emphasis> parent of the merge.  Chaos will\r
1465 ensue otherwise, especially if the first parent is an older commit on\r
1466 the same SVN branch.</simpara>\r
1467 <simpara><emphasis>git clone</emphasis> does not clone branches under the refs/remotes/ hierarchy or\r
1468 any <emphasis>git svn</emphasis> metadata, or config.  So repositories created and managed with\r
1469 using <emphasis>git svn</emphasis> should use <emphasis>rsync</emphasis> for cloning, if cloning is to be done\r
1470 at all.</simpara>\r
1471 <simpara>Since <emphasis>dcommit</emphasis> uses rebase internally, any git branches you <emphasis>git push</emphasis> to\r
1472 before <emphasis>dcommit</emphasis> on will require forcing an overwrite of the existing ref\r
1473 on the remote repository.  This is generally considered bad practice,\r
1474 see the <xref linkend="git-push(1)" /> documentation for details.</simpara>\r
1475 <simpara>Do not use the --amend option of <xref linkend="git-commit(1)" /> on a change you've\r
1476 already dcommitted.  It is considered bad practice to --amend commits\r
1477 you've already pushed to a remote repository for other users, and\r
1478 dcommit with SVN is analogous to that.</simpara>\r
1479 <simpara>When using multiple --branches or --tags, <emphasis>git svn</emphasis> does not automatically\r
1480 handle name collisions (for example, if two branches from different paths have\r
1481 the same name, or if a branch and a tag have the same name).  In these cases,\r
1482 use <emphasis>init</emphasis> to set up your git repository then, before your first <emphasis>fetch</emphasis>, edit\r
1483 the .git/config file so that the branches and tags are associated with\r
1484 different name spaces.  For example:</simpara>\r
1485 <literallayout class="monospaced">branches = stable/*:refs/remotes/svn/stable/*\r
1486 branches = debug/*:refs/remotes/svn/debug/*</literallayout>\r
1487 </simplesect>\r
1488 <simplesect id="_bugs">\r
1489 <title>BUGS</title>\r
1490 <simpara>We ignore all SVN properties except svn:executable.  Any unhandled\r
1491 properties are logged to $GIT_DIR/svn/&lt;refname&gt;/unhandled.log</simpara>\r
1492 <simpara>Renamed and copied directories are not detected by git and hence not\r
1493 tracked when committing to SVN.  I do not plan on adding support for\r
1494 this as it's quite difficult and time-consuming to get working for all\r
1495 the possible corner cases (git doesn't do it, either).  Committing\r
1496 renamed and copied files is fully supported if they're similar enough\r
1497 for git to detect them.</simpara>\r
1498 </simplesect>\r
1499 <simplesect id="_configuration">\r
1500 <title>CONFIGURATION</title>\r
1501 <simpara><emphasis>git svn</emphasis> stores [svn-remote] configuration information in the\r
1502 repository .git/config file.  It is similar the core git\r
1503 [remote] sections except <emphasis>fetch</emphasis> keys do not accept glob\r
1504 arguments; but they are instead handled by the <emphasis>branches</emphasis>\r
1505 and <emphasis>tags</emphasis> keys.  Since some SVN repositories are oddly\r
1506 configured with multiple projects glob expansions such those\r
1507 listed below are allowed:</simpara>\r
1508 <screen>[svn-remote "project-a"]\r
1509         url = http://server.org/svn\r
1510         fetch = trunk/project-a:refs/remotes/project-a/trunk\r
1511         branches = branches/*/project-a:refs/remotes/project-a/branches/*\r
1512         tags = tags/*/project-a:refs/remotes/project-a/tags/*</screen>\r
1513 <simpara>Keep in mind that the <emphasis>*</emphasis> (asterisk) wildcard of the local ref\r
1514 (right of the <emphasis>:</emphasis>) <emphasis role="strong">must</emphasis> be the farthest right path component;\r
1515 however the remote wildcard may be anywhere as long as it's an\r
1516 independent path component (surrounded by <emphasis>/</emphasis> or EOL).   This\r
1517 type of configuration is not automatically created by <emphasis>init</emphasis> and\r
1518 should be manually entered with a text-editor or using <emphasis>git config</emphasis>.</simpara>\r
1519 <simpara>It is also possible to fetch a subset of branches or tags by using a\r
1520 comma-separated list of names within braces. For example:</simpara>\r
1521 <screen>[svn-remote "huge-project"]\r
1522         url = http://server.org/svn\r
1523         fetch = trunk/src:refs/remotes/trunk\r
1524         branches = branches/{red,green}/src:refs/remotes/branches/*\r
1525         tags = tags/{1.0,2.0}/src:refs/remotes/tags/*</screen>\r
1526 <simpara>Note that git-svn keeps track of the highest revision in which a branch\r
1527 or tag has appeared. If the subset of branches or tags is changed after\r
1528 fetching, then .git/svn/.metadata must be manually edited to remove (or\r
1529 reset) branches-maxRev and/or tags-maxRev as appropriate.</simpara>\r
1530 </simplesect>\r
1531 <simplesect id="_see_also">\r
1532 <title>SEE ALSO</title>\r
1533 <simpara><xref linkend="git-rebase(1)" /></simpara>\r
1534 </simplesect>\r
1535 <simplesect id="_git">\r
1536 <title>GIT</title>\r
1537 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
1538 </simplesect>\r
1539 </article>\r