You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@subversion.apache.org by st...@apache.org on 2011/12/13 13:47:33 UTC
svn commit: r1213665 - /subversion/site/publish/docs/svn-merge.txt
Author: stsp
Date: Tue Dec 13 12:47:33 2011
New Revision: 1213665
URL: http://svn.apache.org/viewvc?rev=1213665&view=rev
Log:
* site/docs/svn-merge.txt: Put current output of 'svn help merge' in here.
Modified:
subversion/site/publish/docs/svn-merge.txt
Modified: subversion/site/publish/docs/svn-merge.txt
URL: http://svn.apache.org/viewvc/subversion/site/publish/docs/svn-merge.txt?rev=1213665&r1=1213664&r2=1213665&view=diff
==============================================================================
--- subversion/site/publish/docs/svn-merge.txt (original)
+++ subversion/site/publish/docs/svn-merge.txt Tue Dec 13 12:47:33 2011
@@ -1,86 +1,117 @@
+merge: Merge changes into a working copy.
+usage: 1. merge SOURCE[@REV] [TARGET_WCPATH]
+ (the 'sync' merge)
+ 2. merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]
+ (the 'cherry-pick' merge)
+ 3. merge --reintegrate SOURCE[@REV] [TARGET_WCPATH]
+ (the 'reintegrate' merge)
+ 4. merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]
+ (the '2-URL' merge)
+
+ 1. This form is called a 'sync' (or 'catch-up') merge:
+
+ svn merge SOURCE[@REV] [TARGET_WCPATH]
+
+ A sync merge is used to fetch all the latest changes made on a parent
+ branch. In other words, the target branch has originally been created
+ by copying the source branch, and any changes committed on the source
+ branch since branching are applied to the target branch. This uses
+ merge tracking to skip all those revisions that have already been
+ merged, so a sync merge can be repeated periodically to stay up-to-
+ date with the source branch.
+
+ SOURCE specifies the branch from where the changes will be pulled, and
+ TARGET_WCPATH specifies a working copy of the target branch to which
+ the changes will be applied. Normally SOURCE and TARGET_WCPATH should
+ each correspond to the root of a branch. (If you want to merge only a
+ subtree, then the subtree path must be included in both SOURCE and
+ TARGET_WCPATH; this is discouraged, to avoid subtree mergeinfo.)
+
+ SOURCE is usually a URL. The optional '@REV' specifies both the peg
+ revision of the URL and the latest revision that will be considered
+ for merging; if REV is not specified, the HEAD revision is assumed. If
+ SOURCE is a working copy path, the corresponding URL of the path is
+ used, and the default value of 'REV' is the base revision (usually the
+ revision last updated to).
-$LastChangedDate$
+ TARGET_WCPATH is a working copy path; if omitted, '.' is assumed.
-The following is the help text of 'svn merge' in 1.7.x. This information is
-also available in the Subversion Book:
- http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.merge.html
-
-
-merge: Apply the differences between two sources to a working copy path.
-usage: 1. merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]
- 2. merge --reintegrate SOURCE[@REV] [TARGET_WCPATH]
- 3. merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]
-
- 1. The first form is called a "sync", or "cherry-pick", merge:
- svn merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]
-
- A sync merge is used to merge into a branch any unmerged changes
- made on its immediate ancestor branch.
+ - Sync Merge Example -
- A cherry-picking merge is used to merge specific revisions from
- one branch to another.
+ A feature is being developed on a branch called 'feature', which has
+ originally been a copy of trunk. The feature branch has been regularly
+ synced with trunk to keep up with the changes made there. The previous
+ sync merges are not shown on this diagram, and the last of them was
+ done when HEAD was r100. Currently, HEAD is r200.
+
+ feature +------------------------o-----
+ / ^
+ / ............ |
+ / . . /
+ trunk ------+------------L--------------R------
+ r100 r200
- SOURCE is usually a URL. The source of a cherry-picking merge can
- also be a working copy path, in which case the corresponding URL
- of the path is used.
+ Subversion will locate all the changes on 'trunk' that have not yet
+ been merged into the 'feature' branch. In this case that is a single
+ range, r100:200. In the diagram above, L marks the left side
+ (trunk@100) and R marks the right side (trunk@200) of the merge. The
+ difference between L and R will be applied to the target working copy
+ path. In this case, the working copy is a clean checkout of the entire
+ 'feature' branch.
- If REV is specified, it is used as the peg revision for SOURCE,
- i.e. SOURCE is looked up in the repository at revision REV.
- If REV is not specified, the HEAD revision is assumed.
+ To perform this sync merge, have a clean working copy of the feature
+ branch and run the following command in its top-level directory:
- TARGET_WCPATH is a working copy of the branch the changes will
- be applied to.
+ svn merge ^/trunk
- '-r N:M' specifies a revision range to be merged. The difference
- between SOURCE@REV as it existed at revision N, and SOURCE@REV at
- it existed at revision M, is merged into TARGET_WCPATH. If no
- revision range is specified, the default range of 0:REV is used.
-
- If mergeinfo within TARGET_WCPATH indicates that revisions within
- the range were already merged, changes made in those revisions
- are not merged again. If needed, the range is broken into multiple
- sub-ranges, and each sub-range is merged separately.
-
- If N is greater than M, the range is a "reverse range".
- A reverse range can be used to undo changes made to SOURCE
- between revisions N and M.
+ Note that the merge is now only in your local working copy and still
+ needs to be committed to the repository so that it can be seen by
+ others. You can review the changes and you may have to resolve
+ conflicts before you commit the merge.
+
+
+ 2. This form is called a 'cherry-pick' merge:
+
+ svn merge [-c M[,N...] | -r N:M ...] SOURCE[@REV] [TARGET_WCPATH]
+
+ A cherry-pick merge is used to merge specific revisions (or revision
+ ranges) from one branch to another. By default, this uses merge
+ tracking to automatically skip any revisions that have already been
+ merged to the target; you can use the --ignore-ancestry option to
+ disable such skipping.
+
+ SOURCE is usually a URL. The optional '@REV' specifies only the peg
+ revision of the URL and does not affect the merge range; if REV is not
+ specified, the HEAD revision is assumed. If SOURCE is a working copy
+ path, the corresponding URL of the path is used, and the default value
+ of 'REV' is the base revision (usually the revision last updated to).
+
+ TARGET_WCPATH is a working copy path; if omitted, '.' is assumed.
+
+ The revision ranges to be merged are specified by the '-r' and/or '-c'
+ options. '-r N:M' refers to the difference in the history of the
+ source branch between revisions N and M. You can use '-c M' to merge
+ single revisions: '-c M' is equivalent to '-r <M-1>:M'. Each such
+ difference is applied to TARGET_WCPATH.
+
+ If the mergeinfo in TARGET_WCPATH indicates that revisions within the
+ range were already merged, changes made in those revisions are not
+ merged again. If needed, the range is broken into multiple sub-ranges,
+ and each sub-range is merged separately.
+
+ A 'reverse range' can be used to undo changes. For example, when
+ source and target refer to the same branch, a previously committed
+ revision can be 'undone'. In a reverse range, N is greater than M in
+ '-r N:M', or the '-c' option is used with a negative number: '-c -M'
+ is equivalent to '-r M:<M-1>'.
- '-c M' is equivalent to the range '-r <M-1>:M'.
- '-c -M' does the reverse: '-r M:<M-1>'.
-
Multiple '-c' and/or '-r' options may be specified and mixing of
forward and reverse ranges is allowed.
- - Sync Merge Example -
-
- A feature is being developed on a branch called "feature".
- The feature branch is regularly synced with trunk to keep up with
- changes made there.
-
- feature +------------------------o-----
- / ^
- / /
- / .............../
- trunk ------+------------L--------------R------
- r100 r200
-
- In the above diagram, L marks the "left" side of the merge
- (trunk@100), and R marks the "right" side of the merge (trunk@200).
- The difference between the left and right side is merged into the target.
-
- To perform the merge, check out a working copy of the feature
- branch and run the following command in the top-level directory
- of the working copy:
-
- svn merge ^/trunk
+ - Cherry-pick Merge Example -
- The default revision range is -r0:HEAD, so any unmerged changes
- will be merged.
-
- - Cherry-picking Merge Example -
-
- A bug has been fixed on trunk on revision 50. This fix needs to
- be merged from the trunk into the release branch.
+ A bug has been fixed on trunk in revision 50. This fix needs to
+ be merged from trunk onto the release branch.
1.x-release +-----------------------o-----
/ ^
@@ -88,161 +119,168 @@ usage: 1. merge [-c M[,N...] | -r N:M ..
/ |
trunk ------+--------------------------LR-----
r50
-
- In the above diagram, L marks the left side of the merge (trunk@49)
- and R marks the right side of the merge (trunk@50).
- The difference between the left and right side is merged into the target.
-
- To perform the merge, check out a working copy of the release
- branch and run the following command in the top-level directory
- of the working copy:
+
+ In the above diagram, L marks the left side (trunk@49) and R marks the
+ right side (trunk@50) of the merge. The difference between the left
+ and right side is applied to the target working copy path.
+
+ Note that the difference between revision 49 and 50 is exactly those
+ changes that were committed in revision 50, not including changes
+ committed in revision 49.
+
+ To perform the merge, have a clean working copy of the release branch
+ and run the following command in its top-level directory; remember
+ that the default target is '.':
svn merge -c50 ^/trunk
- If several commits to trunk were related to the fix, multiple
- revisions can be merged:
+ You can also cherry-pick several revisions and/or revision ranges:
- svn merge -c50,54,60 ^/trunk
+ svn merge -c50,54,60 -r65:68 ^/trunk
- 2. The second form is called a "reintegrate merge":
- svn merge --reintegrate SOURCE[@REV] [TARGET_WCPATH]
+ 3. This form is called a 'reintegrate merge':
- SOURCE is the URL of a branch to be merged back into (usually) its
- immediate ancestor branch. If REV is specified, it is used a
- the peg revision for SOURCE, i.e. SOURCE is looked up in the
- repository at revision REV. If REV is not specified, the HEAD
- revision is assumed.
+ svn merge --reintegrate SOURCE[@REV] [TARGET_WCPATH]
- TARGET_WCPATH is a working copy of the branch the changes will
- be applied to.
+ In a reintegrate merge, an (e.g. feature) branch is merged back to its
+ originating branch. In other words, the source branch has originally
+ been created by copying the target branch, development has concluded
+ on the source branch and it should now be merged back into the target
+ branch.
+
+ SOURCE is the URL of a branch to be merged back. If REV is specified,
+ it is used as the peg revision for SOURCE; if REV is not specified,
+ the HEAD revision is assumed.
+
+ TARGET_WCPATH is a working copy of the branch the changes will be
+ applied to.
- Reintegrate Merge Example -
- A feature has been developed on a branch called "feature".
- The feature branch started as a copy of trunk@W. Work on the
- feature has completed and it should be merged back into the trunk.
-
- The feature branch was last synced with its immediate ancestor,
- the trunk, in revision X. So the difference between trunk@X and
- feature@HEAD contains the complete set of changes that implement
- the feature, and no other changes. These changes are applied to
- the trunk.
-
- feature +-------------------------------R
- / . \
- / .............. \
- / . v
+ A feature has been developed on a branch called 'feature'. The feature
+ branch started as a copy of trunk@W. Work on the feature has completed
+ and it should be merged back into the trunk.
+
+ The feature branch was last synced with trunk up to revision X. So the
+ difference between trunk@X and feature@HEAD contains the complete set
+ of changes that implement the feature, and no other changes. These
+ changes are applied to trunk.
+
+ feature +--------------------------------R
+ / . \
+ / ............. \
+ / . v
trunk ------+--------------------L------------------o
rW rX
- In the diagram above, L marks the left side of the merge (trunk@X),
- and R marks the right side of the merge (feature@HEAD). The difference
- between the left and right side is merged into the target.
+ In the diagram above, L marks the left side (trunk@X) and R marks the
+ right side (feature@HEAD) of the merge. The difference between the
+ left and right side is merged into trunk, the target.
- To perform the merge, check out a working copy of the trunk, and run
- the following command in the top-level directory of the working copy:
+ To perform the merge, have a clean working copy of trunk and run the
+ following command in its top-level directory:
svn merge --reintegrate ^/feature
- To prevent unnecessary merge conflicts, reintegrate merges require
- that TARGET_WCPATH is not a mixed-revision working copy, has no
- local modifications, and has no switched subtrees.
-
- Reintegrate merges also require that the reintegrate source be fully
- synced with the target since their common branch point.
- In the above example this means that all of the changes made
- on trunk between revision W and revision X are fully merged to
- the feature branch before it can be reintegrated back to trunk.
-
- After the reintegrate merge, the feature branch cannot be synced
- to the trunk again without merge conflicts. If further work must
- be done on the feature branch, it should be deleted and then re-created.
+ To prevent unnecessary merge conflicts, a reintegrate merge requires
+ that TARGET_WCPATH is not a mixed-revision working copy, has no local
+ modifications, and has no switched subtrees.
+
+ A reintegrate merge also requires that the source branch is coherently
+ synced with the target -- in the above example, this means that all
+ revisions between the branch point W and the last merged revision X
+ are merged to the feature branch, so that there are no unmerged
+ revisions in-between.
+ After the reintegrate merge, the feature branch cannot be synced to
+ the trunk again without merge conflicts. If further work must be done
+ on the feature branch, it should be deleted and then re-created.
- 3. The third form is called a "2-URL merge":
- svn merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]
+
+ 4. This form is called a '2-URL merge':
+
+ svn merge SOURCE1[@N] SOURCE2[@M] [TARGET_WCPATH]
Two source URLs are specified, together with two revisions N and M.
- The two sources to be compared at the specified revisions, and the
+ The two sources are compared at the specified revisions, and the
difference is applied to TARGET_WCPATH, which is a path to a working
- copy of another branch.
+ copy of another branch. The three branches involved can be completely
+ unrelated.
- The revisions default to HEAD if omitted.
+ You should use this merge variant only if the other variants do not
+ apply to your situation, as this variant can be quite complex to
+ master.
+
+ If TARGET_WCPATH is omitted, a default value of '.' is assumed.
+ However, in the special case where both sources refer to a file node
+ with the same basename and a similarly named file is also found within
+ '.', the differences will be applied to that local file. The source
+ revisions default to HEAD if omitted.
- If TARGET_WCPATH is omitted, a default value of '.' is assumed,
- unless the sources have identical basenames that match a file
- within '.'; In which case, the differences will be applied to
- that file.
-
- The sources can also be specified as working copy paths, in which
- case the URLs of the merge sources are derived from the working copies.
-
- This is the most flexible type of merge, but also the most difficult
- to use. It can be used to merge the differences between two (possibly
- ancestrally unrelated) branches into a working copy of another branch.
- This type of merge should be used very carefully because the probability
- of merge conflicts is quite high. In most use cases, a sync, cherry-pick,
- or reintegrate merge is sufficient and reduces the chances of mistakes.
+ The sources can also be specified as working copy paths, in which case
+ the URLs of the merge sources are derived from the working copies.
- 2-URL Merge Example -
- A feature has been developed on a branch called "feature".
- Development for the upcoming 3.0 release has happened in parallel on
- the "3.x-release" branch. The work on the feature branch must be
- merged to the 3.x-release branch. However, the feature branch and
- the 3.x-release branch are not directly related, so a 2-URL merge
- is needed.
- The feature branch was last synced with its immediate ancestor,
- the trunk, up to revision 500. So the difference between trunk@500
- and feature@HEAD contains the complete set of changes related to
- the feature, and no other changes. These changes are applied to
- the 3.x-release branch.
+ Two features have been developed on separate branches called 'foo' and
+ 'bar'. It has since become clear that 'bar' should be combined with
+ the 'foo' branch for further development before reintegration.
+
+ Although both feature branches originate from trunk, they are not
+ directly related -- one is not a direct copy of the other. A 2-URL
+ merge is necessary.
+
+ The 'bar' branch has been synced with trunk up to revision 500.
+ (If this revision number is not known, it can be located using the
+ 'svn log' and/or 'svn mergeinfo' commands.)
+ The difference between trunk@500 and bar@HEAD contains the complete
+ set of changes related to feature 'bar', and no other changes. These
+ changes are applied to the 'foo' branch.
- 3.x-release +-----------------------------------o
+ foo +-----------------------------------o
/ ^
/ /
/ r500 /
trunk ------+------+-----------------L---------> /
- \ . /
- \ ........... /
+ \ . /
+ \ ............ /
\ . /
- feature +-----------------------------------R
+ bar +-----------------------------------R
+
+ In the diagram above, L marks the left side (trunk@500) and R marks
+ the right side (bar@HEAD) of the merge. The difference between the
+ left and right side is applied to the target working copy path, in
+ this case a working copy of the 'foo' branch.
+
+ To perform the merge, have a clean working copy of the 'foo' branch
+ and run the following command in its top-level directory:
- In the diagram above, L marks the left side of the merge (trunk@500),
- and R marks the right side of the merge is (feature@HEAD).
- The difference between the left and right side is merged into the target.
-
- To perform the merge, check out a working copy of the 3.x-release
- branch and run the following command in the top-level directory
- of the working copy:
-
- svn merge ^/trunk@500 ^/feature
-
- Before performing a 2-URL merge, it is a good idea to preview the
- changes which will be merged, because there is no guarantee that
- the merge will be free of conflicts. The preview can be done with
- the svn diff command:
-
- svn diff ^/trunk@500 ^/feature@HEAD
-
- Note that a 2-URL merge can also merge from foreign repositories.
- While SOURCE1 and SOURCE2 must both come from the same repository,
- TARGET_WCPATH may come from a different repository than the sources.
- However, there are some caveats. Most notably, copies made in the
- merge source will be transformed into plain additions in the merge
- target. Also, merge-tracking is not supported.
+ svn merge ^/trunk@500 ^/bar
+
+ The exact changes applied by a 2-URL merge can be previewed with svn's
+ diff command, which is a good idea to verify if you do not have the
+ luxury of a clean working copy to merge to. In this case:
+
+ svn diff ^/trunk@500 ^/bar@HEAD
The following applies to all types of merges:
To prevent unnecessary merge conflicts, svn merge requires that
- TARGET_WCPATH is not a mixed-revision working copy.
- Running 'svn update' before starting a merge ensures that all
- items in the working copy are based on the same revision.
+ TARGET_WCPATH is not a mixed-revision working copy. Running 'svn update'
+ before starting a merge ensures that all items in the working copy are
+ based on the same revision.
+
+ If possible, you should have no local modifications in the merge's target
+ working copy prior to the merge, to keep things simpler. It will be
+ easier to revert the merge and to understand the branch's history.
- For each merged item a line will be printed with characters reporting
- the action taken. These characters have the following meaning:
+ Switched sub-paths should also be avoided during merging, as they may
+ cause incomplete merges and create subtree mergeinfo.
+
+ For each merged item a line will be printed with characters reporting the
+ action taken. These characters have the following meaning:
A Added
D Deleted
@@ -258,15 +296,29 @@ usage: 1. merge [-c M[,N...] | -r N:M ..
the first and second columns indicate textual conflicts in files
and in property values, respectively.
- NOTE: Subversion uses the svn:mergeinfo property to track merge
- history. This property is considered at the start of a merge to
- determine what to merge and it is updated at the conclusion of the
- merge to describe the merge that took place. Mergeinfo is used only
- if the two sources are on the same line of history -- if the first
- source is an ancestor of the second, or vice-versa. This is guaranteed
- to be the case when using sync merges and reintegrate merges.
- The --ignore-ancestry option prevents merge tracking and thus
- ignores mergeinfo, neither considering it nor recording it.
+ - Merge Tracking -
+
+ Subversion uses the svn:mergeinfo property to track merge history. This
+ property is considered at the start of a merge to determine what to merge
+ and it is updated at the conclusion of the merge to describe the merge
+ that took place. Mergeinfo is used only if the two sources are on the
+ same line of history -- if the first source is an ancestor of the second,
+ or vice-versa (i.e. if one has originally been created by copying the
+ other). This is verified and enforced when using sync merges and
+ reintegrate merges.
+
+ The --ignore-ancestry option prevents merge tracking and thus ignores
+ mergeinfo, neither considering it nor recording it.
+
+ - Merging from foreign repositories -
+
+ Subversion does support merging from foreign repositories.
+ While all merge source URLs must point to the same repository, the merge
+ target working copy may come from a different repository than the source.
+ However, there are some caveats. Most notably, copies made in the
+ merge source will be transformed into plain additions in the merge
+ target. Also, merge-tracking is not supported for merges from foreign
+ repositories.
Valid options:
-r [--revision] ARG : ARG (some commands also take ARG1:ARG2 range)
@@ -279,6 +331,8 @@ Valid options:
'PREV' revision just before COMMITTED
-c [--change] ARG : the change made by revision ARG (like -r ARG-1:ARG)
If ARG is negative this is like -r ARG:ARG-1
+ If ARG is of the form ARG1-ARG2 then this is like
+ ARG1:ARG2, where ARG1 is inclusive
-N [--non-recursive] : obsolete; try --depth=files or --depth=immediates
--depth ARG : limit operation by depth ARG ('empty', 'files',
'immediates', or 'infinity')
@@ -305,9 +359,10 @@ Valid options:
Show C function name in diff output.
--ignore-ancestry : ignore ancestry when calculating merges
--accept ARG : specify automatic conflict resolution action
- ('postpone', 'base', 'mine-conflict',
+ ('postpone', 'working', 'base', 'mine-conflict',
'theirs-conflict', 'mine-full', 'theirs-full',
'edit', 'launch')
+ (shorthand: 'p', 'mc', 'tc', 'mf', 'tf', 'e', 'l')
--reintegrate : merge a branch back into its parent branch
--allow-mixed-revisions : Allow merge into mixed-revision working copy.
Use of this option is not recommended!