Documentation/git-svn: Promote the use of --prefix in docs + examples

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 <normalperson@yhbt.net>
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Eric Wong <normalperson@yhbt.net>

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 5383496cbb56864df3bb95a2ebbca563b520f27b..f1417deb994143030ad42a5bafc055944e704d93 100644 (file)
--- 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.
        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.

 --ignore-paths=<regex>;;
        When passed to 'init' or 'clone' this regular expression will
        be preserved as a config key.  See 'fetch' for a description
 --ignore-paths=<regex>;;
        When passed to 'init' or 'clone' this regular expression will
        be preserved as a config key.  See 'fetch' for a description


@@ -811,16 +816,16 @@ Tracking and contributing to an entire Subversion-managed project
 
 ------------------------------------------------------------------------
 # Clone a repo with standard SVN directory layout (like git clone):
 
 ------------------------------------------------------------------------
 # Clone a repo with standard SVN directory layout (like git clone):

-       git svn clone http://svn.example.com/project --stdlayout
+       git svn clone http://svn.example.com/project --stdlayout --prefix svn/

 # Or, if the repo uses a non-standard directory layout:
 # Or, if the repo uses a non-standard directory layout:

-       git svn clone http://svn.example.com/project -T tr -b branch -t tag
+       git svn clone http://svn.example.com/project -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):
 # 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.
 ------------------------------------------------------------------------
 # 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.
 ------------------------------------------------------------------------


@@ -834,7 +839,7 @@ have each person clone that repository with 'git clone':
 
 ------------------------------------------------------------------------
 # Do the initial import on a server
 
 ------------------------------------------------------------------------
 # Do the initial import on a server

-       ssh server "cd /pub && git svn clone http://svn.example.com/project
+       ssh server "cd /pub && git svn clone http://svn.example.com/project [options...]"

 # Clone locally - make sure the refs/remotes/ space matches the server
        mkdir project
        cd project
 # Clone locally - make sure the refs/remotes/ space matches the server
        mkdir project
        cd project


@@ -847,8 +852,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
        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 http://svn.example.com/project
+# 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 http://svn.example.com/project [options...]

 # Pull the latest changes from Subversion
        git svn rebase
 ------------------------------------------------------------------------
 # Pull the latest changes from Subversion
        git svn rebase
 ------------------------------------------------------------------------


@@ -980,6 +986,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.
 
 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,
 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,


@@ -1042,8 +1057,8 @@ comma-separated list of names within braces. For example:
 [svn-remote "huge-project"]
        url = http://server.org/svn
        fetch = trunk/src:refs/remotes/trunk
 [svn-remote "huge-project"]
        url = http://server.org/svn
        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:
 ------------------------------------------------------------------------
 
 Multiple fetch, branches, and tags keys are supported: