MERGE
Description
Merges a branch with another branch.
Usage
cm merge <source_spec> [--merge] [--cherrypicking] [--forced] [--mergetype=(onlyone|onlysrc|onlydst|try|forced)] [--interval-origin=<csetspec> | --ancestor=<csetspec>] [--keepsource | --ks] [--keepdestination | --kd] [--automaticresolution=<conflict-types>[;...]] [--subtractive] [--mount] [--printcontributors] [--noprintoperations] [--silent] [(--to=<brspec> | --destination=<brspec>)[--shelve]] [--no-dst-changes] [-c=<str_comment> | --commentsfile=<comments_file>] [--resolveconflict --conflict=<index> --resolutionoption=(src|dst|(rename --resolutioninfo=<strname>)) --mergeresultfile=<path> --solvedconflictsfile=<path>] [--nointeractiveresolution] [--machinereadable [--startlineseparator=<sep>] [--xml] [--encoding] [--endlineseparator=<sep>] [--fieldseparator=<sep>]]
Options
| Option / Argument | Description |
|---|---|
| --merge | Performs the merge. Otherwise, prints the conflicts found. |
| --cherrypicking | Merges the changes included on the source changesets. This option is not used if the merge source specification is a label. |
| --forced | Does not check if the source and destination are already connected. This option is only available for interval merge and cherry picking. |
| --mergetype | Type of the merge. See Remarks for more info. |
| --interval-origin | Specifies which changeset is chosen as the interval origin, so the merge will only take the differences between the source changeset and the specified interval origin. |
| --ancestor | This is an alias of '--interval-origin'. |
| --keepsource | Accepts all changes from source contributor for items with conflicts. |
| --keepdestination | Preserves changes from destination contributor for items with conflicts. |
| --automaticresolution | Used to resolve directory conflicts. This option lets you choose whether the source or the destination contributor should be automatically selected to resolve the conflict. Use a semicolon to separate conflict types. See Remarks for more info. |
| --subtractive | Deletes changes introduced by a merge. The parameter passed to the command (source_spec) is used to specify which is the source to delete changes. It must be a changeset. In the case of a changeset interval, the '--interval-origin' must be used to define the interval origin. To remove a change, the system creates a new checked out revision which will have the content of the previous one except for the deleted changes. |
| --mount | The mount point for the given repository. |
| --printcontributors | Prints the contributors (base, source, and destination). |
| --noprintoperations | Silently resolves merges without showing information about the resolution. |
| --silent | No output is shown unless an error happens. |
| --to | --destination | Performs a merge-to operation to the specified branch (by entering a branch spec or brspec) with full conflict resolution. (Use 'cm help objectspec' to learn more about branch specs.) A "merge-to" (or workspace-less merge) is a merge done in the server side. While normal merges happen on a workspace merging "from" a branch, label or changeset, a merge-to happens entirely on the server. While in normal merges the "destination" is the workspace, in "merge-to" a destination must be always specified (that's why we call it "to"). Check the following link for more information about the "merge to" feature: https://www.plasticscm.com/download/help/mergeto |
| --shelve | Creates a shelve with the changes of the merge result (plus merge traceability info) instead of creating a new changeset. This option is not available when the merge source is a shelve. This option is only available for server-side-merge (a.k.a. "merge-to"). Hence, the '--to' and '--merge' options are required. |
| --no-dst-changes | Ensures that the destination contributor doesn't have changes (the destination changeset is also the common ancestor). When there are changes on the destination, the merge is not allowed. |
| -c | Applies the specified comment to the changeset created in the merge operation. |
| --commentsfile | Applies the comment in the specified file to the changeset created in the merge operation. |
| --resolveconflict | (Mainly used by plugins. See Remarks for more info.) Used to solve a directory conflict. |
| --conflict | Used with the '--resolveconflict' flag, specifies the index of the conflict to solve starting at 1. |
| --resolutionoption | Used with the '--resolveconflict' flag, indicates the type of the conflict resolution. Use one of the following options: 'src', 'dst', 'rename'. See Remarks for more info. |
| --resolutioninfo | Used with the '--resolveconflict' flag, provides the name to use when the '--resolutionoption' option is 'rename'. |
| --mergeresultfile | Used with the '--resolveconflict' flag, outputs into a file the information of the merge result between different calls .The specified path will be created during the first call and updated on each next call. |
| --solvedconflictsfile | Used with the '--resolveconflict' flag, outputs into a file the information of the conflicts solved between different calls. The specified path will be created during the first call and updated on each next call. --nointeractiveresolution (Mainly used by plugins. See Remarks for more info.) Avoids prompting the user for manual conflict. This way, a directory conflict won't be solved. |
| --machinereadable | (Mainly used by plugins. See Remarks for more info.) Outputs the result in an easy-to-parse format. |
| --xml | Prints the output in XML format to the standard output. It is possible to specify an output file. This option cannot be combined with '--format' nor '--resolveconflict'. |
| --encoding | Used with the '--xml' option, specifies the encoding to use in the XML output, i.e.: utf-8. See the MSDN documentation at http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx to get the table of supported encodings and its format, (at the end of the page, in the "Name" column). |
| --startlineseparator | Used with the '--machinereadable' flag, specifies how the lines should start. (Default: empty string.) |
| --endlineseparator | Used with the '--machinereadable' flag, specifies how the lines should end. (Default: empty string.) |
| --fieldseparator | Used with the '--machinereadable' flag, specifies how the fields should be separated. (Default: whitespace.) |
| source_spec | Specification of the source object to merge from (See Remarks for more info.) |
Help
Remarks
This command is used to merge changes between two branches or between a label and a branch. The destination of the merge must be always a branch. The merge source is specified as an argument. Destination is the current content of the workspace. For example, to display the elements that will be merged from branch task001 to the main branch, the selector must point to the main branch, the workspace must be updated, and then:
cm merge br:/task001
To really perform the merge, '--merge' option is added
cm merge br:/task001 --merge
To define the merge source, the following specs can be used
- Branch specification (brspec):
- cm merge [br:/]br_name
- Example: cm merge br:/main/task001 (Merges from the last changeset on this branch.)
- Label specification (lbspec):
- cm merge lb:lb_name
- Example: cm merge lb:BL001 (Merges from the labeled changeset.)
- Changeset specification (csetspec):
- cm merge cs:cs_number
- Example: cm merge cs:25 (Merges from the given changeset content.)
- Shelve specification (shspec):
- cm merge sh:shelve_number
- Example: cm merge sh:2 (Merges from the given shelve content.)
To automatically resolve directory conflicts, use '--automaticresolution' option and specify the type of conflict followed by the contributor (source or destination) that must be selected during the merge operation. (Separate each "type of conflict"-"contributor" pair by a semicolon (;).) For example:
cm merge cs:2634 --merge --automaticresolution=eviltwin-src;changedelete-src
(The merge operation from changeset 2634 resolves the "eviltwin" and "changedelete" conflicts by keeping the source ("-src") contributor in both cases.)
- A "-src" suffix after a conflict type tells the merge command to keep the source contributor changes.
- A "-dst" suffix will keep the destination contributor changes.
This is the list of conflict types the merge command supports
- movedeviltwin
- eviltwin
- changedelete
- deletechange
- movedelete"
- deletemove
- loadedtwice
- addmove
- moveadd
- divergentmove
- cyclemove
- all
The "all" value overrides the other options. In the following example, "eviltwin-dst" will be ignored:
cm merge br:/main/task062 --merge --automaticresolution=all-src;eviltwin-dst
Check the following link to learn more about merge conflicts
https://www.plasticscm.com/download/help/directorymerges
These are the options for '--mergetype'
| Option / Argument | Description |
|---|---|
| onlyone | Automatic merge if only one contributor modified the item. |
| onlysrc | Automatic merge if only source contributor modified the item. |
| onlydst | Automatic merge if only destination contributor modified the item. |
| try | Automatic merge if only one contributor has modified the conflictive piece of code (each conflict). |
| forced | Always try to solve all non-automatic conflicts. |
These are the options that are mainly used by plugins and integrations
- '--resolveconflict' to solve a directory conflict. You also have to use the following options:
- '--conflict' is the index of the conflict that you want to solve, starting at 1.
- '--resolutionoption' indicates the conflict resolution to use. This can be:
- 'src' to keep the source change and discard the destination change
- 'dst' to keep the destination change and discard the source change
- 'rename' (only if the conflict type supports this resolution), to rename the destination to the given name provided with the '--resolutioninfo' option.
- '--resolutioninfo' to provide the name to use on a 'rename' resolution
- '--mergeresultfile' and '--solvedconflictsfile', both used to store the merge info between different calls.
- '--nointeractiveresolution' indicates the merge to not ask the user for manual conflict resolution.
- '--machinereadable' and '--startlineseparator', '--endlineseparator', '--fieldseparator' options to print the output on a machine-readable way (easier-to-parse).
Set the PLASTICEDITOR environment variable to specify an editor for entering comments. If the PLASTICEDITOR environment variable is set, and the comment is empty, the editor will be automatically launched to allow you to specify the comment.
Specification of the source
| Option / Argument | Description |
|---|---|
| Branch specification | '[br:/]br_name' |
| Label specification | 'lb:lb_name' |
| Changeset specification | 'cs:cs_number' |
| Shelve specification | 'sh:shelve_number' |
(Use 'cm help objectspec' to learn more about specs.)
Examples
cm merge br:/task001
(Does not merge, just prints items to be merged.)
cm merge br:/task001 --merge
(Does merge from branch 'task001'.)
cm merge cs:5 --merge --cherrypicking --interval-origin=cs:2
(Cherry pick from the changeset interval (2,5].)
cm merge cs:8 --merge --subtractive --keepdestination
(Subtractive merge from changeset 8, keeping destination changes for those elements with conflicts.)
cm merge br:/main/task001 --to=br:/main --merge -c="Integrated new UI"
(Does server-side merge, a.k.a. merge-to, from branch 'task001' to branch 'main' and sets a comment.)
cm merge br:/main/task001 --to=br:/main --merge --shelve
(Does server-side merge from branch 'task001' to branch 'main' and leaves the result on a shelve.)
cm merge sh:2 --to=br:/main --merge --no-dst-changes
(Applies the shelve 2 into 'main' only if it was created from the current 'main' head')
cm merge --machinereadable --startlineseparator=start@_@line --endlineseparator=new@_@line --fieldseparator=def#_#sep --mergeresultfile=C:\Users\Borja\AppData\Local\Temp\2tmp4D6C.tmp --solvedconflictsfile=C:\Users\Borja\AppData\Local\Temp\2tmp4D6D.tmp --resolveconflict --conflict=1 --resolutionoption=rename --resolutioninfo=bin_dst br:/main/task --merge
(Example for plugins and integrations)