Re: [PATCH v2 2/4] Recommend use of structure options for git svn.

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 3, 2012, 19:30 UTC
Message-ID: <7v7gozq6ge.fsf@alter.siamese.dyndns.org>
In-Reply-To: <5cb2f71bc9be3323e425205020105dcfd948fca5.1354324110.git.Sebastian.Leske@sleske.name>

Sebastian Leske <Sebastian.Leske@sleske.name> writes:

Show 35 quoted lines

> 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>
> ---
>  Documentation/git-svn.txt |   24 +++++++++++++++++++++---
>  1 file changed, 21 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
> index 824bf82..bfa8788 100644
> --- a/Documentation/git-svn.txt
> +++ b/Documentation/git-svn.txt
> @@ -739,7 +739,8 @@ for rewriteRoot and rewriteUUID which can be used together.
>  BASIC EXAMPLES
>  --------------
>  
> -Tracking and contributing to the trunk of a Subversion-managed project:
> +Tracking and contributing to the trunk of a Subversion-managed project
> +(ignoring tags and branches):
>  
>  ------------------------------------------------------------------------
>  # Clone a repo (like git clone):
> @@ -764,8 +765,10 @@ Tracking and contributing to an entire Subversion-managed project
>  (complete with a trunk, tags and branches):
>  
>  ------------------------------------------------------------------------
> -# Clone a repo (like git clone):
> -	git svn clone http://svn.example.com/project -T trunk -b branches -t tags
> +# Clone a repo with standard SVN directory layout (like git clone):
> +	git svn clone http://svn.example.com/project --stdlayout
> +# Or, if the repo uses a non-standard directory layout:
> +	git svn clone http://svn.example.com/project -T tr -b branch -t tag

These command line, given that the SYNPOSIS section says:

	git svn <command> [options] [arguments]

look strange to have the URL argument before all the options.

Because the original shares the same trait, this should not be fixed in this patch, but it may be a good idea to fix the order of the arguments in a separate follow-up patch.

Show 9 quoted lines

> @@ -871,6 +874,21 @@ 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 cloning an SVN repository, if none of the options for describing
> +the repository layout is used (--trunk, --tags, --branches,
> +--stdlayout), 'git svn clone' will create a git repository with
> +completely linear history, where branches and tags appear as separate
> +folders in the working copy.  ...

As existing text in git-svn.txt consistently uses "directory" and never "folder", please match that terminology (like you did in a later sentence in your patch).

Show 14 quoted lines

> ...  While this is the easiest way to get a
> +copy of a complete repository, for projects with many branches it will
> +lead to a working copy many times larger than just the trunk. Thus for
> +projects using the standard directory structure (trunk/branches/tags),
> +it is recommended to clone with option '--stdlayout'. If the project
> +uses a non-standard structure, and/or if branches and tags are not
> +required, it is easiest to only clone one directory (typically trunk),
> +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 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,