From: Junio C Hamano Date: Thu, 27 Dec 2012 23:38:34 +0000 (-0800) Subject: Merge branch 'sl/maint-git-svn-docs' into maint X-Git-Tag: v1.8.0.3~2 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/2b05d9f917488f27bbd5592f0927d3a754ad0eb5?ds=inline;hp=-c Merge branch 'sl/maint-git-svn-docs' into maint * sl/maint-git-svn-docs: git-svn: Note about tags. git-svn: Expand documentation for --follow-parent git-svn: Recommend use of structure options. git-svn: Document branches with at-sign(@). --- 2b05d9f917488f27bbd5592f0927d3a754ad0eb5 diff --combined Documentation/git-svn.txt index 8b0d3adfed,346f1b766f..69decb13b0 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@@ -146,13 -146,6 +146,13 @@@ Skip "branches" and "tags" of first lev ------------------------------------------------------------------------ -- +--log-window-size=;; + Fetch log entries per request when scanning Subversion history. + The default is 100. For very large Subversion repositories, larger + values may be needed for 'clone'/'fetch' to complete in reasonable + time. But overly large values may lead to higher memory usage and + request timeouts. + 'clone':: Runs 'init' and 'fetch'. It will automatically create a directory based on the basename of the URL passed to it; @@@ -628,10 -621,19 +628,19 @@@ ADVANCED OPTION 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 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 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. + [verse] @@@ -739,7 -741,8 +748,8 @@@ for rewriteRoot and rewriteUUID which c 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 -767,10 +774,10 @@@ Tracking and contributing to an entire (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 @@@ -830,6 -835,52 +842,52 @@@ inside git back upstream to SVN users users keep history as linear as possible inside git to ease compatibility with SVN (see the CAVEATS section below). + HANDLING OF SVN BRANCHES + ------------------------ + If 'git svn' 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 + '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 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: ". + + Additionally, it will create a special branch named + '@', where 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 ------- @@@ -871,6 -922,21 +929,21 @@@ already dcommitted. It is considered b 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 + 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 '--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, @@@ -894,6 -960,12 +967,12 @@@ the possible corner cases (git doesn't 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 -------------