Sebastian Leske <sebastian.le...@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.le...@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:" -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
