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 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/).
CAVEATS
-------
For the sake of simplicity and interoperating with Subversion,
it is recommended that all 'git svn' users clone, fetch and dcommit
directly from the SVN server, and avoid all 'git clone'/'pull'/'merge'/'push'
operations between Git repositories and branches. The recommended
method of exchanging code between Git branches and users is
'git format-patch' and 'git am', or just 'dcommit'ing to the SVN repository.
Running 'git merge' or 'git pull' is NOT recommended on a branch you
plan to 'dcommit' from because Subversion users cannot see any
merges you've made. Furthermore, if you merge or pull from a Git branch
that is a mirror of an SVN branch, 'dcommit' may commit to the wrong
branch.
If you do merge, note the following rule: 'git svn dcommit' will
attempt to commit on top of the SVN commit named in
------------------------------------------------------------------------
git log --grep=^git-svn-id: --first-parent -1
------------------------------------------------------------------------
You 'must' therefore ensure that the most recent commit of the branch
you want to dcommit to is the 'first' parent of the merge. Chaos will
ensue otherwise, especially if the first parent is an older commit on
the same SVN branch.
'git clone' does not clone branches under the refs/remotes/ hierarchy or
any 'git svn' metadata, or config. So repositories created and managed with
using 'git svn' should use 'rsync' for cloning, if cloning is to be done
at all.
Since 'dcommit' uses rebase internally, any Git branches you 'git push' to
before 'dcommit' on will require forcing an overwrite of the existing ref
on the remote repository. This is generally considered bad practice,
see the linkgit:git-push[1]