Autogenerated HTML docs for v1.8.1-rc2-38-gb10c4

1 files changed, 82 insertions, 7 deletions

diff --git a/git-svn.html b/git-svn.html
index 216052114..235e84175 100644
--- a/git-svn.html
+++ b/git-svn.html
@@ -1845,10 +1845,19 @@ creating the branch or tag.</p></div>
 </dt>

 <dd>

 <p>

+        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 from, and set

+        a suitable parent in the first git commit for the branch.

         This is especially helpful when we&#8217;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 <em>git svn</em> will all

+        be linear and not share any history, meaning that there will be

+        no information on where branches were 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.

 </p>

 <div class="verseblock">

@@ -2008,7 +2017,8 @@ for rewriteRoot and rewriteUUID which can be used together.</p></div>
 <div class="sect1">

 <h2 id="_basic_examples">BASIC EXAMPLES</h2>

 <div class="sectionbody">

-<div class="paragraph"><p>Tracking and contributing to the trunk of a Subversion-managed project:</p></div>

+<div class="paragraph"><p>Tracking and contributing to the trunk of a Subversion-managed project

+(ignoring tags and branches):</p></div>

 <div class="listingblock">

 <div class="content">

 <pre><code># Clone a repo (like git clone):

@@ -2032,8 +2042,10 @@ for rewriteRoot and rewriteUUID which can be used together.</p></div>
 (complete with a trunk, tags and branches):</p></div>

 <div class="listingblock">

 <div class="content">

-<pre><code># Clone a repo (like git clone):

-        git svn clone http://svn.example.com/project -T trunk -b branches -t tags

+<pre><code># 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

@@ -2102,6 +2114,50 @@ compatibility with SVN (see the CAVEATS section below).</p></div>
 </div>

 </div>

 <div class="sect1">

+<h2 id="_handling_of_svn_branches">HANDLING OF SVN BRANCHES</h2>

+<div class="sectionbody">

+<div class="paragraph"><p>If <em>git svn</em> is configured to fetch branches (and --follow-branches

+is in effect), it sometimes creates multiple git branches for one

+SVN branch, where the addtional branches have names of the form

+<em>branchname@nnn</em> (with nnn an SVN revision number).  These additional

+branches are created if <em>git svn</em> cannot find a parent commit for the

+first commit in an SVN branch, to connect the branch to the history of

+the other branches.</p></div>

+<div class="paragraph"><p>Normally, the first commit in an SVN branch consists

+of a copy operation. <em>git svn</em> 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 <em>git

+svn</em> (e.g. because it is an old revision that was skipped with

+<em>--revision</em>), or if in SVN a directory was copied that is not tracked

+by <em>git svn</em> (such as a branch that is not tracked at all, or a

+subdirectory of a tracked branch). In these cases, <em>git svn</em> 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: &lt;branchname&gt;".</p></div>

+<div class="paragraph"><p>Additionally, it will create a special branch named

+<em>&lt;branchname&gt;@&lt;SVN-Revision&gt;</em>, where &lt;SVN-Revision&gt; 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 <em>@</em>.</p></div>

+<div class="paragraph"><p>Note that this may mean that multiple git commits are created for a

+single SVN revision.</p></div>

+<div class="paragraph"><p>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/. <em>git svn

+clone -s</em> will then create a branch <em>sub</em>. It will also create new git

+commits for r.100 through r.199 and use these as the history of branch

+<em>sub</em>. 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 <em>sub@200</em> pointing to the new parent commit of

+branch <em>sub</em> (i.e. the commit for r.200 and trunk/sub/).</p></div>

+</div>

+</div>

+<div class="sect1">

 <h2 id="_caveats">CAVEATS</h2>

 <div class="sectionbody">

 <div class="paragraph"><p>For the sake of simplicity and interoperating with Subversion,

@@ -2137,6 +2193,20 @@ see the <a href="git-push.html">git-push(1)</a> documentation for details.</p></
 already dcommitted.  It is considered bad practice to --amend commits

 you&#8217;ve already pushed to a remote repository for other users, and

 dcommit with SVN is analogous to that.</p></div>

+<div class="paragraph"><p>When cloning an SVN repository, if none of the options for describing

+the repository layout is used (--trunk, --tags, --branches,

+--stdlayout), <em>git svn clone</em> will create a git repository with

+completely linear history, where branches and tags appear as separate

+directories 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 <em>--stdlayout</em>. 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 <em>--trunk</em> / <em>--branches</em> /

+<em>--tags</em> must be used.</p></div>

 <div class="paragraph"><p>When using multiple --branches or --tags, <em>git svn</em> 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,

@@ -2161,6 +2231,11 @@ this as it&#8217;s quite difficult and time-consuming to get working for all
 the possible corner cases (git doesn&#8217;t do it, either).  Committing

 renamed and copied files is fully supported if they&#8217;re similar enough

 for git to detect them.</p></div>

+<div class="paragraph"><p>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, <em>git svn</em> 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 <em>tags/</em>.</p></div>

 </div>

 </div>

 <div class="sect1">

@@ -2219,7 +2294,7 @@ reset) branches-maxRev and/or tags-maxRev as appropriate.</p></div>
 <div id="footnotes"><hr /></div>

 <div id="footer">

 <div id="footer-text">

-Last updated 2012-11-13 14:31:09 PST

+Last updated 2012-12-21 15:43:34 PST

 </div>

 </div>

 </body>