[PATCH v2 0/4] git-svn: More docs for branch handling in

[PATCH v2 0/4] git-svn: More docs for branch handling in

[Sebastian Leske]

Updated version of my documentation patch for git-svn. Thanks to Michael
J Gruber and Eric Wong for helpful comments.

Sebastian Leske (4):
  git-svn: Document branches with at-sign(@).
  Recommend use of structure options for git svn.
  git-svn: Expand documentation for --follow-parent
  git-svn: Note about tags.

 Documentation/git-svn.txt |   84 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 78 insertions(+), 6 deletions(-)

-- 
1.7.10.4

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

[Sebastian Leske]

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
 # View all branches and tags you have cloned:
 	git branch -r
 # Create a new branch in SVN
@@ -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.  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,
-- 
1.7.10.4

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

[Junio C Hamano]

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

> 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.

> @@ -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).

> ...  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,

[PATCH v2 1/4] git-svn: Document branches with at-sign(@).

[Sebastian Leske]

git svn will sometimes create branches with an at-sign in the name
(branchname@revision). These branches confuse many users and it is a FAQ
why they are created. Document when git svn will create them.

Signed-off-by: Sebastian Leske <sebastian.leske@sleske.name>
---
 Documentation/git-svn.txt |   38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 8b0d3ad..824bf82 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -881,6 +881,44 @@ different name spaces.  For example:
 	branches = stable/*:refs/remotes/svn/stable/*
 	branches = debug/*:refs/remotes/svn/debug/*
 
+If 'git svn' is configured to fetch branches (and --follow-branches
+is in effect), it will sometimes create multiple branches for one SVN
+branch, where the addtional branches have names of the form
+'branchname@nnn' (with nnn an SVN revision number).  These additional
+branches are created if 'git svn' cannot find a parent commit for the
+first commit in an SVN branch, to connect the branch to the history of
+the other branches. Normally, the first commit in an SVN branch consists
+of a copy operation. 'git svn' will read this commit to get the SVN
+revision the branch was created (copied) from. It will then try to find the
+git commit that corresponds to this SVN revision, and use that as the
+parent of the branch. However, it is possible that there is no suitable
+git commit to serve as parent.  This will happen, among other reasons,
+if the SVN branch is a copy of a revision that was not fetched by 'git
+svn' (e.g. because it is an old revision that was skipped with
+'--revision'), or if in SVN a directory was copied that is not tracked
+by 'git svn' (such as a branch that is not tracked at all, or a
+subdirectory of a tracked branch). In these cases, 'git svn' will still
+create a git branch, but instead of using an existing git commit as the
+parent of the branch, it will read the SVN history of the directory the
+branch was copied from and create appropriate git commits (this is
+indicated by the message "Initializing parent: <branchname>").
+Additionally, it will create a special branch named
+'<branchname>@<SVN-Revision>', where <SVN-Revision> is the SVN revision
+number the branch was copied from.  This branch will point to the newly 
+created parent commit of the branch.  If in SVN the branch was deleted
+and later recreated from a different version, there will be multiple
+such branches with an '@'.
+Note that this may mean that multiple git commits are created for a
+single SVN revision. An example: In an SVN repository with a standard 
+trunk/tags/branches layout, a directory trunk/sub is created in r.100.
+In r.200, trunk/sub is branched by copying it to branches/. 'git svn
+clone -s' will then create a branch 'sub'. It will also create new git
+commits for r.100 through r.199 and use these as the history of branch
+'sub'. Thus there will be two git commits for each revision from r.100
+to r.199 (one containing trunk/, one containing trunk/sub/). Finally,
+it will create a branch 'sub@200' pointing to the new parent commit of
+branch 'sub' (i.e. the commit for r.200 and trunk/sub/).
+
 BUGS
 ----
 
-- 
1.7.10.4

Re: [PATCH v2 1/4] git-svn: Document branches with at-sign(@).

[Junio C Hamano]

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

> git svn will sometimes create branches with an at-sign in the name

It may be just me but "git svn sometimes creates" without "will"
reads much better to me (there is the same phrasing in the patch
text as well).

> (branchname@revision). These branches confuse many users and it is a FAQ
> why they are created. Document when git svn will create them.
>
> Signed-off-by: Sebastian Leske <sebastian.leske@sleske.name>
> ---
>  Documentation/git-svn.txt |   38 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 38 insertions(+)
>
> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
> index 8b0d3ad..824bf82 100644
> --- a/Documentation/git-svn.txt
> +++ b/Documentation/git-svn.txt
> @@ -881,6 +881,44 @@ different name spaces.  For example:
>  	branches = stable/*:refs/remotes/svn/stable/*
>  	branches = debug/*:refs/remotes/svn/debug/*
>  
> +If 'git svn' is configured to fetch branches (and --follow-branches
> +is in effect), it will sometimes create multiple branches for one SVN
> +branch, where the addtional branches have names of the form
> +'branchname@nnn' (with nnn an SVN revision number).  These additional
> +branches are created if 'git svn' cannot find a parent commit for the
> +first commit in an SVN branch, to connect the branch to the history of
> +the other branches. Normally, the first commit in an SVN branch consists
> +of a copy operation. 'git svn' will read this commit to get the SVN
> +revision the branch was created (copied) from. It will then try to find the
> +git commit that corresponds to this SVN revision, and use that as the
> +parent of the branch. However, it is possible that there is no suitable
> +git commit to serve as parent.  This will happen, among other reasons,
> +if the SVN branch is a copy of a revision that was not fetched by 'git
> +svn' (e.g. because it is an old revision that was skipped with
> +'--revision'), or if in SVN a directory was copied that is not tracked
> +by 'git svn' (such as a branch that is not tracked at all, or a
> +subdirectory of a tracked branch). In these cases, 'git svn' will still
> +create a git branch, but instead of using an existing git commit as the
> +parent of the branch, it will read the SVN history of the directory the
> +branch was copied from and create appropriate git commits (this is
> +indicated by the message "Initializing parent: <branchname>").
> +Additionally, it will create a special branch named
> +'<branchname>@<SVN-Revision>', where <SVN-Revision> is the SVN revision
> +number the branch was copied from.  This branch will point to the newly 
> +created parent commit of the branch.  If in SVN the branch was deleted
> +and later recreated from a different version, there will be multiple
> +such branches with an '@'.
> +Note that this may mean that multiple git commits are created for a
> +single SVN revision. An example: In an SVN repository with a standard 
> +trunk/tags/branches layout, a directory trunk/sub is created in r.100.
> +In r.200, trunk/sub is branched by copying it to branches/. 'git svn
> +clone -s' will then create a branch 'sub'. It will also create new git
> +commits for r.100 through r.199 and use these as the history of branch
> +'sub'. Thus there will be two git commits for each revision from r.100
> +to r.199 (one containing trunk/, one containing trunk/sub/). Finally,
> +it will create a branch 'sub@200' pointing to the new parent commit of
> +branch 'sub' (i.e. the commit for r.200 and trunk/sub/).
> +

Have you looked at the formatted result?  This is quite detailed and
long, and may deserve to be split into a few paragraphs.  I'd
probably suggest a paragraph break before "Normally, the first...",
"Additionally", "Note that", and "An example:"

[PATCH v2 3/4] git-svn: Expand documentation for --follow-parent

[Sebastian Leske]

Describe what the option --follow-parent does, and what happens if it is
set or unset.

Signed-off-by: Sebastian Leske <sebastian.leske@sleske.name>
---
 Documentation/git-svn.txt |   15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index bfa8788..6bda014 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -628,10 +628,19 @@ ADVANCED OPTIONS
 	Default: "svn"
 
 --follow-parent::
+	This option is only relevant if we are tracking branches (using
+	one of the repository layout options --trunk, --tags,
+	--branches, --stdlayout). For each tracked branch, try to find
+	out where its revision was copied (i.e. branched) from, and set
+	a suitable parent in the first git commit for the branch.
 	This is especially helpful when we're tracking a directory
-	that has been moved around within the repository, or if we
-	started tracking a branch and never tracked the trunk it was
-	descended from. This feature is enabled by default, use
+	that has been moved around within the repository.  If this
+	feature is disabled, the branches created by 'git svn' will all
+	be linear and not share any history, meaning that there will be
+	no information on where branches where branched off or merged.
+	However, following long/convoluted histories can take a long
+	time, so disabling this feature may speed up the cloning
+	process. This feature is enabled by default, use
 	--no-follow-parent to disable it.
 +
 [verse]
-- 
1.7.10.4

Re: [PATCH v2 3/4] git-svn: Expand documentation for --follow-parent

[Junio C Hamano]

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

> Describe what the option --follow-parent does, and what happens if it is
> set or unset.
>
> Signed-off-by: Sebastian Leske <sebastian.leske@sleske.name>
> ---
>  Documentation/git-svn.txt |   15 ++++++++++++---
>  1 file changed, 12 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
> index bfa8788..6bda014 100644
> --- a/Documentation/git-svn.txt
> +++ b/Documentation/git-svn.txt
> @@ -628,10 +628,19 @@ ADVANCED OPTIONS
>  	Default: "svn"
>  
>  --follow-parent::
> +	This option is only relevant if we are tracking branches (using
> +	one of the repository layout options --trunk, --tags,
> +	--branches, --stdlayout). For each tracked branch, try to find
> +	out where its revision was copied (i.e. branched) from, and set
> +	a suitable parent in the first git commit for the branch.

I also commit this sin myself often, but it is a good habit to get
into to re-read the sentence after writing "... X (i.e. Y)", "... V
(meaning W)", "... A (in other words B)".  We often write these
after realizing that "... X", "... V" or "... A" is hard to
understand and attempt to paraphrase to make it easier, but while
doing so we unconsciously hesitate to remove what we originally
wrote.  The results sometimes (but not always) reads better if you
do not say X, V or A and only used the rephrased version that is
meant to be easier-to-read.

In this case, I think "was copied" and "was branched" alone are
equally good but adding "(i.e. branched)" sounds redundant.

>  	This is especially helpful when we're tracking a directory
> -	that has been moved around within the repository, or if we
> -	started tracking a branch and never tracked the trunk it was
> -	descended from. This feature is enabled by default, use
> +	that has been moved around within the repository.  If this
> +	feature is disabled, the branches created by 'git svn' will all
> +	be linear and not share any history, meaning that there will be
> +	no information on where branches where branched off or merged.

I think the second "where" is a typo for "were" here.

> +	However, following long/convoluted histories can take a long
> +	time, so disabling this feature may speed up the cloning
> +	process. This feature is enabled by default, use
>  	--no-follow-parent to disable it.
>  +
>  [verse]

[PATCH v2 4/4] git-svn: Note about tags.

[Sebastian Leske]

Document that 'git svn' will import SVN tags as branches.

Signed-off-by: Sebastian Leske <sebastian.leske@sleske.name>
---
 Documentation/git-svn.txt |    7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 6bda014..18d5e45 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -959,6 +959,13 @@ the possible corner cases (git doesn't do it, either).  Committing
 renamed and copied files is fully supported if they're similar enough
 for git to detect them.
 
+SVN tags (if tracked using options '--tags' or '--stdlayout') are
+imported as git branches, prefixing the tag name with 'tags/'.
+This is because tags in SVN behave more like git branches: The contents
+of a tag need not be identical to the tagged commit, and it is possible
+(though discouraged) to commit changes to a tag (because a tag is just a
+directory copy, thus technically the same as a branch).
+
 CONFIGURATION
 -------------
 
-- 
1.7.10.4

Re: [PATCH v2 0/4] git-svn: More docs for branch handling in

[Junio C Hamano]

I've sent comments on small nits I found but overall they looked
quite well researched.  Will tentatively queue on the 'pu' branch,
expecting further updates and Acks from people involved polishing
these patches.

Thanks for writing it up.

Re: [PATCH v2 0/4] git-svn: More docs for branch handling in

[Eric Wong]

Junio C Hamano <gitster@pobox.com> wrote:
> I've sent comments on small nits I found but overall they looked
> quite well researched.  Will tentatively queue on the 'pu' branch,
> expecting further updates and Acks from people involved polishing
> these patches.
> 
> Thanks for writing it up.

Thanks all.  I think the patches are good, but also look forward
to improvements following Junio's comments.