{"thread":{"id":"32191","subject":"[PATCH 3/4] git-svn: Expand documentation for --follow-parent","startedAt":"2012-11-18T17:08:27Z","lastAt":"2012-11-28T14:58:02Z","messageCount":8,"participants":["Sebastian Leske","Michael J Gruber"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"203792","messageId":"b115a546fa783b4121d118bb8fdb9270443f90fa.1353691892.git.Sebastian.Leske@sleske.name","threadId":"32191","inReplyTo":null,"subject":"[PATCH 1/4] git-svn: Document branches with at-sign(@).","fromName":"Sebastian Leske","fromEmail":"sebastian.leske@sleske.name","sentAt":"2012-11-18T17:08:27Z","receivedAt":"2012-11-18T17:08:27Z","isPatch":true,"sender":{"key":"sebastian.leske@sleske.name","avatar":"https://avatars.githubusercontent.com/u/1101993?v=4"},"body":"git svn will sometimes create branches with an at-sign in the name\n(branchname@revision). These branches confuse many users and it is a FAQ\nwhy they are created. Document when git svn will create them.\n\nSigned-off-by: Sebastian Leske \n---\n\nI found various important features of git-svn that are not documented.\nThus I created a series of patches to add and update documentation for\ngit-svn. I am sending this as four patches (of which this mail is the\nfirst). I have tried my best to make the patches ready for inclusion\ninto git, but if there's any feedback, I'll gladly incorporate it.\n\n\n Documentation/git-svn.txt | 26 ++++++++++++++++++++++++++\n 1 file changed, 26 insertions(+)\n\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex 8b0d3ad..482d60d 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -881,6 +881,32 @@ different name spaces. For example:\n \tbranches = stable/*:refs/remotes/svn/stable/*\n \tbranches = debug/*:refs/remotes/svn/debug/*\n \n+If 'git svn' is configured to fetch branches (and --follow-branches\n+is in effect), it will sometimes create multiple branches for one SVN\n+branch, where the addtional branches have names of the form\n+'branchname@nnn' (with nnn an SVN revision number). These additional\n+branches are created if 'git svn' cannot find a parent commit for the\n+first commit in the branch, to connect the branch to the history of the\n+other branches. Normally, 'git svn' will find the git commit that\n+corresponds to the SVN revision a branch was created (copied) from and\n+use that as the parent. However, it is possible that there is no\n+suitable git commit to serve as parent. This will happen, among other\n+reasons, if the SVN branch is a copy of a revision that was not fetched\n+by 'git svn' (e.g. because it is an old revision that was skipped with\n+'--revision'), or if in SVN a directory was copied that is not tracked\n+by 'git svn' (a branch that is not tracked at all, or a subdirectory of\n+a tracked branch). In these cases, 'git svn' will still create a git\n+branch, but the branch will not be connected to the history of the other\n+branches. 'git svn' will also create a commit from the SVN revision the\n+branch was copied from, and use that as the parent commit of the branch\n+(this is indicated by the message \"Initializing parent: \").\n+Additionally, it will create a special branch named\n+'@', where is the SVN revision\n+number the branch was copied from. This branch will point to the\n+specially created parent commit.\n+If in SVN the branch was deleted and later recreated from a different\n+version, there will be multiple such branches with an '@'.\n+\n BUGS\n ----\n \n-- \n1.7.10.4\n"},{"id":"203794","messageId":"a4de87e8d09c26221eff116c3209b0a3606dfc21.1353691892.git.Sebastian.Leske@sleske.name","threadId":"32191","inReplyTo":"b115a546fa783b4121d118bb8fdb9270443f90fa.1353691892.git.Sebastian.Leske@sleske.name","subject":"[PATCH 2/4] Recommend use of structure options for git svn.","fromName":"Sebastian Leske","fromEmail":"sebastian.leske@sleske.name","sentAt":"2012-11-21T07:13:51Z","receivedAt":"2012-11-21T07:13:51Z","isPatch":true,"sender":{"key":"sebastian.leske@sleske.name","avatar":"https://avatars.githubusercontent.com/u/1101993?v=4"},"body":"Document that when using git svn, one should usually either use the\ndirectory structure options to import branches as branches, or only\nimport one subdirectory. The default behaviour of cloning all branches\nand tags as subdirectories in the working copy is usually not what the\nuser wants.\n\nSigned-off-by: Sebastian Leske \n---\n Documentation/git-svn.txt | 10 ++++++++++\n 1 file changed, 10 insertions(+)\n\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex 482d60d..928a961 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -871,6 +871,16 @@ already dcommitted. It is considered bad practice to --amend commits\n you've already pushed to a remote repository for other users, and\n dcommit with SVN is analogous to that.\n \n+When cloning an SVN repository, if none of the options for describing\n+the repository layout is used (--trunk, --tags, --branches,\n+--stdlayout), 'git svn clone' will create a git repository with\n+completely linear history, where branches and tags appear as separate\n+folders in the working copy. For projects with many branches this will\n+lead to a working copy many times larger than just the trunk. It is\n+recommended to either use the the options for trunk / tag / branch\n+directory, or to only clone the trunk (or a subdirectory of the\n+trunk).\n+\n When using multiple --branches or --tags, 'git svn' does not automatically\n handle name collisions (for example, if two branches from different paths have\n the same name, or if a branch and a tag have the same name). In these cases,\n-- \n1.7.10.4\n"},{"id":"203791","messageId":"a9748faec2a18231ad588c1a2dedb82e74685d74.1353691892.git.Sebastian.Leske@sleske.name","threadId":"32191","inReplyTo":"b115a546fa783b4121d118bb8fdb9270443f90fa.1353691892.git.Sebastian.Leske@sleske.name","subject":"[PATCH 3/4] git-svn: Expand documentation for --follow-parent","fromName":"Sebastian Leske","fromEmail":"sebastian.leske@sleske.name","sentAt":"2012-11-23T07:13:16Z","receivedAt":"2012-11-23T07:13:16Z","isPatch":true,"sender":{"key":"sebastian.leske@sleske.name","avatar":"https://avatars.githubusercontent.com/u/1101993?v=4"},"body":"Describe what the option --follow-parent does, and what happens if it is\nset or unset.\n\nSigned-off-by: Sebastian Leske \n---\n Documentation/git-svn.txt | 16 ++++++++++++----\n 1 file changed, 12 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex 928a961..92780ef 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -628,11 +628,19 @@ ADVANCED OPTIONS\n \tDefault: \"svn\"\n \n --follow-parent::\n+\tThis option is only relevant if we are tracking branches (using\n+\tone of the repository layout options --trunk, --tags,\n+\t--branches, --stdlayout). For each tracked branch, try to find\n+\tout where its revision was copied (i.e. branched) from, and set\n+\ta suitable parent in the first git commit for the branch.\n \tThis is especially helpful when we're tracking a directory\n-\tthat has been moved around within the repository, or if we\n-\tstarted tracking a branch and never tracked the trunk it was\n-\tdescended from. This feature is enabled by default, use\n-\t--no-follow-parent to disable it.\n+\tthat has been moved around within the repository (note that you\n+\tmust track both the old and the new name for the whole history\n+\tto be imported). If this feature is disabled, the branches\n+\tcreated by 'git svn' will all be linaear and not share any\n+\thistory, meaning that there will be no information on where\n+\tbranches where branched off or merged. This feature is enabled\n+\tby default, use --no-follow-parent to disable it.\n +\n [verse]\n config key: svn.followparent\n-- \n1.7.10.4\n"},{"id":"203793","messageId":"c72bc0d2a4f2681d27247c6f7510c4ada8e83aec.1353691892.git.Sebastian.Leske@sleske.name","threadId":"32191","inReplyTo":"b115a546fa783b4121d118bb8fdb9270443f90fa.1353691892.git.Sebastian.Leske@sleske.name","subject":"[PATCH 4/4] git-svn: Note about tags.","fromName":"Sebastian Leske","fromEmail":"sebastian.leske@sleske.name","sentAt":"2012-11-23T07:29:38Z","receivedAt":"2012-11-23T07:29:38Z","isPatch":true,"sender":{"key":"sebastian.leske@sleske.name","avatar":"https://avatars.githubusercontent.com/u/1101993?v=4"},"body":"Document that 'git svn' will import SVN tags as branches.\n\nSigned-off-by: Sebastian Leske \n---\n Documentation/git-svn.txt | 6 ++++++\n 1 file changed, 6 insertions(+)\n\ndiff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\nindex 92780ef..6212b24 100644\n--- a/Documentation/git-svn.txt\n+++ b/Documentation/git-svn.txt\n@@ -938,6 +938,12 @@ the possible corner cases (git doesn't do it, either). Committing\n renamed and copied files is fully supported if they're similar enough\n for git to detect them.\n \n+In SVN, it is possible (though discouraged) to commit changes to a tag\n+(because a tag is just a directory copy, thus technically the same as a\n+branch). When cloning an SVN repository, 'git svn' cannot know if such a\n+commit to a tag will happen in the future. Thus it acts conservatively\n+and imports all SVN tags as branches, prefixing the tag name with 'tags/'.\n+\n CONFIGURATION\n -------------\n \n-- \n1.7.10.4\n"},{"id":"204159","messageId":"50B6230A.2040503@drmicha.warpmail.net","threadId":"32191","inReplyTo":"b115a546fa783b4121d118bb8fdb9270443f90fa.1353691892.git.Sebastian.Leske@sleske.name","subject":"Re: [PATCH 1/4] git-svn: Document branches with at-sign(@).","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2012-11-28T14:43:22Z","receivedAt":"2012-11-28T14:43:22Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Sebastian Leske venit, vidit, dixit 18.11.2012 18:08:\n> git svn will sometimes create branches with an at-sign in the name\n> (branchname@revision). These branches confuse many users and it is a FAQ\n> why they are created. Document when git svn will create them.\n> \n> Signed-off-by: Sebastian Leske \n> ---\n> \n> I found various important features of git-svn that are not documented.\n> Thus I created a series of patches to add and update documentation for\n> git-svn. I am sending this as four patches (of which this mail is the\n> first). I have tried my best to make the patches ready for inclusion\n> into git, but if there's any feedback, I'll gladly incorporate it.\n> \n> \n> Documentation/git-svn.txt | 26 ++++++++++++++++++++++++++\n> 1 file changed, 26 insertions(+)\n> \n> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\n> index 8b0d3ad..482d60d 100644\n> --- a/Documentation/git-svn.txt\n> +++ b/Documentation/git-svn.txt\n> @@ -881,6 +881,32 @@ different name spaces. For example:\n> \tbranches = stable/*:refs/remotes/svn/stable/*\n> \tbranches = debug/*:refs/remotes/svn/debug/*\n> \n> +If 'git svn' is configured to fetch branches (and --follow-branches\n> +is in effect), it will sometimes create multiple branches for one SVN\n> +branch, where the addtional branches have names of the form\n> +'branchname@nnn' (with nnn an SVN revision number). These additional\n> +branches are created if 'git svn' cannot find a parent commit for the\n> +first commit in the branch, to connect the branch to the history of the\n> +other branches. Normally, 'git svn' will find the git commit that\n> +corresponds to the SVN revision a branch was created (copied) from and\n> +use that as the parent. However, it is possible that there is no\n> +suitable git commit to serve as parent. This will happen, among other\n> +reasons, if the SVN branch is a copy of a revision that was not fetched\n> +by 'git svn' (e.g. because it is an old revision that was skipped with\n> +'--revision'), or if in SVN a directory was copied that is not tracked\n> +by 'git svn' (a branch that is not tracked at all, or a subdirectory of\n> +a tracked branch). In these cases, 'git svn' will still create a git\n> +branch, but the branch will not be connected to the history of the other\n> +branches. 'git svn' will also create a commit from the SVN revision the\n> +branch was copied from, and use that as the parent commit of the branch\n> +(this is indicated by the message \"Initializing parent: \").\n> +Additionally, it will create a special branch named\n> +'@', where is the SVN revision\n> +number the branch was copied from. This branch will point to the\n> +specially created parent commit.\n> +If in SVN the branch was deleted and later recreated from a different\n> +version, there will be multiple such branches with an '@'.\n> +\n> BUGS\n> ----\n> \n> \n\nIn fact, the most typical reason for at-branches is a botched branching\nor tagging operation on the svn side: since they are simply \"copy\"\noperations it's too easy to copy a tree into the wrong directory.\n\nMichael\n"},{"id":"204160","messageId":"50B623D5.9090606@drmicha.warpmail.net","threadId":"32191","inReplyTo":"a4de87e8d09c26221eff116c3209b0a3606dfc21.1353691892.git.Sebastian.Leske@sleske.name","subject":"Re: [PATCH 2/4] Recommend use of structure options for git svn.","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2012-11-28T14:46:45Z","receivedAt":"2012-11-28T14:46:45Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Sebastian Leske venit, vidit, dixit 21.11.2012 08:13:\n> Document that when using git svn, one should usually either use the\n> directory structure options to import branches as branches, or only\n> import one subdirectory. The default behaviour of cloning all branches\n> and tags as subdirectories in the working copy is usually not what the\n> user wants.\n\n\"Usually\" assumes that usually svn repos follow a branch/tag structure.\nThat may be quite true nowadays (but wasn't in the beginning).\n\nIn fact I would suggest to emphasize \"--stdlayout\" as the most standard\nchoice nowadays, followed by specifying a specific branch (usually\ntrunk) as the repo uri.\n\n> Signed-off-by: Sebastian Leske \n> ---\n> Documentation/git-svn.txt | 10 ++++++++++\n> 1 file changed, 10 insertions(+)\n> \n> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\n> index 482d60d..928a961 100644\n> --- a/Documentation/git-svn.txt\n> +++ b/Documentation/git-svn.txt\n> @@ -871,6 +871,16 @@ already dcommitted. It is considered bad practice to --amend commits\n> you've already pushed to a remote repository for other users, and\n> dcommit with SVN is analogous to that.\n> \n> +When cloning an SVN repository, if none of the options for describing\n> +the repository layout is used (--trunk, --tags, --branches,\n> +--stdlayout), 'git svn clone' will create a git repository with\n> +completely linear history, where branches and tags appear as separate\n> +folders in the working copy. For projects with many branches this will\n> +lead to a working copy many times larger than just the trunk. It is\n> +recommended to either use the the options for trunk / tag / branch\n> +directory, or to only clone the trunk (or a subdirectory of the\n> +trunk).\n> +\n> When using multiple --branches or --tags, 'git svn' does not automatically\n> handle name collisions (for example, if two branches from different paths have\n> the same name, or if a branch and a tag have the same name). In these cases,\n> \n"},{"id":"204161","messageId":"50B62453.7080203@drmicha.warpmail.net","threadId":"32191","inReplyTo":"a9748faec2a18231ad588c1a2dedb82e74685d74.1353691892.git.Sebastian.Leske@sleske.name","subject":"Re: [PATCH 3/4] git-svn: Expand documentation for --follow-parent","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2012-11-28T14:48:51Z","receivedAt":"2012-11-28T14:48:51Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Sebastian Leske venit, vidit, dixit 23.11.2012 08:13:\n> Describe what the option --follow-parent does, and what happens if it is\n> set or unset.\n> \n> Signed-off-by: Sebastian Leske \n> ---\n> Documentation/git-svn.txt | 16 ++++++++++++----\n> 1 file changed, 12 insertions(+), 4 deletions(-)\n> \n> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\n> index 928a961..92780ef 100644\n> --- a/Documentation/git-svn.txt\n> +++ b/Documentation/git-svn.txt\n> @@ -628,11 +628,19 @@ ADVANCED OPTIONS\n> \tDefault: \"svn\"\n> \n> --follow-parent::\n> +\tThis option is only relevant if we are tracking branches (using\n> +\tone of the repository layout options --trunk, --tags,\n> +\t--branches, --stdlayout). For each tracked branch, try to find\n> +\tout where its revision was copied (i.e. branched) from, and set\n> +\ta suitable parent in the first git commit for the branch.\n> \tThis is especially helpful when we're tracking a directory\n> -\tthat has been moved around within the repository, or if we\n> -\tstarted tracking a branch and never tracked the trunk it was\n> -\tdescended from. This feature is enabled by default, use\n> -\t--no-follow-parent to disable it.\n> +\tthat has been moved around within the repository (note that you\n> +\tmust track both the old and the new name for the whole history\n> +\tto be imported). If this feature is disabled, the branches\n> +\tcreated by 'git svn' will all be linaear and not share any\n\nlinear\n\n> +\thistory, meaning that there will be no information on where\n> +\tbranches where branched off or merged. This feature is enabled\n> +\tby default, use --no-follow-parent to disable it.\n> +\n> [verse]\n> config key: svn.followparent\n> \n"},{"id":"204162","messageId":"50B6267A.204@drmicha.warpmail.net","threadId":"32191","inReplyTo":"c72bc0d2a4f2681d27247c6f7510c4ada8e83aec.1353691892.git.Sebastian.Leske@sleske.name","subject":"Re: [PATCH 4/4] git-svn: Note about tags.","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2012-11-28T14:58:02Z","receivedAt":"2012-11-28T14:58:02Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Sebastian Leske venit, vidit, dixit 23.11.2012 08:29:\n> Document that 'git svn' will import SVN tags as branches.\n> \n> Signed-off-by: Sebastian Leske \n> ---\n> Documentation/git-svn.txt | 6 ++++++\n> 1 file changed, 6 insertions(+)\n> \n> diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt\n> index 92780ef..6212b24 100644\n> --- a/Documentation/git-svn.txt\n> +++ b/Documentation/git-svn.txt\n> @@ -938,6 +938,12 @@ the possible corner cases (git doesn't do it, either). Committing\n> renamed and copied files is fully supported if they're similar enough\n> for git to detect them.\n> \n> +In SVN, it is possible (though discouraged) to commit changes to a tag\n> +(because a tag is just a directory copy, thus technically the same as a\n> +branch). When cloning an SVN repository, 'git svn' cannot know if such a\n> +commit to a tag will happen in the future. Thus it acts conservatively\n> +and imports all SVN tags as branches, prefixing the tag name with 'tags/'.\n> +\n\nIf git-svn turned SVN tags in git lightweight tags it would be just as\nconservative, because they can be rewritten also... It's just a ref.\nNote that the above assumes standard refspecs.\n\nBut, importing SVN tags as branches conveys their character much more\nprecisely. If r8 is being tagged then svn creates r9, which may or may\nnot be treesame to r8; different projects do different things in this step.\n\nEven if they are treesame, r9 still carries a separate commit message.\nThis is probably the most typical case, and converting the r9 commit\ninto a git tag object would be appropriate (but is left to the user of\ngit-svn).\n\nA lightweight tag pointing to an \"off-branch\" commit (r9) would be a\nstrange thing, so git-svn creates a new branch instead, pointing at r9,\nbranching off r8.\n\n> CONFIGURATION\n> -------------\n> \n> \n"}]}