subversion-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From julianf...@apache.org
Subject svn commit: r1370818 - /subversion/trunk/subversion/svn/main.c
Date Wed, 08 Aug 2012 15:55:38 GMT
Author: julianfoad
Date: Wed Aug  8 15:55:37 2012
New Revision: 1370818

URL: http://svn.apache.org/viewvc?rev=1370818&view=rev
Log:
Update the help text for 'svn merge' to reflect symmetric merge.  There is
more to do here, especially with the 'sync merge example' and 'reintegrate
merge example' sections.

* subversion/svn/main.c
  (svn_cl__options): Just say 'deprecated'.
  (svn_cl__cmd_table): Update 'svn merge' text, combining sections 1 and 2.

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=1370818&r1=1370817&r2=1370818&view=diff
==============================================================================
--- subversion/trunk/subversion/svn/main.c (original)
+++ subversion/trunk/subversion/svn/main.c Wed Aug  8 15:55:37 2012
@@ -313,7 +313,7 @@ const apr_getopt_option_t svn_cl__option
                        "                             "
                        "('merged', 'eligible')")},
   {"reintegrate",   opt_reintegrate, 0,
-                    N_("merge a branch back into its parent branch")},
+                    N_("deprecated")},
   {"strip",         opt_strip, 1,
                     N_("number of leading path components to strip from\n"
                        "                             "
@@ -735,22 +735,16 @@ const svn_opt_subcommand_desc2_t svn_cl_
 "          (the 'sync' merge)\n"
 "       2. merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]\n"
 "          (the 'cherry-pick' merge)\n"
-"       3. merge --reintegrate SOURCE[@REV] [TARGET_WCPATH]\n"
-"          (the 'reintegrate' merge)\n"
-"       4. merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]\n"
+"       3. merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]\n"
 "          (the '2-URL' merge)\n"
 "\n"
-"  1. This form is called a 'sync' (or 'catch-up') merge:\n"
+"  1. This form, with one source path and no revision range:\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"
+"     finds all the changes on the source branch that have not already been\n"
+"     merged to the target branch, and merges them. Merge tracking is used\n"
+"     to know which changes have already been merged.\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"
@@ -766,22 +760,44 @@ const svn_opt_subcommand_desc2_t svn_cl_
 "     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"
+"     TARGET_WCPATH is a working copy path; if omitted, '.' is assumed. In\n"
+"     normal usage the working copy should be up to date, at a single\n"
+"     revision, with no local modifications and no switched subtrees.\n"
+"\n"
+"       - The 'Feature Branch' Merging Pattern -\n"
+"\n"
+"     In this commonly used pattern of merging, a developer is working on\n"
+"     a feature development branch, committing a series of changes that\n"
+"     implement the feature. The developer periodically merges all the\n"
+"     latest changes from the 'parent' branch (from which the feature branch\n"
+"     is branched off). When the feature development is complete, the\n"
+"     developer integrates the feature back into the parent branch by\n"
+"     merging the other way, into a trunk working copy.\n"
+"\n"
+"         trunk  --+----------o------o-o-------------o--\n"
+"                   \\           \\          \\     /\n"
+"                    \\         merge       merge merge\n"
+"                     \\           \\          \\ /\n"
+"         feature      +--o-o-------o----o-o----o-------\n"
+"\n"
+"     In this pattern, a merge from the parent branch to the feature branch\n"
+"     is known as a 'sync' merge (or 'catch-up' merge), and a merge from the\n"
+"     feature branch to the parent branch may be called a 'reintegrate'\n"
+"     merge. The 'sync' merges are normally low-risk because the parent\n"
+"     branch is considered to be more 'stable' than the feature branch, in\n"
+"     the sense of being less likely to contain incomplete or broken work.\n"
+"     By syncing often, these merges can be kept small, avoiding the need\n"
+"     for a difficult 'big bang' merge at reintegration time.\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"
+"                                .            .\n"
+"         trunk  --+------------L--------------R------\n"
+"                   \\                          \\\n"
+"                    \\                         |\n"
+"                     \\                        v\n"
+"         feature      +------------------------o-----\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"
@@ -802,6 +818,40 @@ const svn_opt_subcommand_desc2_t svn_cl_
 "     conflicts before you commit the merge.\n"
 "\n"
 "\n"
+"       - Reintegrate Merge Example -\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"
+"                    rW                   rX\n"
+"         trunk ------+--------------------L------------------o\n"
+"                      \\                   .                 ^\n"
+"                       \\                   .............   /\n"
+"                        \\                               . /\n"
+"         feature         +--------------------------------R\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 ^/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"
+"\n"
 "  2. This form is called a 'cherry-pick' merge:\n"
 "\n"
 "       svn merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]\n"
@@ -871,66 +921,7 @@ const svn_opt_subcommand_desc2_t svn_cl_
 "         svn merge -c50,54,60 -r65:68 ^/trunk\n"
 "\n"
 "\n"
-"  3. 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"
-"  4. This form is called a '2-URL merge':\n"
+"  3. This form is called a '2-URL merge':\n"
 "\n"
 "       svn merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]\n"
 "\n"



Mime
View raw message