--- /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 <merge/config_project.zip>`
+ - :download:`myasset2.zip <merge/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).