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
91583a6a8517afd76a78720d8c060d8ad9f03784
1 file changed
+21
-3
Documentation/git-svn.txt
+21
-3
@@ -732,7 +732,8 @@ for rewriteRoot and rewriteUUID which can be used together.
732
BASIC EXAMPLES
733
--------------
734
735
-Tracking and contributing to the trunk of a Subversion-managed project:
735
+Tracking and contributing to the trunk of a Subversion-managed project
736
+(ignoring tags and branches):
737
738
------------------------------------------------------------------------
739
# Clone a repo (like git clone):
@@ -757,8 +758,10 @@ Tracking and contributing to an entire Subversion-managed project
758
(complete with a trunk, tags and branches):
759
760
------------------------------------------------------------------------
760
-# Clone a repo (like git clone):
761
- git svn clone http://svn.example.com/project -T trunk -b branches -t tags
761
+# Clone a repo with standard SVN directory layout (like git clone):
762
+ git svn clone http://svn.example.com/project --stdlayout
763
+# Or, if the repo uses a non-standard directory layout:
764
+ git svn clone http://svn.example.com/project -T tr -b branch -t tag
765
# View all branches and tags you have cloned:
766
git branch -r
767
# Create a new branch in SVN
@@ -910,6 +913,21 @@ already dcommitted. It is considered bad practice to --amend commits
913
you've already pushed to a remote repository for other users, and
914
dcommit with SVN is analogous to that.
915
916
+When cloning an SVN repository, if none of the options for describing
917
+the repository layout is used (--trunk, --tags, --branches,
918
+--stdlayout), 'git svn clone' will create a git repository with
919
+completely linear history, where branches and tags appear as separate
920
+directories in the working copy. While this is the easiest way to get a
921
+copy of a complete repository, for projects with many branches it will
922
+lead to a working copy many times larger than just the trunk. Thus for
923
+projects using the standard directory structure (trunk/branches/tags),
924
+it is recommended to clone with option '--stdlayout'. If the project
925
+uses a non-standard structure, and/or if branches and tags are not
926
+required, it is easiest to only clone one directory (typically trunk),
927
+without giving any repository layout options. If the full history with
928
+branches and tags is required, the options '--trunk' / '--branches' /
929
+'--tags' must be used.
930
+
931
When using multiple --branches or --tags, 'git svn' does not automatically
932
handle name collisions (for example, if two branches from different paths have
933
the same name, or if a branch and a tag have the same name). In these cases,