subversion-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From julianf...@apache.org
Subject svn commit: r1195480 - /subversion/trunk/subversion/svn/main.c
Date Mon, 31 Oct 2011 14:35:13 GMT
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"



Mime
View raw message