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).