Mailing-List: contact commits-help@subversion.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@subversion.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1066468 - /subversion/trunk/subversion/svn/main.c
Date: Wed, 02 Feb 2011 13:55:58 -0000
To: commits@subversion.apache.org
From: stsp@apache.org
Message-Id: <20110202135558.8682123889B3@eris.apache.org>

Author: stsp
Date: Wed Feb  2 13:55:58 2011
New Revision: 1066468

URL: http://svn.apache.org/viewvc?rev=1066468&view=rev
Log:
* subversion/svn/main.c
  (svn_cl__cmd_table): Revised help text for "svn merge", written by
   myself and pburba. See for related discussion:
    Date: Fri, 29 Oct 2010 17:57:00 +0200
    From: Stefan Sperling
    To: dev@
    Subject: RFC: revised text for "svn help merge"
    Message-ID: <20101029155700.GA1981@ted.stsp.name>
    http://svn.haxx.se/dev/archive-2010-10/0464.shtml

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=1066468&r1=1066467&r2=1066468&view=diff
==============================================================================
--- subversion/trunk/subversion/svn/main.c (original)
+++ subversion/trunk/subversion/svn/main.c Wed Feb  2 13:55:58 2011
@@ -674,32 +674,226 @@ const svn_opt_subcommand_desc2_t svn_cl_
 
   { "merge", svn_cl__merge, {0}, N_
     ("Apply the differences between two sources to a working copy path.\n"
-     "usage: 1. merge sourceURL1[@N] sourceURL2[@M] [WCPATH]\n"
-     "       2. merge sourceWCPATH1@N sourceWCPATH2@M [WCPATH]\n"
-     "       3. merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [WCPATH]\n"
-     "\n"
-     "  1. In the first form, the source URLs are specified at revisions\n"
-     "     N and M.  These are the two sources to be compared.  The revisions\n"
-     "     default to HEAD if omitted.\n"
-     "\n"
-     "  2. In the second form, the URLs corresponding to the source working\n"
-     "     copy paths define the sources to be compared.  The revisions must\n"
-     "     be specified.\n"
-     "\n"
-     "  3. In the third form, SOURCE can be either a URL or a working copy\n"
-     "     path (in which case its corresponding URL is used).  SOURCE (in\n"
-     "     revision REV) is compared as it existed between revisions N and M\n"
-     "     for each revision range provided.  If REV is not specified, HEAD\n"
-     "     is assumed.  '-c M' is equivalent to '-r <M-1>:M', and '-c -M'\n"
-     "     does the reverse: '-r M:<M-1>'.  If no revision ranges are\n"
-     "     specified, the default range of 0:REV is used.  Multiple '-c'\n"
-     "     and/or '-r' options may be specified, and mixing of forward\n"
-     "     and reverse ranges is allowed.\n"
-     "\n"
-     "  WCPATH is the working copy path that will receive the changes.\n"
-     "  If WCPATH is omitted, a default value of '.' is assumed, unless\n"
-     "  the sources have identical basenames that match a file within '.':\n"
-     "  in which case, the differences will be applied to that file.\n"
+     "usage: 1. merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]\n"
+     "       2. merge --reintegrate SOURCE[@REV] [TARGET_WCPATH]\n"
+     "       3. merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]\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"
+     "\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"
+     "     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"
+     "     The source of a cherry pick merge can also be a working copy path,\n"
+     "     in which case the corresponding URL of the path is used.\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"
+     "\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"
+     "\n"
+     "     '-c M' is equivalent to the range '-r <M-1>:M'.\n"
+     "     '-c -M' does the reverse: '-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"
+     "       - 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"
+     "\n"
+     "                 feature  +------------------------o-----\n"
+     "                         /                         ^\n"
+     "                        /                         /\n"
+     "                       /          .............../\n"
+     "         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"
+     "\n"
+     "     To perform the 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"
+     "       - Cherry-picking 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).\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 feature\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. The second form is called a \"reintegrate merge\":\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"
+     "     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. The third form is called a \"2-URL merge\":\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 is (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-UL 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"
+     "\n"
+     "  The following applies to all types of merges:\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"
@@ -709,6 +903,7 @@ const svn_opt_subcommand_desc2_t svn_cl_
      "    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"
@@ -717,12 +912,15 @@ const svn_opt_subcommand_desc2_t svn_cl_
      "  the first and second columns indicate textual conflicts in files\n"
      "  and in property values, respectively.\n"
      "\n"
-     "  NOTE:  Subversion will only record metadata to track the merge\n"
-     "  if the two sources are on the same line of history -- if the\n"
-     "  first source is an ancestor of the second, or vice-versa.  This is\n"
-     "  guaranteed to be the case when using the third form listed above.\n"
-     "  The --ignore-ancestry option overrides this, forcing Subversion to\n"
-     "  regard the sources as unrelated and not to track the merge.\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"),
     {'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} },