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"
