You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@subversion.apache.org by ne...@apache.org on 2011/12/02 19:39:47 UTC
svn commit: r1209631 - /subversion/trunk/subversion/svn/main.c
Author: neels
Date: Fri Dec 2 18:39:47 2011
New Revision: 1209631
URL: http://svn.apache.org/viewvc?rev=1209631&view=rev
Log:
* subversion/svn/main.c:
Fully review and semi-automatically re-line-break the 'svn help merge'
text. Fix another typo. Revamp the 2-URL merge example into an example of
combining two feature branches (inspired by an actual question on
FreeNode's #svn IRC channel by 'Xinil' on Nov. 30th). Rephrase a lot to be
(hopefully) more clear. Tweak some ascii art. There should be no change in
the actual information though. Unindent to fit in 80 chars width and
comment on that.
Modified:
subversion/trunk/subversion/svn/main.c
Modified: subversion/trunk/subversion/svn/main.c
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/svn/main.c?rev=1209631&r1=1209630&r2=1209631&view=diff
==============================================================================
--- subversion/trunk/subversion/svn/main.c (original)
+++ subversion/trunk/subversion/svn/main.c Fri Dec 2 18:39:47 2011
@@ -674,294 +674,326 @@ const svn_opt_subcommand_desc2_t svn_cl_
{'c', N_("the change made in revision ARG")}} },
{ "merge", svn_cl__merge, {0}, N_
- ("Merge changes into a working copy.\n"
- "usage: 0. merge SOURCE[@REV] [TARGET_WCPATH]\n"
- " (the 'sync' merge)\n"
- " 1. merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]\n"
- " (the 'cherry-pick' merge)\n"
- " 2. merge --reintegrate SOURCE[@REV] [TARGET_WCPATH]\n"
- " (the 'reintegrate' merge)\n"
- " 3. merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]\n"
- " (the '2-URL' merge)\n"
- "\n"
- " 0. This form is called a 'sync' (aka 'catch-up') merge:\n"
- "\n"
- " svn merge SOURCE[@REV] [TARGET_WCPATH]\n"
- "\n"
- " A sync merge is used to merge into a branch any unmerged changes\n"
- " made on its immediate ancestor branch. This uses merge tracking\n"
- " to find which changes need to be merged.\n"
- "\n"
- " SOURCE specifies the branch from where the changes will be pulled,\n"
- " and TARGET_WCPATH specifies the working copy of the target branch,\n"
- " into which the changes will be applied. Normally SOURCE and\n"
- " TARGET_WCPATH should each point to the root of a branch. If changes\n"
- " need to be merged from and to only a subtree of the branch, then\n"
- " the path to that subtree must be included in both SOURCE and\n"
- " TARGET_WCPATH.\n"
- "\n"
- " SOURCE is usually a URL. The optional '@REV' specifies both the peg\n"
- " revision of the URL and the latest revision that will be considered\n"
- " for merging; the default value is the HEAD revision. If SOURCE is a\n"
- " working copy path, the corresponding URL of the path is used, and\n"
- " the default value of 'REV' is the base revision.\n"
- "\n"
- " TARGET_WCPATH is a working copy path; the default is '.'.\n"
- "\n"
- " - Sync Merge Example -\n"
- "\n"
- " A feature is being developed on a branch called 'feature'. The\n"
- " feature branch is regularly synced with trunk to keep up with the\n"
- " changes made there. The previous sync merges are not shown on this\n"
- " diagram, and the last of them was done when HEAD was r100, and now\n"
- " HEAD is r200.\n"
- "\n"
- " feature +------------------------o-----\n"
- " / ^\n"
- " / /\n"
- " / ............../\n"
- " trunk ------+------------L--------------R------\n"
- " r100 r200\n"
- "\n"
- " Subversion will locate all the changes on 'trunk' that have not yet\n"
- " been merged into the target. In this case that is a single range,\n"
- " r100:200. In the diagram above, L marks the 'left' side of the\n"
- " range (trunk@100) and R marks the 'right' side of the range\n"
- " (trunk@200). The difference between L and R will be merged into\n"
- " the target.\n"
- "\n"
- " To perform this sync merge, check out a working copy of the feature\n"
- " branch and run the following command in the top-level directory\n"
- " of the working copy:\n"
- "\n"
- " svn merge ^/trunk\n"
- "\n"
- "\n"
- " 1. This form is called a 'cherry-pick' merge:\n"
- "\n"
- " svn merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]\n"
- "\n"
- " A cherry-pick merge is used to merge specific revisions (or\n"
- " revision ranges) from one branch to another. By default, this form\n"
- " of merge uses merge tracking to avoid re-merging any of the specified\n"
- " revisions that have already been merged. If the --ignore-ancestry\n"
- " option is given then that does not happen.\n"
- "\n"
- " The SOURCE and TARGET_WCPATH arguments are the same as for a 'sync'\n"
- " merge, except that REV acts only as a peg and does not specify the\n"
- " latest revision that will be considered for merging.\n"
- "\n"
- " The revision ranges to be merged are specified by the '-r' and/or\n"
- " '-c' options. '-r N:M' refers to the difference in the history of\n"
- " the source branch between revision N and revision M. '-c M' is\n"
- " equivalent to '-r <M-1>:M'. Each such difference is merged into\n"
- " TARGET_WCPATH.\n"
- "\n"
- " If mergeinfo within TARGET_WCPATH indicates that revisions within\n"
- " the range were already merged, changes made in those revisions\n"
- " are not merged again. If needed, the range is broken into multiple\n"
- " sub-ranges, and each sub-range is merged separately.\n"
- "\n"
- " If N is greater than M in '-r N:M', or with '-c -M' which is\n"
- " equivalent to '-r M:<M-1>', the range is a 'reverse range'.\n"
- " A reverse range can be used to undo changes made to SOURCE\n"
- " between revisions N and M.\n"
- "\n"
- " Multiple '-c' and/or '-r' options may be specified and mixing of\n"
- " forward and reverse ranges is allowed.\n"
- "\n"
- " - Cherry-pick Merge Example -\n"
- "\n"
- " A bug has been fixed on trunk on revision 50. This fix needs to\n"
- " be merged from the trunk into the release branch.\n"
- "\n"
- " 1.x-release +-----------------------o-----\n"
- " / ^\n"
- " / |\n"
- " / |\n"
- " trunk ------+--------------------------LR-----\n"
- " r50\n"
- "\n"
- " In the above diagram, L marks the left side of the merge (trunk@49)\n"
- " and R marks the right side of the merge (trunk@50). The difference\n"
- " between the left and right side is merged into the target.\n"
- "\n"
- " To perform the merge, check out a working copy of the release\n"
- " branch and run the following command in the top-level directory\n"
- " of the working copy:\n"
- "\n"
- " svn merge -c50 ^/trunk\n"
- "\n"
- " If several commits to trunk were related to the fix, multiple\n"
- " revisions can be merged:\n"
- "\n"
- " svn merge -c50,54,60 ^/trunk\n"
- "\n"
- "\n"
- " 2. This form is called a 'reintegrate merge':\n"
- "\n"
- " svn merge --reintegrate SOURCE[@REV] [TARGET_WCPATH]\n"
- "\n"
- " SOURCE is the URL of a branch to be merged back into (usually) its\n"
- " immediate ancestor branch. If REV is specified, it is used as\n"
- " the peg revision for SOURCE, i.e. SOURCE is looked up in the\n"
- " repository at revision REV. If REV is not specified, the HEAD\n"
- " revision is assumed.\n"
- "\n"
- " TARGET_WCPATH is a working copy of the branch the changes will\n"
- " be applied to.\n"
- "\n"
- " - Reintegrate Merge Example -\n"
- "\n"
- " A feature has been developed on a branch called 'feature'.\n"
- " The feature branch started as a copy of trunk@W. Work on the\n"
- " feature has completed and it should be merged back into the trunk.\n"
- "\n"
- " The feature branch was last synced with its immediate ancestor,\n"
- " the trunk, in revision X. So the difference between trunk@X and\n"
- " feature@HEAD contains the complete set of changes that implement\n"
- " the feature, and no other changes. These changes are applied to\n"
- " the trunk.\n"
- "\n"
- " feature +--------------------------------R\n"
- " / . \\\n"
- " / .............. \\\n"
- " / . v\n"
- " trunk ------+--------------------L------------------o\n"
- " rW rX\n"
- "\n"
- " In the diagram above, L marks the left side of the merge (trunk@X),\n"
- " and R marks the right side of the merge (feature@HEAD). The difference\n"
- " between the left and right side is merged into the target.\n"
- "\n"
- " To perform the merge, check out a working copy of the trunk, and run\n"
- " the following command in the top-level directory of the working copy:\n"
- "\n"
- " svn merge --reintegrate ^/feature\n"
- "\n"
- " To prevent unnecessary merge conflicts, reintegrate merges require\n"
- " that TARGET_WCPATH is not a mixed-revision working copy, has no\n"
- " local modifications, and has no switched subtrees.\n"
- "\n"
- " Reintegrate merges also require that the reintegrate source be fully\n"
- " synced with the target since their common branch point.\n"
- " In the above example this means that all of the changes made\n"
- " on trunk between revision W and revision X are fully merged to\n"
- " the feature branch before it can be reintegrated back to trunk.\n"
- "\n"
- " After the reintegrate merge, the feature branch cannot be synced\n"
- " to the trunk again without merge conflicts. If further work must\n"
- " be done on the feature branch, it should be deleted and then re-created.\n"
- "\n"
- "\n"
- " 3. This form is called a '2-URL merge':\n"
- "\n"
- " svn merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]\n"
- "\n"
- " Two source URLs are specified, together with two revisions N and M.\n"
- " The two sources to be compared at the specified revisions, and the\n"
- " difference is applied to TARGET_WCPATH, which is a path to a working\n"
- " copy of another branch.\n"
- "\n"
- " The revisions default to HEAD if omitted.\n"
- "\n"
- " If TARGET_WCPATH is omitted, a default value of '.' is assumed,\n"
- " unless the sources have identical basenames that match a file\n"
- " within '.', in which case the differences will be applied to\n"
- " that file.\n"
- "\n"
- " The sources can also be specified as working copy paths, in which\n"
- " case the URLs of the merge sources are derived from the working copies.\n"
- "\n"
- " This is the most flexible type of merge, but also the most difficult\n"
- " to use. It can be used to merge the differences between two (possibly\n"
- " ancestrally unrelated) branches into a working copy of another branch.\n"
- " This type of merge should be used very carefully because the probability\n"
- " of merge conflicts is quite high. In most use cases, a sync, cherry-pick,\n"
- " or reintegrate merge is sufficient and reduces the chances of mistakes.\n"
- "\n"
- " - 2-URL Merge Example -\n"
- "\n"
- " A feature has been developed on a branch called 'feature'.\n"
- " Development for the upcoming 3.0 release has happened in parallel on\n"
- " the '3.x-release' branch. The work on the feature branch must be\n"
- " merged to the 3.x-release branch. However, the feature branch and\n"
- " the 3.x-release branch are not directly related, so a 2-URL merge\n"
- " is needed.\n"
- " The feature branch was last synced with its immediate ancestor,\n"
- " the trunk, up to revision 500. So the difference between trunk@500\n"
- " and feature@HEAD contains the complete set of changes related to\n"
- " the feature, and no other changes. These changes are applied to\n"
- " the 3.x-release branch.\n"
- "\n"
- " 3.x-release +-----------------------------------o\n"
- " / ^\n"
- " / /\n"
- " / r500 /\n"
- " trunk ------+------+-----------------L---------> /\n"
- " \\ . /\n"
- " \\ ........... /\n"
- " \\ . /\n"
- " feature +-----------------------------------R\n"
- "\n"
- " In the diagram above, L marks the left side of the merge (trunk@500),\n"
- " and R marks the right side of the merge (feature@HEAD).\n"
- " The difference between the left and right side is merged into the target.\n"
- "\n"
- " To perform the merge, check out a working copy of the 3.x-release\n"
- " branch and run the following command in the top-level directory\n"
- " of the working copy:\n"
- "\n"
- " svn merge ^/trunk@500 ^/feature\n"
- "\n"
- " Before performing a 2-URL merge, it is a good idea to preview the\n"
- " changes which will be merged, because there is no guarantee that\n"
- " the merge will be free of conflicts. The preview can be done with\n"
- " the svn diff command:\n"
- "\n"
- " svn diff ^/trunk@500 ^/feature@HEAD\n"
- "\n"
- " Note that a 2-URL merge can also merge from foreign repositories.\n"
- " While SOURCE1 and SOURCE2 must both come from the same repository,\n"
- " TARGET_WCPATH may come from a different repository than the sources.\n"
- " However, there are some caveats. Most notably, copies made in the\n"
- " merge source will be transformed into plain additions in the merge\n"
- " target. Also, merge-tracking is not supported.\n"
- "\n"
- "\n"
- " The following applies to all types of merges:\n"
- "\n"
- " To prevent unnecessary merge conflicts, svn merge requires that\n"
- " TARGET_WCPATH is not a mixed-revision working copy.\n"
- " Running 'svn update' before starting a merge ensures that all\n"
- " items in the working copy are based on the same revision.\n"
- "\n"
- " For each merged item a line will be printed with characters reporting\n"
- " the action taken. These characters have the following meaning:\n"
- "\n"
- " A Added\n"
- " D Deleted\n"
- " U Updated\n"
- " C Conflict\n"
- " G Merged\n"
- " E Existed\n"
- " R Replaced\n"
- "\n"
- " Characters in the first column report about the item itself.\n"
- " Characters in the second column report about properties of the item.\n"
- " A 'C' in the third column indicates a tree conflict, while a 'C' in\n"
- " the first and second columns indicate textual conflicts in files\n"
- " and in property values, respectively.\n"
- "\n"
- " NOTE: Subversion uses the svn:mergeinfo property to track merge\n"
- " history. This property is considered at the start of a merge to\n"
- " determine what to merge and it is updated at the conclusion of the\n"
- " merge to describe the merge that took place. Mergeinfo is used only\n"
- " if the two sources are on the same line of history -- if the first\n"
- " source is an ancestor of the second, or vice-versa. This is guaranteed\n"
- " to be the case when using sync merges and reintegrate merges.\n"
- " The --ignore-ancestry option prevents merge tracking and thus\n"
- " ignores mergeinfo, neither considering it nor recording it.\n"),
+ ( /* For this large section, let's keep it unindented for easier
+ * viewing/editing. It has been vim-treated with a textwidth=75 and 'gw'
+ * (with quotes and newlines removed). */
+"Merge changes into a working copy.\n"
+"usage: 0. merge SOURCE[@REV] [TARGET_WCPATH]\n"
+" (the 'sync' merge)\n"
+" 1. merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]\n"
+" (the 'cherry-pick' merge)\n"
+" 2. merge --reintegrate SOURCE[@REV] [TARGET_WCPATH]\n"
+" (the 'reintegrate' merge)\n"
+" 3. merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]\n"
+" (the '2-URL' merge)\n"
+"\n"
+" 0. This form is called a 'sync' (or 'catch-up') merge:\n"
+"\n"
+" svn merge SOURCE[@REV] [TARGET_WCPATH]\n"
+"\n"
+" A sync merge is used to fetch all the latest changes made on a parent\n"
+" branch. In other words, the target branch has originally been created\n"
+" by copying the source branch, and any changes committed on the source\n"
+" branch since branching are applied to the target branch. This uses\n"
+" merge tracking to skip all those revisions that have already been\n"
+" merged, so a sync merge can be repeated periodically to stay up-to-\n"
+" date with the source branch.\n"
+"\n"
+" SOURCE specifies the branch from where the changes will be pulled, and\n"
+" TARGET_WCPATH specifies a working copy of the target branch to which\n"
+" the changes will be applied. Normally SOURCE and TARGET_WCPATH should\n"
+" each correspond to the root of a branch. (If you want to merge only a\n"
+" subtree, then the subtree path must be included in both SOURCE and\n"
+" TARGET_WCPATH; this is discouraged, to avoid subtree mergeinfo.)\n"
+"\n"
+" SOURCE is usually a URL. The optional '@REV' specifies both the peg\n"
+" revision of the URL and the latest revision that will be considered\n"
+" for merging; if REV is not specified, the HEAD revision is assumed. If\n"
+" SOURCE is a working copy path, the corresponding URL of the path is\n"
+" used, and the default value of 'REV' is the base revision (usually the\n"
+" revision last updated to).\n"
+"\n"
+" TARGET_WCPATH is a working copy path; if omitted, '.' is assumed.\n"
+"\n"
+" - Sync Merge Example -\n"
+"\n"
+" A feature is being developed on a branch called 'feature', which has\n"
+" originally been a copy of trunk. The feature branch has been regularly\n"
+" synced with trunk to keep up with the changes made there. The previous\n"
+" sync merges are not shown on this diagram, and the last of them was\n"
+" done when HEAD was r100. Currently, HEAD is r200.\n"
+"\n"
+" feature +------------------------o-----\n"
+" / ^\n"
+" / ............ |\n"
+" / . . /\n"
+" trunk ------+------------L--------------R------\n"
+" r100 r200\n"
+"\n"
+" Subversion will locate all the changes on 'trunk' that have not yet\n"
+" been merged into the 'feature' branch. In this case that is a single\n"
+" range, r100:200. In the diagram above, L marks the left side\n"
+" (trunk@100) and R marks the right side (trunk@200) of the merge. The\n"
+" difference between L and R will be applied to the target working copy\n"
+" path. In this case, the working copy is a clean checkout of the entire\n"
+" 'feature' branch.\n"
+"\n"
+" To perform this sync merge, have a clean working copy of the feature\n"
+" branch and run the following command in its top-level directory:\n"
+"\n"
+" svn merge ^/trunk\n"
+"\n"
+" Note that the merge is now only in your local working copy and still\n"
+" needs to be committed to the repository so that it can be seen by\n"
+" others. You can review the changes and you may have to resolve\n"
+" conflicts before you commit the merge.\n"
+"\n"
+"\n"
+" 1. This form is called a 'cherry-pick' merge:\n"
+"\n"
+" svn merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]\n"
+"\n"
+" A cherry-pick merge is used to merge specific revisions (or revision\n"
+" ranges) from one branch to another. By default, this uses merge\n"
+" tracking to automatically skip any revisions that have already been\n"
+" merged to the target; you can use the --ignore-ancestry option to\n"
+" disable such skipping.\n"
+"\n"
+" SOURCE is usually a URL. The optional '@REV' specifies only the peg\n"
+" revision of the URL and does not affect the merge range; if REV is not\n"
+" specified, the HEAD revision is assumed. If SOURCE is a working copy\n"
+" path, the corresponding URL of the path is used, and the default value\n"
+" of 'REV' is the base revision (usually the revision last updated to).\n"
+"\n"
+" TARGET_WCPATH is a working copy path; if omitted, '.' is assumed.\n"
+"\n"
+" The revision ranges to be merged are specified by the '-r' and/or '-c'\n"
+" options. '-r N:M' refers to the difference in the history of the\n"
+" source branch between revisions N and M. You can use '-c M' to merge\n"
+" single revisions: '-c M' is equivalent to '-r <M-1>:M'. Each such\n"
+" difference is applied to TARGET_WCPATH.\n"
+"\n"
+" If the mergeinfo in TARGET_WCPATH indicates that revisions within the\n"
+" range were already merged, changes made in those revisions are not\n"
+" merged again. If needed, the range is broken into multiple sub-ranges,\n"
+" and each sub-range is merged separately.\n"
+"\n"
+" A 'reverse range' can be used to undo changes. For example, when\n"
+" source and target refer to the same branch, a previously committed\n"
+" revision can be 'undone'. In a reverse range, N is greater than M in\n"
+" '-r N:M', or the '-c' option is used with a negative number: '-c -M'\n"
+" is equivalent to '-r M:<M-1>'.\n"
+"\n"
+" Multiple '-c' and/or '-r' options may be specified and mixing of\n"
+" forward and reverse ranges is allowed.\n"
+"\n"
+" - Cherry-pick Merge Example -\n"
+"\n"
+" A bug has been fixed on trunk in revision 50. This fix needs to\n"
+" be merged from trunk onto the release branch.\n"
+"\n"
+" 1.x-release +-----------------------o-----\n"
+" / ^\n"
+" / |\n"
+" / |\n"
+" trunk ------+--------------------------LR-----\n"
+" r50\n"
+"\n"
+" In the above diagram, L marks the left side (trunk@49) and R marks the\n"
+" right side (trunk@50) of the merge. The difference between the left\n"
+" and right side is applied to the target working copy path.\n"
+"\n"
+" Note that the difference between revision 49 and 50 is exactly those\n"
+" changes that were committed in revision 50, not including changes\n"
+" committed in revision 49.\n"
+"\n"
+" To perform the merge, have a clean working copy of the release branch\n"
+" and run the following command in its top-level directory; remember\n"
+" that the default target is '.':\n"
+"\n"
+" svn merge -c50 ^/trunk\n"
+"\n"
+" You can also cherry-pick several revisions and/or revision ranges:\n"
+"\n"
+" svn merge -c50,54,60 -r65:68 ^/trunk\n"
+"\n"
+"\n"
+" 2. This form is called a 'reintegrate merge':\n"
+"\n"
+" svn merge --reintegrate SOURCE[@REV] [TARGET_WCPATH]\n"
+"\n"
+" In a reintegrate merge, an (e.g. feature) branch is merged back to its\n"
+" originating branch. In other words, the source branch has originally\n"
+" been created by copying the target branch, development has concluded\n"
+" on the source branch and it should now be merged back into the target\n"
+" branch.\n"
+" \n"
+" SOURCE is the URL of a branch to be merged back. If REV is specified,\n"
+" it is used as the peg revision for SOURCE; if REV is not specified,\n"
+" the HEAD revision is assumed.\n"
+"\n"
+" TARGET_WCPATH is a working copy of the branch the changes will be\n"
+" applied to.\n"
+"\n"
+" - Reintegrate Merge Example -\n"
+"\n"
+" A feature has been developed on a branch called 'feature'. The feature\n"
+" branch started as a copy of trunk@W. Work on the feature has completed\n"
+" and it should be merged back into the trunk.\n"
+"\n"
+" The feature branch was last synced with trunk up to revision X. So the\n"
+" difference between trunk@X and feature@HEAD contains the complete set\n"
+" of changes that implement the feature, and no other changes. These\n"
+" changes are applied to trunk.\n"
+"\n"
+" feature +--------------------------------R\n"
+" / . \\\n"
+" / ............. \\\n"
+" / . v\n"
+" trunk ------+--------------------L------------------o\n"
+" rW rX\n"
+"\n"
+" In the diagram above, L marks the left side (trunk@X) and R marks the\n"
+" right side (feature@HEAD) of the merge. The difference between the\n"
+" left and right side is merged into trunk, the target.\n"
+"\n"
+" To perform the merge, have a clean working copy of trunk and run the\n"
+" following command in its top-level directory:\n"
+"\n"
+" svn merge --reintegrate ^/feature\n"
+"\n"
+" To prevent unnecessary merge conflicts, a reintegrate merge requires\n"
+" that TARGET_WCPATH is not a mixed-revision working copy, has no local\n"
+" modifications, and has no switched subtrees.\n"
+"\n"
+" A reintegrate merge also requires that the source branch is coherently\n"
+" synced with the target -- in the above example, this means that all\n"
+" revisions between the branch point W and the last merged revision X\n"
+" are merged to the feature branch, so that there are no unmerged\n"
+" revisions in-between.\n"
+"\n"
+" After the reintegrate merge, the feature branch cannot be synced to\n"
+" the trunk again without merge conflicts. If further work must be done\n"
+" on the feature branch, it should be deleted and then re-created.\n"
+"\n"
+"\n"
+" 3. This form is called a '2-URL merge':\n"
+"\n"
+" svn merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]\n"
+"\n"
+" Two source URLs are specified, together with two revisions N and M.\n"
+" The two sources are compared at the specified revisions, and the\n"
+" difference is applied to TARGET_WCPATH, which is a path to a working\n"
+" copy of another branch. The three branches involved can be completely\n"
+" unrelated.\n"
+"\n"
+" You should use this merge variant only if the other variants do not\n"
+" apply to your situation, as this variant can be quite complex to\n"
+" master.\n"
+"\n"
+" If TARGET_WCPATH is omitted, a default value of '.' is assumed.\n"
+" However, in the special case where both sources refer to a file node\n"
+" with the same basename and a similarly named file is also found within\n"
+" '.', the differences will be applied to that local file. The source\n"
+" revisions default to HEAD if omitted.\n"
+"\n"
+" The sources can also be specified as working copy paths, in which case\n"
+" the URLs of the merge sources are derived from the working copies.\n"
+"\n"
+" - 2-URL Merge Example -\n"
+"\n"
+" Two features have been developed on separate branches called 'foo' and\n"
+" 'bar'. It has since become clear that 'bar' should be combined with\n"
+" the 'foo' branch for further development before reintegration.\n"
+"\n"
+" Although both feature branches originate from trunk, they are not\n"
+" directly related -- one is not a direct copy of the other. A 2-URL\n"
+" merge is necessary.\n"
+"\n"
+" The 'bar' branch has been synced with trunk up to revision 500. So the\n"
+" difference between trunk@500 and bar@HEAD contains the complete\n"
+" set of changes related to feature 'bar', and no other changes. These\n"
+" changes are applied to the 'foo' branch.\n"
+"\n"
+" foo +-----------------------------------o\n"
+" / ^\n"
+" / /\n"
+" / r500 /\n"
+" trunk ------+------+-----------------L---------> /\n"
+" \\ . /\n"
+" \\ ............ /\n"
+" \\ . /\n"
+" bar +-----------------------------------R\n"
+"\n"
+" In the diagram above, L marks the left side (trunk@500) and R marks\n"
+" the right side (bar@HEAD) of the merge. The difference between the\n"
+" left and right side is applied to the target working copy path, in\n"
+" this case a working copy of the 'foo' branch.\n"
+"\n"
+" To perform the merge, have a clean working copy of the 'foo' branch\n"
+" and run the following command in its top-level directory:\n"
+"\n"
+" svn merge ^/trunk@500 ^/bar\n"
+"\n"
+" The exact changes applied by a 2-URL merge can be previewed with svn's\n"
+" diff command, which is a good idea to verify if you do not have the\n"
+" luxury of a clean working copy to merge to. In this case:\n"
+"\n"
+" svn diff ^/trunk@500 ^/bar@HEAD\n"
+"\n"
+" Note that a 2-URL merge can also merge from foreign repositories.\n"
+" While SOURCE1 and SOURCE2 must both come from the same repository,\n"
+" TARGET_WCPATH may come from a different repository than the sources.\n"
+" However, there are some caveats. Most notably, copies made in the\n"
+" merge source will be transformed into plain additions in the merge\n"
+" target. Also, merge-tracking is not supported when foreign\n"
+" repositories are involved.\n"
+"\n"
+"\n"
+" The following applies to all types of merges:\n"
+"\n"
+" To prevent unnecessary merge conflicts, svn merge requires that\n"
+" TARGET_WCPATH is not a mixed-revision working copy. Running 'svn update'\n"
+" before starting a merge ensures that all items in the working copy are\n"
+" based on the same revision.\n"
+"\n"
+" If possible, you should have no local modifications in the merge's target\n"
+" working copy prior to the merge, to keep things simpler. It will be\n"
+" easier to revert the merge and to understand the branch's history.\n"
+"\n"
+" Switched sub-paths should also be avoided during merging, as they may\n"
+" cause incomplete merges and create subtree mergeinfo.\n"
+"\n"
+" For each merged item a line will be printed with characters reporting the\n"
+" action taken. These characters have the following meaning:\n"
+"\n"
+" A Added\n"
+" D Deleted\n"
+" U Updated\n"
+" C Conflict\n"
+" G Merged\n"
+" E Existed\n"
+" R Replaced\n"
+"\n"
+" Characters in the first column report about the item itself.\n"
+" Characters in the second column report about properties of the item.\n"
+" A 'C' in the third column indicates a tree conflict, while a 'C' in\n"
+" the first and second columns indicate textual conflicts in files\n"
+" and in property values, respectively.\n"
+"\n"
+" - Merge Tracking -\n"
+"\n"
+" Subversion uses the svn:mergeinfo property to track merge history. This\n"
+" property is considered at the start of a merge to determine what to merge\n"
+" and it is updated at the conclusion of the merge to describe the merge\n"
+" that took place. Mergeinfo is used only if the two sources are on the\n"
+" same line of history -- if the first source is an ancestor of the second,\n"
+" or vice-versa (i.e. if one has originally been created by copying the\n"
+" other). This is verified and enforced when using sync merges and\n"
+" reintegrate merges.\n"
+"\n"
+" The --ignore-ancestry option prevents merge tracking and thus ignores\n"
+" mergeinfo, neither considering it nor recording it.\n"),
{'r', 'c', 'N', opt_depth, 'q', opt_force, opt_dry_run, opt_merge_cmd,
opt_record_only, 'x', opt_ignore_ancestry, opt_accept, opt_reintegrate,
opt_allow_mixed_revisions} },