0d52997b8d3389ff88973b910185b2484309aaab
   1git-svn(1)
   2==========
   3
   4NAME
   5----
   6git-svn - Bidirectional operation between a Subversion repository and git
   7
   8SYNOPSIS
   9--------
  10[verse]
  11'git svn' <command> [options] [arguments]
  12
  13DESCRIPTION
  14-----------
  15'git svn' is a simple conduit for changesets between Subversion and git.
  16It provides a bidirectional flow of changes between a Subversion and a git
  17repository.
  18
  19'git svn' can track a standard Subversion repository,
  20following the common "trunk/branches/tags" layout, with the --stdlayout option.
  21It can also follow branches and tags in any layout with the -T/-t/-b options
  22(see options to 'init' below, and also the 'clone' command).
  23
  24Once tracking a Subversion repository (with any of the above methods), the git
  25repository can be updated from Subversion by the 'fetch' command and
  26Subversion updated from git by the 'dcommit' command.
  27
  28COMMANDS
  29--------
  30
  31'init'::
  32        Initializes an empty git repository with additional
  33        metadata directories for 'git svn'.  The Subversion URL
  34        may be specified as a command-line argument, or as full
  35        URL arguments to -T/-t/-b.  Optionally, the target
  36        directory to operate on can be specified as a second
  37        argument.  Normally this command initializes the current
  38        directory.
  39
  40-T<trunk_subdir>;;
  41--trunk=<trunk_subdir>;;
  42-t<tags_subdir>;;
  43--tags=<tags_subdir>;;
  44-b<branches_subdir>;;
  45--branches=<branches_subdir>;;
  46-s;;
  47--stdlayout;;
  48        These are optional command-line options for init.  Each of
  49        these flags can point to a relative repository path
  50        (--tags=project/tags) or a full url
  51        (--tags=https://foo.org/project/tags).
  52        You can specify more than one --tags and/or --branches options, in case
  53        your Subversion repository places tags or branches under multiple paths.
  54        The option --stdlayout is
  55        a shorthand way of setting trunk,tags,branches as the relative paths,
  56        which is the Subversion default. If any of the other options are given
  57        as well, they take precedence.
  58--no-metadata;;
  59        Set the 'noMetadata' option in the [svn-remote] config.
  60        This option is not recommended, please read the 'svn.noMetadata'
  61        section of this manpage before using this option.
  62--use-svm-props;;
  63        Set the 'useSvmProps' option in the [svn-remote] config.
  64--use-svnsync-props;;
  65        Set the 'useSvnsyncProps' option in the [svn-remote] config.
  66--rewrite-root=<URL>;;
  67        Set the 'rewriteRoot' option in the [svn-remote] config.
  68--rewrite-uuid=<UUID>;;
  69        Set the 'rewriteUUID' option in the [svn-remote] config.
  70--username=<user>;;
  71        For transports that SVN handles authentication for (http,
  72        https, and plain svn), specify the username.  For other
  73        transports (eg svn+ssh://), you must include the username in
  74        the URL, eg svn+ssh://foo@svn.bar.com/project
  75--prefix=<prefix>;;
  76        This allows one to specify a prefix which is prepended
  77        to the names of remotes if trunk/branches/tags are
  78        specified.  The prefix does not automatically include a
  79        trailing slash, so be sure you include one in the
  80        argument if that is what you want.  If --branches/-b is
  81        specified, the prefix must include a trailing slash.
  82        Setting a prefix is useful if you wish to track multiple
  83        projects that share a common repository.
  84--ignore-paths=<regex>;;
  85        When passed to 'init' or 'clone' this regular expression will
  86        be preserved as a config key.  See 'fetch' for a description
  87        of '--ignore-paths'.
  88--no-minimize-url;;
  89        When tracking multiple directories (using --stdlayout,
  90        --branches, or --tags options), git svn will attempt to connect
  91        to the root (or highest allowed level) of the Subversion
  92        repository.  This default allows better tracking of history if
  93        entire projects are moved within a repository, but may cause
  94        issues on repositories where read access restrictions are in
  95        place.  Passing '--no-minimize-url' will allow git svn to
  96        accept URLs as-is without attempting to connect to a higher
  97        level directory.  This option is off by default when only
  98        one URL/branch is tracked (it would do little good).
  99
 100'fetch'::
 101        Fetch unfetched revisions from the Subversion remote we are
 102        tracking.  The name of the [svn-remote "..."] section in the
 103        .git/config file may be specified as an optional command-line
 104        argument.
 105
 106--localtime;;
 107        Store Git commit times in the local timezone instead of UTC.  This
 108        makes 'git log' (even without --date=local) show the same times
 109        that `svn log` would in the local timezone.
 110+
 111This doesn't interfere with interoperating with the Subversion
 112repository you cloned from, but if you wish for your local Git
 113repository to be able to interoperate with someone else's local Git
 114repository, either don't use this option or you should both use it in
 115the same local timezone.
 116
 117--parent;;
 118        Fetch only from the SVN parent of the current HEAD.
 119
 120--ignore-paths=<regex>;;
 121        This allows one to specify a Perl regular expression that will
 122        cause skipping of all matching paths from checkout from SVN.
 123        The '--ignore-paths' option should match for every 'fetch'
 124        (including automatic fetches due to 'clone', 'dcommit',
 125        'rebase', etc) on a given repository.
 126+
 127[verse]
 128config key: svn-remote.<name>.ignore-paths
 129+
 130If the ignore-paths config key is set and the command line option is
 131also given, both regular expressions will be used.
 132+
 133Examples:
 134+
 135--
 136Skip "doc*" directory for every fetch;;
 137+
 138------------------------------------------------------------------------
 139--ignore-paths="^doc"
 140------------------------------------------------------------------------
 141
 142Skip "branches" and "tags" of first level directories;;
 143+
 144------------------------------------------------------------------------
 145--ignore-paths="^[^/]+/(?:branches|tags)"
 146------------------------------------------------------------------------
 147--
 148
 149'clone'::
 150        Runs 'init' and 'fetch'.  It will automatically create a
 151        directory based on the basename of the URL passed to it;
 152        or if a second argument is passed; it will create a directory
 153        and work within that.  It accepts all arguments that the
 154        'init' and 'fetch' commands accept; with the exception of
 155        '--fetch-all' and '--parent'.  After a repository is cloned,
 156        the 'fetch' command will be able to update revisions without
 157        affecting the working tree; and the 'rebase' command will be
 158        able to update the working tree with the latest changes.
 159
 160--preserve-empty-dirs;;
 161        Create a placeholder file in the local Git repository for each
 162        empty directory fetched from Subversion.  This includes directories
 163        that become empty by removing all entries in the Subversion
 164        repository (but not the directory itself).  The placeholder files
 165        are also tracked and removed when no longer necessary.
 166
 167--placeholder-filename=<filename>;;
 168        Set the name of placeholder files created by --preserve-empty-dirs.
 169        Default: ".gitignore"
 170
 171'rebase'::
 172        This fetches revisions from the SVN parent of the current HEAD
 173        and rebases the current (uncommitted to SVN) work against it.
 174+
 175This works similarly to `svn update` or 'git pull' except that
 176it preserves linear history with 'git rebase' instead of
 177'git merge' for ease of dcommitting with 'git svn'.
 178+
 179This accepts all options that 'git svn fetch' and 'git rebase'
 180accept.  However, '--fetch-all' only fetches from the current
 181[svn-remote], and not all [svn-remote] definitions.
 182+
 183Like 'git rebase'; this requires that the working tree be clean
 184and have no uncommitted changes.
 185
 186-l;;
 187--local;;
 188        Do not fetch remotely; only run 'git rebase' against the
 189        last fetched commit from the upstream SVN.
 190
 191'dcommit'::
 192        Commit each diff from a specified head directly to the SVN
 193        repository, and then rebase or reset (depending on whether or
 194        not there is a diff between SVN and head).  This will create
 195        a revision in SVN for each commit in git.
 196        It is recommended that you run 'git svn' fetch and rebase (not
 197        pull or merge) your commits against the latest changes in the
 198        SVN repository.
 199        An optional revision or branch argument may be specified, and
 200        causes 'git svn' to do all work on that revision/branch
 201        instead of HEAD.
 202        This is advantageous over 'set-tree' (below) because it produces
 203        cleaner, more linear history.
 204+
 205--no-rebase;;
 206        After committing, do not rebase or reset.
 207--commit-url <URL>;;
 208        Commit to this SVN URL (the full path).  This is intended to
 209        allow existing 'git svn' repositories created with one transport
 210        method (e.g. `svn://` or `http://` for anonymous read) to be
 211        reused if a user is later given access to an alternate transport
 212        method (e.g. `svn+ssh://` or `https://`) for commit.
 213+
 214[verse]
 215config key: svn-remote.<name>.commiturl
 216config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options)
 217+
 218Using this option for any other purpose (don't ask) is very strongly
 219discouraged.
 220
 221--mergeinfo=<mergeinfo>;;
 222        Add the given merge information during the dcommit
 223        (e.g. `--mergeinfo="/branches/foo:1-10"`). All svn server versions can
 224        store this information (as a property), and svn clients starting from
 225        version 1.5 can make use of it. To specify merge information from multiple
 226        branches, use a single space character between the branches
 227        (`--mergeinfo="/branches/foo:1-10 /branches/bar:3,5-6,8"`)
 228+
 229[verse]
 230config key: svn.pushmergeinfo
 231+
 232This option will cause git-svn to attempt to automatically populate the
 233svn:mergeinfo property in the SVN repository when possible. Currently, this can
 234only be done when dcommitting non-fast-forward merges where all parents but the
 235first have already been pushed into SVN.
 236
 237--interactive;;
 238        Ask the user to confirm that a patch set should actually be sent to SVN.
 239        For each patch, one may answer "yes" (accept this patch), "no" (discard this
 240        patch), "all" (accept all patches), or "quit".
 241        +
 242        'git svn dcommit' returns immediately if answer if "no" or "quit", without
 243        commiting anything to SVN.
 244
 245'branch'::
 246        Create a branch in the SVN repository.
 247
 248-m;;
 249--message;;
 250        Allows to specify the commit message.
 251
 252-t;;
 253--tag;;
 254        Create a tag by using the tags_subdir instead of the branches_subdir
 255        specified during git svn init.
 256
 257-d;;
 258--destination;;
 259        If more than one --branches (or --tags) option was given to the 'init'
 260        or 'clone' command, you must provide the location of the branch (or
 261        tag) you wish to create in the SVN repository.  The value of this
 262        option must match one of the paths specified by a --branches (or
 263        --tags) option.  You can see these paths with the commands
 264+
 265        git config --get-all svn-remote.<name>.branches
 266        git config --get-all svn-remote.<name>.tags
 267+
 268where <name> is the name of the SVN repository as specified by the -R option to
 269'init' (or "svn" by default).
 270
 271--username;;
 272        Specify the SVN username to perform the commit as.  This option overrides
 273        the 'username' configuration property.
 274
 275--commit-url;;
 276        Use the specified URL to connect to the destination Subversion
 277        repository.  This is useful in cases where the source SVN
 278        repository is read-only.  This option overrides configuration
 279        property 'commiturl'.
 280+
 281        git config --get-all svn-remote.<name>.commiturl
 282+
 283
 284'tag'::
 285        Create a tag in the SVN repository. This is a shorthand for
 286        'branch -t'.
 287
 288'log'::
 289        This should make it easy to look up svn log messages when svn
 290        users refer to -r/--revision numbers.
 291+
 292The following features from `svn log' are supported:
 293+
 294--
 295-r <n>[:<n>];;
 296--revision=<n>[:<n>];;
 297        is supported, non-numeric args are not:
 298        HEAD, NEXT, BASE, PREV, etc ...
 299-v;;
 300--verbose;;
 301        it's not completely compatible with the --verbose
 302        output in svn log, but reasonably close.
 303--limit=<n>;;
 304        is NOT the same as --max-count, doesn't count
 305        merged/excluded commits
 306--incremental;;
 307        supported
 308--
 309+
 310New features:
 311+
 312--
 313--show-commit;;
 314        shows the git commit sha1, as well
 315--oneline;;
 316        our version of --pretty=oneline
 317--
 318+
 319NOTE: SVN itself only stores times in UTC and nothing else. The regular svn
 320client converts the UTC time to the local time (or based on the TZ=
 321environment). This command has the same behaviour.
 322+
 323Any other arguments are passed directly to 'git log'
 324
 325'blame'::
 326       Show what revision and author last modified each line of a file. The
 327       output of this mode is format-compatible with the output of
 328       `svn blame' by default. Like the SVN blame command,
 329       local uncommitted changes in the working tree are ignored;
 330       the version of the file in the HEAD revision is annotated. Unknown
 331       arguments are passed directly to 'git blame'.
 332+
 333--git-format;;
 334        Produce output in the same format as 'git blame', but with
 335        SVN revision numbers instead of git commit hashes. In this mode,
 336        changes that haven't been committed to SVN (including local
 337        working-copy edits) are shown as revision 0.
 338
 339'find-rev'::
 340        When given an SVN revision number of the form 'rN', returns the
 341        corresponding git commit hash (this can optionally be followed by a
 342        tree-ish to specify which branch should be searched).  When given a
 343        tree-ish, returns the corresponding SVN revision number.
 344
 345'set-tree'::
 346        You should consider using 'dcommit' instead of this command.
 347        Commit specified commit or tree objects to SVN.  This relies on
 348        your imported fetch data being up-to-date.  This makes
 349        absolutely no attempts to do patching when committing to SVN, it
 350        simply overwrites files with those specified in the tree or
 351        commit.  All merging is assumed to have taken place
 352        independently of 'git svn' functions.
 353
 354'create-ignore'::
 355        Recursively finds the svn:ignore property on directories and
 356        creates matching .gitignore files. The resulting files are staged to
 357        be committed, but are not committed. Use -r/--revision to refer to a
 358        specific revision.
 359
 360'show-ignore'::
 361        Recursively finds and lists the svn:ignore property on
 362        directories.  The output is suitable for appending to
 363        the $GIT_DIR/info/exclude file.
 364
 365'mkdirs'::
 366        Attempts to recreate empty directories that core git cannot track
 367        based on information in $GIT_DIR/svn/<refname>/unhandled.log files.
 368        Empty directories are automatically recreated when using
 369        "git svn clone" and "git svn rebase", so "mkdirs" is intended
 370        for use after commands like "git checkout" or "git reset".
 371        (See the svn-remote.<name>.automkdirs config file option for
 372        more information.)
 373
 374'commit-diff'::
 375        Commits the diff of two tree-ish arguments from the
 376        command-line.  This command does not rely on being inside an `git svn
 377        init`-ed repository.  This command takes three arguments, (a) the
 378        original tree to diff against, (b) the new tree result, (c) the
 379        URL of the target Subversion repository.  The final argument
 380        (URL) may be omitted if you are working from a 'git svn'-aware
 381        repository (that has been `init`-ed with 'git svn').
 382        The -r<revision> option is required for this.
 383
 384'info'::
 385        Shows information about a file or directory similar to what
 386        `svn info' provides.  Does not currently support a -r/--revision
 387        argument.  Use the --url option to output only the value of the
 388        'URL:' field.
 389
 390'proplist'::
 391        Lists the properties stored in the Subversion repository about a
 392        given file or directory.  Use -r/--revision to refer to a specific
 393        Subversion revision.
 394
 395'propget'::
 396        Gets the Subversion property given as the first argument, for a
 397        file.  A specific revision can be specified with -r/--revision.
 398
 399'show-externals'::
 400        Shows the Subversion externals.  Use -r/--revision to specify a
 401        specific revision.
 402
 403'gc'::
 404        Compress $GIT_DIR/svn/<refname>/unhandled.log files in .git/svn
 405        and remove $GIT_DIR/svn/<refname>index files in .git/svn.
 406
 407'reset'::
 408        Undoes the effects of 'fetch' back to the specified revision.
 409        This allows you to re-'fetch' an SVN revision.  Normally the
 410        contents of an SVN revision should never change and 'reset'
 411        should not be necessary.  However, if SVN permissions change,
 412        or if you alter your --ignore-paths option, a 'fetch' may fail
 413        with "not found in commit" (file not previously visible) or
 414        "checksum mismatch" (missed a modification).  If the problem
 415        file cannot be ignored forever (with --ignore-paths) the only
 416        way to repair the repo is to use 'reset'.
 417+
 418Only the rev_map and refs/remotes/git-svn are changed.  Follow 'reset'
 419with a 'fetch' and then 'git reset' or 'git rebase' to move local
 420branches onto the new tree.
 421
 422-r <n>;;
 423--revision=<n>;;
 424        Specify the most recent revision to keep.  All later revisions
 425        are discarded.
 426-p;;
 427--parent;;
 428        Discard the specified revision as well, keeping the nearest
 429        parent instead.
 430Example:;;
 431Assume you have local changes in "master", but you need to refetch "r2".
 432+
 433------------
 434    r1---r2---r3 remotes/git-svn
 435                \
 436                 A---B master
 437------------
 438+
 439Fix the ignore-paths or SVN permissions problem that caused "r2" to
 440be incomplete in the first place.  Then:
 441+
 442[verse]
 443git svn reset -r2 -p
 444git svn fetch
 445+
 446------------
 447    r1---r2'--r3' remotes/git-svn
 448      \
 449       r2---r3---A---B master
 450------------
 451+
 452Then fixup "master" with 'git rebase'.
 453Do NOT use 'git merge' or your history will not be compatible with a
 454future 'dcommit'!
 455+
 456[verse]
 457git rebase --onto remotes/git-svn A^ master
 458+
 459------------
 460    r1---r2'--r3' remotes/git-svn
 461                \
 462                 A'--B' master
 463------------
 464
 465OPTIONS
 466-------
 467
 468--shared[=(false|true|umask|group|all|world|everybody)]::
 469--template=<template_directory>::
 470        Only used with the 'init' command.
 471        These are passed directly to 'git init'.
 472
 473-r <arg>::
 474--revision <arg>::
 475           Used with the 'fetch' command.
 476+
 477This allows revision ranges for partial/cauterized history
 478to be supported.  $NUMBER, $NUMBER1:$NUMBER2 (numeric ranges),
 479$NUMBER:HEAD, and BASE:$NUMBER are all supported.
 480+
 481This can allow you to make partial mirrors when running fetch;
 482but is generally not recommended because history will be skipped
 483and lost.
 484
 485-::
 486--stdin::
 487        Only used with the 'set-tree' command.
 488+
 489Read a list of commits from stdin and commit them in reverse
 490order.  Only the leading sha1 is read from each line, so
 491'git rev-list --pretty=oneline' output can be used.
 492
 493--rmdir::
 494        Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
 495+
 496Remove directories from the SVN tree if there are no files left
 497behind.  SVN can version empty directories, and they are not
 498removed by default if there are no files left in them.  git
 499cannot version empty directories.  Enabling this flag will make
 500the commit to SVN act like git.
 501+
 502[verse]
 503config key: svn.rmdir
 504
 505-e::
 506--edit::
 507        Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
 508+
 509Edit the commit message before committing to SVN.  This is off by
 510default for objects that are commits, and forced on when committing
 511tree objects.
 512+
 513[verse]
 514config key: svn.edit
 515
 516-l<num>::
 517--find-copies-harder::
 518        Only used with the 'dcommit', 'set-tree' and 'commit-diff' commands.
 519+
 520They are both passed directly to 'git diff-tree'; see
 521linkgit:git-diff-tree[1] for more information.
 522+
 523[verse]
 524config key: svn.l
 525config key: svn.findcopiesharder
 526
 527-A<filename>::
 528--authors-file=<filename>::
 529        Syntax is compatible with the file used by 'git cvsimport':
 530+
 531------------------------------------------------------------------------
 532        loginname = Joe User <user@example.com>
 533------------------------------------------------------------------------
 534+
 535If this option is specified and 'git svn' encounters an SVN
 536committer name that does not exist in the authors-file, 'git svn'
 537will abort operation. The user will then have to add the
 538appropriate entry.  Re-running the previous 'git svn' command
 539after the authors-file is modified should continue operation.
 540+
 541[verse]
 542config key: svn.authorsfile
 543
 544--authors-prog=<filename>::
 545        If this option is specified, for each SVN committer name that
 546        does not exist in the authors file, the given file is executed
 547        with the committer name as the first argument.  The program is
 548        expected to return a single line of the form "Name <email>",
 549        which will be treated as if included in the authors file.
 550
 551-q::
 552--quiet::
 553        Make 'git svn' less verbose. Specify a second time to make it
 554        even less verbose.
 555
 556--repack[=<n>]::
 557--repack-flags=<flags>::
 558        These should help keep disk usage sane for large fetches with
 559        many revisions.
 560+
 561--repack takes an optional argument for the number of revisions
 562to fetch before repacking.  This defaults to repacking every
 5631000 commits fetched if no argument is specified.
 564+
 565--repack-flags are passed directly to 'git repack'.
 566+
 567[verse]
 568config key: svn.repack
 569config key: svn.repackflags
 570
 571-m::
 572--merge::
 573-s<strategy>::
 574--strategy=<strategy>::
 575-p::
 576--preserve-merges::
 577        These are only used with the 'dcommit' and 'rebase' commands.
 578+
 579Passed directly to 'git rebase' when using 'dcommit' if a
 580'git reset' cannot be used (see 'dcommit').
 581
 582-n::
 583--dry-run::
 584        This can be used with the 'dcommit', 'rebase', 'branch' and
 585        'tag' commands.
 586+
 587For 'dcommit', print out the series of git arguments that would show
 588which diffs would be committed to SVN.
 589+
 590For 'rebase', display the local branch associated with the upstream svn
 591repository associated with the current branch and the URL of svn
 592repository that will be fetched from.
 593+
 594For 'branch' and 'tag', display the urls that will be used for copying when
 595creating the branch or tag.
 596
 597--use-log-author::
 598        When retrieving svn commits into git (as part of 'fetch', 'rebase', or
 599        'dcommit' operations), look for the first `From:` or `Signed-off-by:` line
 600        in the log message and use that as the author string.
 601--add-author-from::
 602        When committing to svn from git (as part of 'commit-diff', 'set-tree' or 'dcommit'
 603        operations), if the existing log message doesn't already have a
 604        `From:` or `Signed-off-by:` line, append a `From:` line based on the
 605        git commit's author string.  If you use this, then `--use-log-author`
 606        will retrieve a valid author string for all commits.
 607
 608
 609ADVANCED OPTIONS
 610----------------
 611
 612-i<GIT_SVN_ID>::
 613--id <GIT_SVN_ID>::
 614        This sets GIT_SVN_ID (instead of using the environment).  This
 615        allows the user to override the default refname to fetch from
 616        when tracking a single URL.  The 'log' and 'dcommit' commands
 617        no longer require this switch as an argument.
 618
 619-R<remote name>::
 620--svn-remote <remote name>::
 621        Specify the [svn-remote "<remote name>"] section to use,
 622        this allows SVN multiple repositories to be tracked.
 623        Default: "svn"
 624
 625--follow-parent::
 626        This is especially helpful when we're tracking a directory
 627        that has been moved around within the repository, or if we
 628        started tracking a branch and never tracked the trunk it was
 629        descended from. This feature is enabled by default, use
 630        --no-follow-parent to disable it.
 631+
 632[verse]
 633config key: svn.followparent
 634
 635CONFIG FILE-ONLY OPTIONS
 636------------------------
 637
 638svn.noMetadata::
 639svn-remote.<name>.noMetadata::
 640        This gets rid of the 'git-svn-id:' lines at the end of every commit.
 641+
 642This option can only be used for one-shot imports as 'git svn'
 643will not be able to fetch again without metadata. Additionally,
 644if you lose your .git/svn/**/.rev_map.* files, 'git svn' will not
 645be able to rebuild them.
 646+
 647The 'git svn log' command will not work on repositories using
 648this, either.  Using this conflicts with the 'useSvmProps'
 649option for (hopefully) obvious reasons.
 650+
 651This option is NOT recommended as it makes it difficult to track down
 652old references to SVN revision numbers in existing documentation, bug
 653reports and archives.  If you plan to eventually migrate from SVN to git
 654and are certain about dropping SVN history, consider
 655linkgit:git-filter-branch[1] instead.  filter-branch also allows
 656reformatting of metadata for ease-of-reading and rewriting authorship
 657info for non-"svn.authorsFile" users.
 658
 659svn.useSvmProps::
 660svn-remote.<name>.useSvmProps::
 661        This allows 'git svn' to re-map repository URLs and UUIDs from
 662        mirrors created using SVN::Mirror (or svk) for metadata.
 663+
 664If an SVN revision has a property, "svm:headrev", it is likely
 665that the revision was created by SVN::Mirror (also used by SVK).
 666The property contains a repository UUID and a revision.  We want
 667to make it look like we are mirroring the original URL, so
 668introduce a helper function that returns the original identity
 669URL and UUID, and use it when generating metadata in commit
 670messages.
 671
 672svn.useSvnsyncProps::
 673svn-remote.<name>.useSvnsyncprops::
 674        Similar to the useSvmProps option; this is for users
 675        of the svnsync(1) command distributed with SVN 1.4.x and
 676        later.
 677
 678svn-remote.<name>.rewriteRoot::
 679        This allows users to create repositories from alternate
 680        URLs.  For example, an administrator could run 'git svn' on the
 681        server locally (accessing via file://) but wish to distribute
 682        the repository with a public http:// or svn:// URL in the
 683        metadata so users of it will see the public URL.
 684
 685svn-remote.<name>.rewriteUUID::
 686        Similar to the useSvmProps option; this is for users who need
 687        to remap the UUID manually. This may be useful in situations
 688        where the original UUID is not available via either useSvmProps
 689        or useSvnsyncProps.
 690
 691svn-remote.<name>.pushurl::
 692
 693        Similar to git's 'remote.<name>.pushurl', this key is designed
 694        to be used in cases where 'url' points to an SVN repository
 695        via a read-only transport, to provide an alternate read/write
 696        transport. It is assumed that both keys point to the same
 697        repository. Unlike 'commiturl', 'pushurl' is a base path. If
 698        either 'commiturl' or 'pushurl' could be used, 'commiturl'
 699        takes precedence.
 700
 701svn.brokenSymlinkWorkaround::
 702        This disables potentially expensive checks to workaround
 703        broken symlinks checked into SVN by broken clients.  Set this
 704        option to "false" if you track a SVN repository with many
 705        empty blobs that are not symlinks.  This option may be changed
 706        while 'git svn' is running and take effect on the next
 707        revision fetched.  If unset, 'git svn' assumes this option to
 708        be "true".
 709
 710svn.pathnameencoding::
 711        This instructs git svn to recode pathnames to a given encoding.
 712        It can be used by windows users and by those who work in non-utf8
 713        locales to avoid corrupted file names with non-ASCII characters.
 714        Valid encodings are the ones supported by Perl's Encode module.
 715
 716svn-remote.<name>.automkdirs::
 717        Normally, the "git svn clone" and "git svn rebase" commands
 718        attempt to recreate empty directories that are in the
 719        Subversion repository.  If this option is set to "false", then
 720        empty directories will only be created if the "git svn mkdirs"
 721        command is run explicitly.  If unset, 'git svn' assumes this
 722        option to be "true".
 723
 724Since the noMetadata, rewriteRoot, rewriteUUID, useSvnsyncProps and useSvmProps
 725options all affect the metadata generated and used by 'git svn'; they
 726*must* be set in the configuration file before any history is imported
 727and these settings should never be changed once they are set.
 728
 729Additionally, only one of these options can be used per svn-remote
 730section because they affect the 'git-svn-id:' metadata line, except
 731for rewriteRoot and rewriteUUID which can be used together.
 732
 733
 734BASIC EXAMPLES
 735--------------
 736
 737Tracking and contributing to the trunk of a Subversion-managed project:
 738
 739------------------------------------------------------------------------
 740# Clone a repo (like git clone):
 741        git svn clone http://svn.example.com/project/trunk
 742# Enter the newly cloned directory:
 743        cd trunk
 744# You should be on master branch, double-check with 'git branch'
 745        git branch
 746# Do some work and commit locally to git:
 747        git commit ...
 748# Something is committed to SVN, rebase your local changes against the
 749# latest changes in SVN:
 750        git svn rebase
 751# Now commit your changes (that were committed previously using git) to SVN,
 752# as well as automatically updating your working HEAD:
 753        git svn dcommit
 754# Append svn:ignore settings to the default git exclude file:
 755        git svn show-ignore >> .git/info/exclude
 756------------------------------------------------------------------------
 757
 758Tracking and contributing to an entire Subversion-managed project
 759(complete with a trunk, tags and branches):
 760
 761------------------------------------------------------------------------
 762# Clone a repo (like git clone):
 763        git svn clone http://svn.example.com/project -T trunk -b branches -t tags
 764# View all branches and tags you have cloned:
 765        git branch -r
 766# Create a new branch in SVN
 767    git svn branch waldo
 768# Reset your master to trunk (or any other branch, replacing 'trunk'
 769# with the appropriate name):
 770        git reset --hard remotes/trunk
 771# You may only dcommit to one branch/tag/trunk at a time.  The usage
 772# of dcommit/rebase/show-ignore should be the same as above.
 773------------------------------------------------------------------------
 774
 775The initial 'git svn clone' can be quite time-consuming
 776(especially for large Subversion repositories). If multiple
 777people (or one person with multiple machines) want to use
 778'git svn' to interact with the same Subversion repository, you can
 779do the initial 'git svn clone' to a repository on a server and
 780have each person clone that repository with 'git clone':
 781
 782------------------------------------------------------------------------
 783# Do the initial import on a server
 784        ssh server "cd /pub && git svn clone http://svn.example.com/project
 785# Clone locally - make sure the refs/remotes/ space matches the server
 786        mkdir project
 787        cd project
 788        git init
 789        git remote add origin server:/pub/project
 790        git config --replace-all remote.origin.fetch '+refs/remotes/*:refs/remotes/*'
 791        git fetch
 792# Prevent fetch/pull from remote git server in the future,
 793# we only want to use git svn for future updates
 794        git config --remove-section remote.origin
 795# Create a local branch from one of the branches just fetched
 796        git checkout -b master FETCH_HEAD
 797# Initialize 'git svn' locally (be sure to use the same URL and -T/-b/-t options as were used on server)
 798        git svn init http://svn.example.com/project
 799# Pull the latest changes from Subversion
 800        git svn rebase
 801------------------------------------------------------------------------
 802
 803REBASE VS. PULL/MERGE
 804---------------------
 805
 806Originally, 'git svn' recommended that the 'remotes/git-svn' branch be
 807pulled or merged from.  This is because the author favored
 808`git svn set-tree B` to commit a single head rather than the
 809`git svn set-tree A..B` notation to commit multiple commits.
 810
 811If you use `git svn set-tree A..B` to commit several diffs and you do
 812not have the latest remotes/git-svn merged into my-branch, you should
 813use `git svn rebase` to update your work branch instead of `git pull` or
 814`git merge`.  `pull`/`merge` can cause non-linear history to be flattened
 815when committing into SVN, which can lead to merge commits reversing
 816previous commits in SVN.
 817
 818MERGE TRACKING
 819--------------
 820While 'git svn' can track
 821copy history (including branches and tags) for repositories adopting a
 822standard layout, it cannot yet represent merge history that happened
 823inside git back upstream to SVN users.  Therefore it is advised that
 824users keep history as linear as possible inside git to ease
 825compatibility with SVN (see the CAVEATS section below).
 826
 827CAVEATS
 828-------
 829
 830For the sake of simplicity and interoperating with Subversion,
 831it is recommended that all 'git svn' users clone, fetch and dcommit
 832directly from the SVN server, and avoid all 'git clone'/'pull'/'merge'/'push'
 833operations between git repositories and branches.  The recommended
 834method of exchanging code between git branches and users is
 835'git format-patch' and 'git am', or just 'dcommit'ing to the SVN repository.
 836
 837Running 'git merge' or 'git pull' is NOT recommended on a branch you
 838plan to 'dcommit' from because Subversion users cannot see any
 839merges you've made.  Furthermore, if you merge or pull from a git branch
 840that is a mirror of an SVN branch, 'dcommit' may commit to the wrong
 841branch.
 842
 843If you do merge, note the following rule: 'git svn dcommit' will
 844attempt to commit on top of the SVN commit named in
 845------------------------------------------------------------------------
 846git log --grep=^git-svn-id: --first-parent -1
 847------------------------------------------------------------------------
 848You 'must' therefore ensure that the most recent commit of the branch
 849you want to dcommit to is the 'first' parent of the merge.  Chaos will
 850ensue otherwise, especially if the first parent is an older commit on
 851the same SVN branch.
 852
 853'git clone' does not clone branches under the refs/remotes/ hierarchy or
 854any 'git svn' metadata, or config.  So repositories created and managed with
 855using 'git svn' should use 'rsync' for cloning, if cloning is to be done
 856at all.
 857
 858Since 'dcommit' uses rebase internally, any git branches you 'git push' to
 859before 'dcommit' on will require forcing an overwrite of the existing ref
 860on the remote repository.  This is generally considered bad practice,
 861see the linkgit:git-push[1] documentation for details.
 862
 863Do not use the --amend option of linkgit:git-commit[1] on a change you've
 864already dcommitted.  It is considered bad practice to --amend commits
 865you've already pushed to a remote repository for other users, and
 866dcommit with SVN is analogous to that.
 867
 868When using multiple --branches or --tags, 'git svn' does not automatically
 869handle name collisions (for example, if two branches from different paths have
 870the same name, or if a branch and a tag have the same name).  In these cases,
 871use 'init' to set up your git repository then, before your first 'fetch', edit
 872the .git/config file so that the branches and tags are associated with
 873different name spaces.  For example:
 874
 875        branches = stable/*:refs/remotes/svn/stable/*
 876        branches = debug/*:refs/remotes/svn/debug/*
 877
 878BUGS
 879----
 880
 881We ignore all SVN properties except svn:executable.  Any unhandled
 882properties are logged to $GIT_DIR/svn/<refname>/unhandled.log
 883
 884Renamed and copied directories are not detected by git and hence not
 885tracked when committing to SVN.  I do not plan on adding support for
 886this as it's quite difficult and time-consuming to get working for all
 887the possible corner cases (git doesn't do it, either).  Committing
 888renamed and copied files is fully supported if they're similar enough
 889for git to detect them.
 890
 891CONFIGURATION
 892-------------
 893
 894'git svn' stores [svn-remote] configuration information in the
 895repository .git/config file.  It is similar the core git
 896[remote] sections except 'fetch' keys do not accept glob
 897arguments; but they are instead handled by the 'branches'
 898and 'tags' keys.  Since some SVN repositories are oddly
 899configured with multiple projects glob expansions such those
 900listed below are allowed:
 901
 902------------------------------------------------------------------------
 903[svn-remote "project-a"]
 904        url = http://server.org/svn
 905        fetch = trunk/project-a:refs/remotes/project-a/trunk
 906        branches = branches/*/project-a:refs/remotes/project-a/branches/*
 907        tags = tags/*/project-a:refs/remotes/project-a/tags/*
 908------------------------------------------------------------------------
 909
 910Keep in mind that the '\*' (asterisk) wildcard of the local ref
 911(right of the ':') *must* be the farthest right path component;
 912however the remote wildcard may be anywhere as long as it's an
 913independent path component (surrounded by '/' or EOL).   This
 914type of configuration is not automatically created by 'init' and
 915should be manually entered with a text-editor or using 'git config'.
 916
 917It is also possible to fetch a subset of branches or tags by using a
 918comma-separated list of names within braces. For example:
 919
 920------------------------------------------------------------------------
 921[svn-remote "huge-project"]
 922        url = http://server.org/svn
 923        fetch = trunk/src:refs/remotes/trunk
 924        branches = branches/{red,green}/src:refs/remotes/branches/*
 925        tags = tags/{1.0,2.0}/src:refs/remotes/tags/*
 926------------------------------------------------------------------------
 927
 928Note that git-svn keeps track of the highest revision in which a branch
 929or tag has appeared. If the subset of branches or tags is changed after
 930fetching, then .git/svn/.metadata must be manually edited to remove (or
 931reset) branches-maxRev and/or tags-maxRev as appropriate.
 932
 933SEE ALSO
 934--------
 935linkgit:git-rebase[1]
 936
 937GIT
 938---
 939Part of the linkgit:git[1] suite