You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@subversion.apache.org by ju...@apache.org on 2011/10/31 15:35:13 UTC
svn commit: r1195480 - /subversion/trunk/subversion/svn/main.c
Author: julianfoad
Date: Mon Oct 31 14:35:13 2011
New Revision: 1195480
URL: http://svn.apache.org/viewvc?rev=1195480&view=rev
Log:
Improve the help text for 'svn merge', separating the 'sync' and 'cherry-
pick' forms of the command into two sections as well as other changes.
* subversion/svn/main.c
(svn_cl__cmd_table): Update the 'merge' help text.
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=1195480&r1=1195479&r2=1195480&view=diff
==============================================================================
--- subversion/trunk/subversion/svn/main.c (original)
+++ subversion/trunk/subversion/svn/main.c Mon Oct 31 14:35:13 2011
@@ -659,56 +659,47 @@ const svn_opt_subcommand_desc2_t svn_cl_
{'c', N_("the change made in revision ARG")}} },
{ "merge", svn_cl__merge, {0}, N_
- ("Apply the differences between two sources to a working copy path.\n"
- "usage: 1. merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]\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"
- " 1. The first form is called a 'sync', or 'cherry-pick', merge:\n"
- " svn merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]\n"
+ " 0. This form is called a 'sync' (aka 'catch-up') merge:\n"
"\n"
- " A sync merge is used to merge into a branch any unmerged changes\n"
- " made on its immediate ancestor branch.\n"
- "\n"
- " A cherry-picking merge is used to merge specific revisions from\n"
- " one branch to another.\n"
- "\n"
- " SOURCE is usually a URL. The source of a cherry-picking merge can\n"
- " also be a working copy path, in which case the corresponding URL\n"
- " of the path is used.\n"
- "\n"
- " If REV is specified, it is used as the peg revision for SOURCE,\n"
- " i.e. SOURCE is looked up in the repository at revision REV.\n"
- " If REV is not specified, the HEAD revision is assumed.\n"
- "\n"
- " TARGET_WCPATH is a working copy of the branch the changes will\n"
- " be applied to.\n"
- "\n"
- " '-r N:M' specifies a revision range to be merged. The difference\n"
- " between SOURCE@REV as it existed at revision N, and SOURCE@REV at\n"
- " it existed at revision M, is merged into TARGET_WCPATH. If no\n"
- " revision range is specified, the default range of 0:REV is used.\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"
+ " svn merge SOURCE[@REV] [TARGET_WCPATH]\n"
"\n"
- " If N is greater than M, 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"
+ " 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"
- " '-c M' is equivalent to the range '-r <M-1>:M'.\n"
- " '-c -M' does the reverse: '-r M:<M-1>'.\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"
- " Multiple '-c' and/or '-r' options may be specified and mixing of\n"
- " forward and reverse ranges is allowed.\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'.\n"
- " The feature branch is regularly synced with trunk to keep up with\n"
- " changes made there.\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"
@@ -717,18 +708,52 @@ const svn_opt_subcommand_desc2_t svn_cl_
" trunk ------+------------L--------------R------\n"
" r100 r200\n"
"\n"
- " In the above diagram, L marks the 'left' side of the merge\n"
- " (trunk@100), and R marks the 'right' side of the merge (trunk@200).\n"
- " The difference between the left and right side is merged into the target.\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 the merge, check out a working copy of the feature\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"
- " The default revision range is -r0:HEAD, so any unmerged changes\n"
- " will be merged.\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-picking 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-picking Merge Example -\n"
"\n"
@@ -743,8 +768,8 @@ const svn_opt_subcommand_desc2_t svn_cl_
" 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).\n"
- " The difference between the left and right side is merged into the target.\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"
@@ -758,8 +783,9 @@ const svn_opt_subcommand_desc2_t svn_cl_
" svn merge -c50,54,60 ^/trunk\n"
"\n"
"\n"
- " 2. The second form is called a 'reintegrate merge':\n"
- " svn merge --reintegrate SOURCE[@REV] [TARGET_WCPATH]\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 a\n"
@@ -813,8 +839,9 @@ const svn_opt_subcommand_desc2_t svn_cl_
" be done on the feature branch, it should be deleted and then re-created.\n"
"\n"
"\n"
- " 3. The third form is called a '2-URL merge':\n"
- " svn merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]\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"