Currently, the git-svn defaults to using an empty prefix, which ends
up placing the SVN-tracking refs directly in refs/remotes/*. This
placement runs counter to Git's convention of placing remote-tracking
branches in refs/remotes/$remote/*.

Furthermore, combining git-svn with "regular" Git remotes run the risk
of clobbering refs under refs/remotes (e.g. if you have a git remote
called "tags" with a "v1" branch, it will overlap with the git-svn's
tracking branch for the "v1" tag from Subversion.

Even though the git-svn refs stored in refs/remotes/* are not "proper"
remote-tracking branches (since they are not covered by a proper git
remote's refspec), they clearly represent a similar concept, and would
benefit from following the same convention.

For example, if git-svn tracks Subversion branch "foo" at
refs/remotes/foo, and you create a local branch refs/heads/foo to add
some commits to be pushed back to Subversion (using "git svn dcommit),
then it is clearly unhelpful of Git to throw

  warning: refname 'foo' is ambiguous.

every time you checkout, rebase, or otherwise interact with the branch.

At this time, the user is better off using the --prefix=foo/ (the
trailing slash is important) to git svn init/clone, to cause the
SVN-tracking refs to be placed at refs/remotes/foo/* instead of
refs/remotes/*. This patch updates the documentation to encourage
use of --prefix.

This is also in preparation for changing the default value of --prefix
at some point in the future.

Cc: Eric Wong <>
Signed-off-by: Johan Herland <>
 Documentation/git-svn.txt | 35 +++++++++++++++++++++++++----------
 1 file changed, 25 insertions(+), 10 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 4dd3bcb..ac0c72f 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -79,8 +79,13 @@ COMMANDS
        trailing slash, so be sure you include one in the
        argument if that is what you want.  If --branches/-b is
        specified, the prefix must include a trailing slash.
-       Setting a prefix is useful if you wish to track multiple
-       projects that share a common repository.
+       Setting a prefix (with a trailing slash) is strongly
+       encouraged in any case, as your SVN-tracking refs will
+       then be located at "refs/remotes/$prefix/*", which is
+       compatible with Git's own remote-tracking ref layout
+       (refs/remotes/$remote/*). Setting a prefix is also useful
+       if you wish to track multiple projects that share a common
+       repository.
        When passed to 'init' or 'clone' this regular expression will
        be preserved as a config key.  See 'fetch' for a description
@@ -804,16 +809,16 @@ Tracking and contributing to an entire Subversion-managed 
 # Clone a repo with standard SVN directory layout (like git clone):
-       git svn clone --stdlayout
+       git svn clone --stdlayout --prefix svn/
 # Or, if the repo uses a non-standard directory layout:
-       git svn clone -T tr -b branch -t tag
+       git svn clone -T tr -b branch -t tag 
--prefix svn/
 # View all branches and tags you have cloned:
        git branch -r
 # Create a new branch in SVN
     git svn branch waldo
 # Reset your master to trunk (or any other branch, replacing 'trunk'
 # with the appropriate name):
-       git reset --hard remotes/trunk
+       git reset --hard svn/trunk
 # You may only dcommit to one branch/tag/trunk at a time.  The usage
 # of dcommit/rebase/show-ignore should be the same as above.
@@ -827,7 +832,7 @@ have each person clone that repository with 'git clone':
 # Do the initial import on a server
-       ssh server "cd /pub && git svn clone
+       ssh server "cd /pub && git svn clone 
 # Clone locally - make sure the refs/remotes/ space matches the server
        mkdir project
        cd project
@@ -840,8 +845,9 @@ have each person clone that repository with 'git clone':
        git config --remove-section remote.origin
 # Create a local branch from one of the branches just fetched
        git checkout -b master FETCH_HEAD
-# Initialize 'git svn' locally (be sure to use the same URL and -T/-b/-t 
options as were used on server)
-       git svn init
+# Initialize 'git svn' locally (be sure to use the same URL and
+# --stdlayout/-T/-b/-t/--prefix options as were used on server)
+       git svn init [options...]
 # Pull the latest changes from Subversion
        git svn rebase
@@ -973,6 +979,15 @@ without giving any repository layout options.  If the full 
history with
 branches and tags is required, the options '--trunk' / '--branches' /
 '--tags' must be used.
+When using the options for describing the repository layout (--trunk,
+--tags, --branches, --stdlayout), please also specify the --prefix
+option (e.g. '--prefix=origin/') to cause your SVN-tracking refs to be
+placed at refs/remotes/origin/* rather than the default refs/remotes/*.
+The former is more compatible with the layout of Git's "regular"
+remote-tracking refs (refs/remotes/$remote/*), and may potentially
+prevent similarly named SVN branches and Git remotes from clobbering
+each other.
 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,
@@ -1035,8 +1050,8 @@ comma-separated list of names within braces. For example:
 [svn-remote "huge-project"]
        url =
        fetch = trunk/src:refs/remotes/trunk
-       branches = branches/{red,green}/src:refs/remotes/branches/*
-       tags = tags/{1.0,2.0}/src:refs/remotes/tags/*
+       branches = branches/{red,green}/src:refs/remotes/project-a/branches/*
+       tags = tags/{1.0,2.0}/src:refs/remotes/project-a/tags/*
 Multiple fetch, branches, and tags keys are supported:

To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to
More majordomo info at

Reply via email to