diff -r 000000000000 -r 2e8eeb919028 configurationengine/doc/cli/merge.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/configurationengine/doc/cli/merge.rst Thu Mar 11 17:04:37 2010 +0200 @@ -0,0 +1,171 @@ +ConE merge action +================= + +The merge functionality is meant to merge configurations/layers from a +remote project (defined with -r) to the current project (defined with +-p). Default value for the current project is the current working +directory. A project can be either a folder or a CPF/ZIP file. + +There are two ways to use merge: + + #. Merge a configuration root into another + #. Merge a specific source layer into a specific target layer + +These translate to two use cases: + + #. Merging an asset into an existing configuration project + #. Merging a variant data layer from an exported CPF back into the + configuration project + +Examples for these two use cases are given below. + +Examples +-------- + +Files containing the used example data: + + - :download:`config_project.zip ` + - :download:`myasset2.zip ` + +Merging an asset into configuration project +''''''''''''''''''''''''''''''''''''''''''' + +Say that we have a small configuration project that contains the configuration +interface and implementation of some component, and we want to merge this asset +as part of a configuration project, specifically into the ``assets/myassets/`` +layer in the project. This can be done by using the layer -> layer merging +functionality. + +The image below shows what we want to accomplish. You can see that the +``assets/myassets/`` layer already contains asset1, and we want to merge asset2 +there too. + + .. image:: merge/asset_merge.png + +We need to give ConE the layer root .confml files of the layers we want to +merge. To do this, run the following command: + +:: + + > cone merge -p config_project --targetlayer assets/myassets/root.confml -r myasset2 --sourcelayer asset2/root.confml + Running action merge + Target project: config_project + Source project: myasset2 + Target layer: assets/myassets/root.confml + Source layer: asset2/root.confml + Merging layers... + Copying asset2/confml/asset2.confml + Copying asset2/content/asset2_data/dummy.txt + Copying asset2/implml/asset2.templateml + Including confml/asset2.confml in layer root assets/myassets/root.confml + +Now the ``assets/myassets`` layer in the configuration project contains also +the contents of asset2. + +Merging a variant configuration into configuration project +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Another use case is merging the variant data layer of an exported CPF back +into the configuration project. This is where the configuration root merge +comes in. + +First, using the same example project as in the previous example, export a CPF +containing a variant data layer: + +:: + + > cd config_project + config_project> cone export -c product_x_root.confml -r test.cpf --add variants/variant/root.confml + Running action export + Export product_x_root.confml to test.cpf done! + +Now the CPF can be modified somehow, here we'll add the content files ``foo.txt`` +and ``bar.txt``. After this we can merge it back into the project as a new +configuration root that contains also the variant data layer: + +:: + + config_project> cone merge -c foobar.confml -r test.cpf --rename + Running action merge + Target project: . + Source project: test.cpf + Target config: foobar.confml + Source config: product_x_root.confml + Merging 1 layer(s)... + Merging variants/variant/root.confml -> variants/variant_foobar/root.confml + Copying variants/variant/confml/data.confml + Copying variants/variant/content/bar.txt + Copying variants/variant/content/foo.txt + Including confml/data.confml in layer root variants/variant_foobar/root.confml + +The rename option tells ConE to rename the variant layer based on the given +configuration root name, so that the variant data layer becomes ``variants/variant_foobar/``. +So, now the project looks like this: + + .. image:: merge/project_after_variant_layer_merge.png + +Note that the default merge doesn't overwrite the layers, it only adds/replaces +files from the source layers. If the entire layer should be overwritten, the +option --merge-policy can be used to specify that layers should be entirely +overwritten. For example, if we remove ``foo.txt`` from the variant content +in the CPF and re-merge like this: + +:: + + config_project> cone merge -c foobar.confml -r test.cpf --rename --merge-policy overwrite-layer + Running action merge + Target project: . + Source project: test.cpf + Target config: foobar.confml + Source config: product_x_root.confml + Merging 1 layer(s)... + Merging variants/variant/root.confml -> variants/variant_foobar/root.confml + Copying variants/variant/confml/data.confml + Copying variants/variant/content/bar.txt + Including confml/data.confml in layer root variants/variant_foobar/root.confml + +Now ``variants/variant_foobar/content/`` contains only ``bar.txt``. + +Options list +------------ + -c CONFIG, --configuration=CONFIG + defines the name of the target configuration for the + action + -p STORAGE, --project=STORAGE + defines the location of current project. Default is + the current working directory. + -r STORAGE, --remote=STORAGE + defines the location of remote storage + -s CONFIG, --sourceconfiguration=CONFIG + defines the name of the remote configuration inside + the remote storage for the merge action. Default is + the active root of the remote project. + --sourcelayer=LAYER_ROOT + Defines a specific layer to use as the layer to merge + from the remote project. Must be the layer root + (ConfML file).For example: --sourcelayer + assets/somelayer/root.confml + --targetlayer=LAYER_ROOT + Defines a specific layer (root) to use as the layer to + merge into the target project. Must be the layer root + (ConfML file).For example: --targetlayer + assets/somelayer/root.confml + --rename defines that the merged layers need to be renamed + --all Defines that the entire configuration (all layers) + needs to be merged. This has no effect when merging + layers directly using --sourcelayer and --targetlayer. + -l LAYERS, --layer=LAYERS + Define the layers of the source configuration that are + included to merge action. The layer operation can be + used several times in a single command. Note that this + can only be used when merging configuration roots, not + specific layers using --sourcelayer and --targetlayer. + Example -l -1 --layer=-2, which would append a layers + -1 and -2 to the layers => layers = -1,-2 + --merge-policy=MERGE_POLICY + Specifies the merge policy to use when merging layers. + Possible values: + replace-add - Add/replace files from source layer, but + leave other files in the target as they are. + overwrite-layer - Overwrite the entire layer (remove + all previous content).