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

[PATCH 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>
---

I found various important features of git-svn that are not documented.
Thus I created a series of patches to add and update documentation for
git-svn. I am sending this as four patches (of which this mail is the
first). I have tried my best to make the patches ready for inclusion
into git, but if there's any feedback, I'll gladly incorporate it.


 Documentation/git-svn.txt |   26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 8b0d3ad..482d60d 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -881,6 +881,32 @@ 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 the branch, to connect the branch to the history of the
+other branches. Normally, 'git svn' will find the git commit that
+corresponds to the SVN revision a branch was created (copied) from and
+use that as the parent. 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' (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 the branch will not be connected to the history of the other
+branches.  'git svn' will also create a commit from the SVN revision the
+branch was copied from, and use that as the parent commit of the branch
+(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
+specially created parent commit.
+If in SVN the branch was deleted and later recreated from a different
+version, there will be multiple such branches with an '@'.
+
 BUGS
 ----
 
-- 
1.7.10.4

[PATCH 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 |   10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 482d60d..928a961 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -871,6 +871,16 @@ 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.  For projects with many branches this will
+lead to a working copy many times larger than just the trunk.  It is
+recommended to either use the the options for trunk / tag / branch
+directory, or to only clone the trunk (or a subdirectory of the
+trunk).
+
 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

[PATCH 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 |   16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 928a961..92780ef 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -628,11 +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
-	--no-follow-parent to disable it.
+	that has been moved around within the repository (note that you
+	must track both the old and the new name for the whole history
+	to be imported).  If this feature is disabled, the branches
+	created by 'git svn' will all be linaear and not share any
+	history, meaning that there will be no information on where
+	branches where branched off or merged. This feature is enabled
+	by default, use --no-follow-parent to disable it.
 +
 [verse]
 config key: svn.followparent
-- 
1.7.10.4

[PATCH 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 |    6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
index 92780ef..6212b24 100644
--- a/Documentation/git-svn.txt
+++ b/Documentation/git-svn.txt
@@ -938,6 +938,12 @@ 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.
 
+In SVN, 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). When cloning an SVN repository, 'git svn' cannot know if such a
+commit to a tag will happen in the future. Thus it acts conservatively
+and imports all SVN tags as branches, prefixing the tag name with 'tags/'.
+
 CONFIGURATION
 -------------
 
-- 
1.7.10.4

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

[Michael J Gruber]

Sebastian Leske venit, vidit, dixit 18.11.2012 18:08:
> 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>
> ---
> 
> I found various important features of git-svn that are not documented.
> Thus I created a series of patches to add and update documentation for
> git-svn. I am sending this as four patches (of which this mail is the
> first). I have tried my best to make the patches ready for inclusion
> into git, but if there's any feedback, I'll gladly incorporate it.
> 
> 
>  Documentation/git-svn.txt |   26 ++++++++++++++++++++++++++
>  1 file changed, 26 insertions(+)
> 
> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
> index 8b0d3ad..482d60d 100644
> --- a/Documentation/git-svn.txt
> +++ b/Documentation/git-svn.txt
> @@ -881,6 +881,32 @@ 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 the branch, to connect the branch to the history of the
> +other branches. Normally, 'git svn' will find the git commit that
> +corresponds to the SVN revision a branch was created (copied) from and
> +use that as the parent. 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' (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 the branch will not be connected to the history of the other
> +branches.  'git svn' will also create a commit from the SVN revision the
> +branch was copied from, and use that as the parent commit of the branch
> +(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
> +specially created parent commit.
> +If in SVN the branch was deleted and later recreated from a different
> +version, there will be multiple such branches with an '@'.
> +
>  BUGS
>  ----
>  
> 

In fact, the most typical reason for at-branches is a botched branching
or tagging operation on the svn side: since they are simply "copy"
operations it's too easy to copy a tree into the wrong directory.

Michael

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

[Michael J Gruber]

Sebastian Leske venit, vidit, dixit 21.11.2012 08:13:
> 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.

"Usually" assumes that usually svn repos follow a branch/tag structure.
That may be quite true nowadays (but wasn't in the beginning).

In fact I would suggest to emphasize "--stdlayout" as the most standard
choice nowadays, followed by specifying a specific branch (usually
trunk) as the repo uri.

> Signed-off-by: Sebastian Leske <sebastian.leske@sleske.name>
> ---
>  Documentation/git-svn.txt |   10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
> index 482d60d..928a961 100644
> --- a/Documentation/git-svn.txt
> +++ b/Documentation/git-svn.txt
> @@ -871,6 +871,16 @@ 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.  For projects with many branches this will
> +lead to a working copy many times larger than just the trunk.  It is
> +recommended to either use the the options for trunk / tag / branch
> +directory, or to only clone the trunk (or a subdirectory of the
> +trunk).
> +
>  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,
> 

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

[Michael J Gruber]

Sebastian Leske venit, vidit, dixit 23.11.2012 08:13:
> 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 |   16 ++++++++++++----
>  1 file changed, 12 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
> index 928a961..92780ef 100644
> --- a/Documentation/git-svn.txt
> +++ b/Documentation/git-svn.txt
> @@ -628,11 +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
> -	--no-follow-parent to disable it.
> +	that has been moved around within the repository (note that you
> +	must track both the old and the new name for the whole history
> +	to be imported).  If this feature is disabled, the branches
> +	created by 'git svn' will all be linaear and not share any

linear

> +	history, meaning that there will be no information on where
> +	branches where branched off or merged. This feature is enabled
> +	by default, use --no-follow-parent to disable it.
>  +
>  [verse]
>  config key: svn.followparent
> 

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

[Michael J Gruber]

Sebastian Leske venit, vidit, dixit 23.11.2012 08:29:
> Document that 'git svn' will import SVN tags as branches.
> 
> Signed-off-by: Sebastian Leske <sebastian.leske@sleske.name>
> ---
>  Documentation/git-svn.txt |    6 ++++++
>  1 file changed, 6 insertions(+)
> 
> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt
> index 92780ef..6212b24 100644
> --- a/Documentation/git-svn.txt
> +++ b/Documentation/git-svn.txt
> @@ -938,6 +938,12 @@ 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.
>  
> +In SVN, 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). When cloning an SVN repository, 'git svn' cannot know if such a
> +commit to a tag will happen in the future. Thus it acts conservatively
> +and imports all SVN tags as branches, prefixing the tag name with 'tags/'.
> +

If git-svn turned SVN tags in git lightweight tags it would be just as
conservative, because they can be rewritten also... It's just a ref.
Note that the above assumes standard refspecs.

But, importing SVN tags as branches conveys their character much more
precisely. If r8 is being tagged then svn creates r9, which may or may
not be treesame to r8; different projects do different things in this step.

Even if they are treesame, r9 still carries a separate commit message.
This is probably the most typical case, and converting the r9 commit
into a git tag object would be appropriate (but is left to the user of
git-svn).

A lightweight tag pointing to an "off-branch" commit (r9) would be a
strange thing, so git-svn creates a new branch instead, pointing at r9,
branching off r8.

>  CONFIGURATION
>  -------------
>  
>