git svn: Doc update for multiple branch and tag paths

Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
Acked-by: Eric Wong <normalperson@yhbt.net>

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 3f0fa5e6f1b3485232cc5045252e251a575f9111..7e9b9a042347bf286c6ea523bef1952f0c72dec9 100644 (file)
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -3,7 +3,7 @@ git-svn(1)
 
 NAME
 ----
-git-svn - Bidirectional operation between a single Subversion branch and git
+git-svn - Bidirectional operation between a Subversion repository and git
 
 SYNOPSIS
 --------
@@ -15,13 +15,12 @@ DESCRIPTION
 It provides a bidirectional flow of changes between a Subversion and a git
 repository.
 
-'git-svn' can track a single Subversion branch simply by using a
-URL to the branch, follow branches laid out in the Subversion recommended
-method (trunk, branches, tags directories) with the --stdlayout option, or
-follow branches in any layout with the -T/-t/-b options (see options to
-'init' below, and also the 'clone' command).
+'git-svn' can track a standard Subversion repository,
+following the common "trunk/branches/tags" layout, with the --stdlayout option.
+It can also follow branches and tags in any layout with the -T/-t/-b options
+(see options to 'init' below, and also the 'clone' command).
 
-Once tracking a Subversion branch (with any of the above methods), the git
+Once tracking a Subversion repository (with any of the above methods), the git
 repository can be updated from Subversion by the 'fetch' command and
 Subversion updated from git by the 'dcommit' command.
 
@@ -48,8 +47,11 @@ COMMANDS
 --stdlayout;;
        These are optional command-line options for init.  Each of
        these flags can point to a relative repository path
-       (--tags=project/tags') or a full url
-       (--tags=https://foo.org/project/tags). The option --stdlayout is
+       (--tags=project/tags) or a full url
+       (--tags=https://foo.org/project/tags).
+       You can specify more than one --tags and/or --branches options, in case
+       your Subversion repository places tags or branches under multiple paths.
+       The option --stdlayout is
        a shorthand way of setting trunk,tags,branches as the relative paths,
        which is the Subversion default. If any of the other options are given
        as well, they take precedence.
@@ -205,6 +207,20 @@ config key: svn.commiturl (overwrites all svn-remote.<name>.commiturl options)
        Create a tag by using the tags_subdir instead of the branches_subdir
        specified during git svn init.
 
+-d;;
+--destination;;
+       If more than one --branches (or --tags) option was given to the 'init'
+       or 'clone' command, you must provide the location of the branch (or
+       tag) you wish to create in the SVN repository.  The value of this
+       option must match one of the paths specified by a --branches (or
+       --tags) option.  You can see these paths with the commands
++
+       git config --get-all svn-remote.<name>.branches
+       git config --get-all svn-remote.<name>.tags
++
+where <name> is the name of the SVN repository as specified by the -R option to
+'init' (or "svn" by default).
+
 'tag'::
        Create a tag in the SVN repository. This is a shorthand for
        'branch -t'.
@@ -727,6 +743,16 @@ already dcommitted.  It is considered bad practice to --amend commits
 you've already pushed to a remote repository for other users, and
 dcommit with SVN is analogous to that.
 
+When using multiple --branches or --tags, 'git-svn' does not automatically
+handle name collisions (for example, if two branches from different paths have
+the same name, or if a branch and a tag have the same name).  In these cases,
+use 'init' to set up your git repository then, before your first 'fetch', edit
+the .git/config file so that the branches and tags are associated with
+different name spaces.  For example:
+
+       branches = stable/*:refs/remotes/svn/stable/*
+       branches = debug/*:refs/remotes/svn/debug/*
+
 BUGS
 ----