git-svn: Recommend use of structure options.
Document that when using git svn, one should usually either use the directory structure options to import branches as branches, or only import one subdirectory. The default behaviour of cloning all branches and tags as subdirectories in the working copy is usually not what the user wants. Signed-off-by: Sebastian Leske <sebastian.leske@sleske.name> Acked-by: Eric Wong <normalperson@yhbt.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Sebastian Leske committed
Nov 30, 2012 at 08:16 UTC
92166fd7b4538029d60ceb1ce2065f85b8186a70
1 file changed
+21
-3
Documentation/git-svn.txt
+21
-3
@@ -739,7 +739,8 @@ for rewriteRoot and rewriteUUID which can be used together.
739
BASIC EXAMPLES
740
--------------
741
742
-Tracking and contributing to the trunk of a Subversion-managed project:
742
+Tracking and contributing to the trunk of a Subversion-managed project
743
+(ignoring tags and branches):
744
745
------------------------------------------------------------------------
746
# Clone a repo (like git clone):
@@ -764,8 +765,10 @@ Tracking and contributing to an entire Subversion-managed project
765
(complete with a trunk, tags and branches):
766
767
------------------------------------------------------------------------
767
-# Clone a repo (like git clone):
768
- git svn clone http://svn.example.com/project -T trunk -b branches -t tags
768
+# Clone a repo with standard SVN directory layout (like git clone):
769
+ git svn clone http://svn.example.com/project --stdlayout
770
+# Or, if the repo uses a non-standard directory layout:
771
+ git svn clone http://svn.example.com/project -T tr -b branch -t tag
772
# View all branches and tags you have cloned:
773
git branch -r
774
# Create a new branch in SVN
@@ -917,6 +920,21 @@ already dcommitted. It is considered bad practice to --amend commits
920
you've already pushed to a remote repository for other users, and
921
dcommit with SVN is analogous to that.
922
923
+When cloning an SVN repository, if none of the options for describing
924
+the repository layout is used (--trunk, --tags, --branches,
925
+--stdlayout), 'git svn clone' will create a git repository with
926
+completely linear history, where branches and tags appear as separate
927
+directories in the working copy. While this is the easiest way to get a
928
+copy of a complete repository, for projects with many branches it will
929
+lead to a working copy many times larger than just the trunk. Thus for
930
+projects using the standard directory structure (trunk/branches/tags),
931
+it is recommended to clone with option '--stdlayout'. If the project
932
+uses a non-standard structure, and/or if branches and tags are not
933
+required, it is easiest to only clone one directory (typically trunk),
934
+without giving any repository layout options. If the full history with
935
+branches and tags is required, the options '--trunk' / '--branches' /
936
+'--tags' must be used.
937
+
938
When using multiple --branches or --tags, 'git svn' does not automatically
939
handle name collisions (for example, if two branches from different paths have
940
the same name, or if a branch and a tag have the same name). In these cases,