|
1 ConE merge action |
|
2 ================= |
|
3 |
|
4 The merge functionality is meant to merge configurations/layers from a |
|
5 remote project (defined with -r) to the current project (defined with |
|
6 -p). Default value for the current project is the current working |
|
7 directory. A project can be either a folder or a CPF/ZIP file. |
|
8 |
|
9 There are two ways to use merge: |
|
10 |
|
11 #. Merge a configuration root into another |
|
12 #. Merge a specific source layer into a specific target layer |
|
13 |
|
14 These translate to two use cases: |
|
15 |
|
16 #. Merging an asset into an existing configuration project |
|
17 #. Merging a variant data layer from an exported CPF back into the |
|
18 configuration project |
|
19 |
|
20 Examples for these two use cases are given below. |
|
21 |
|
22 Examples |
|
23 -------- |
|
24 |
|
25 Files containing the used example data: |
|
26 |
|
27 - :download:`config_project.zip <merge/config_project.zip>` |
|
28 - :download:`myasset2.zip <merge/myasset2.zip>` |
|
29 |
|
30 Merging an asset into configuration project |
|
31 ''''''''''''''''''''''''''''''''''''''''''' |
|
32 |
|
33 Say that we have a small configuration project that contains the configuration |
|
34 interface and implementation of some component, and we want to merge this asset |
|
35 as part of a configuration project, specifically into the ``assets/myassets/`` |
|
36 layer in the project. This can be done by using the layer -> layer merging |
|
37 functionality. |
|
38 |
|
39 The image below shows what we want to accomplish. You can see that the |
|
40 ``assets/myassets/`` layer already contains asset1, and we want to merge asset2 |
|
41 there too. |
|
42 |
|
43 .. image:: merge/asset_merge.png |
|
44 |
|
45 We need to give ConE the layer root .confml files of the layers we want to |
|
46 merge. To do this, run the following command: |
|
47 |
|
48 :: |
|
49 |
|
50 > cone merge -p config_project --targetlayer assets/myassets/root.confml -r myasset2 --sourcelayer asset2/root.confml |
|
51 Running action merge |
|
52 Target project: config_project |
|
53 Source project: myasset2 |
|
54 Target layer: assets/myassets/root.confml |
|
55 Source layer: asset2/root.confml |
|
56 Merging layers... |
|
57 Copying asset2/confml/asset2.confml |
|
58 Copying asset2/content/asset2_data/dummy.txt |
|
59 Copying asset2/implml/asset2.templateml |
|
60 Including confml/asset2.confml in layer root assets/myassets/root.confml |
|
61 |
|
62 Now the ``assets/myassets`` layer in the configuration project contains also |
|
63 the contents of asset2. |
|
64 |
|
65 Merging a variant configuration into configuration project |
|
66 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''' |
|
67 |
|
68 Another use case is merging the variant data layer of an exported CPF back |
|
69 into the configuration project. This is where the configuration root merge |
|
70 comes in. |
|
71 |
|
72 First, using the same example project as in the previous example, export a CPF |
|
73 containing a variant data layer: |
|
74 |
|
75 :: |
|
76 |
|
77 > cd config_project |
|
78 config_project> cone export -c product_x_root.confml -r test.cpf --add variants/variant/root.confml |
|
79 Running action export |
|
80 Export product_x_root.confml to test.cpf done! |
|
81 |
|
82 Now the CPF can be modified somehow, here we'll add the content files ``foo.txt`` |
|
83 and ``bar.txt``. After this we can merge it back into the project as a new |
|
84 configuration root that contains also the variant data layer: |
|
85 |
|
86 :: |
|
87 |
|
88 config_project> cone merge -c foobar.confml -r test.cpf --rename |
|
89 Running action merge |
|
90 Target project: . |
|
91 Source project: test.cpf |
|
92 Target config: foobar.confml |
|
93 Source config: product_x_root.confml |
|
94 Merging 1 layer(s)... |
|
95 Merging variants/variant/root.confml -> variants/variant_foobar/root.confml |
|
96 Copying variants/variant/confml/data.confml |
|
97 Copying variants/variant/content/bar.txt |
|
98 Copying variants/variant/content/foo.txt |
|
99 Including confml/data.confml in layer root variants/variant_foobar/root.confml |
|
100 |
|
101 The rename option tells ConE to rename the variant layer based on the given |
|
102 configuration root name, so that the variant data layer becomes ``variants/variant_foobar/``. |
|
103 So, now the project looks like this: |
|
104 |
|
105 .. image:: merge/project_after_variant_layer_merge.png |
|
106 |
|
107 Note that the default merge doesn't overwrite the layers, it only adds/replaces |
|
108 files from the source layers. If the entire layer should be overwritten, the |
|
109 option --merge-policy can be used to specify that layers should be entirely |
|
110 overwritten. For example, if we remove ``foo.txt`` from the variant content |
|
111 in the CPF and re-merge like this: |
|
112 |
|
113 :: |
|
114 |
|
115 config_project> cone merge -c foobar.confml -r test.cpf --rename --merge-policy overwrite-layer |
|
116 Running action merge |
|
117 Target project: . |
|
118 Source project: test.cpf |
|
119 Target config: foobar.confml |
|
120 Source config: product_x_root.confml |
|
121 Merging 1 layer(s)... |
|
122 Merging variants/variant/root.confml -> variants/variant_foobar/root.confml |
|
123 Copying variants/variant/confml/data.confml |
|
124 Copying variants/variant/content/bar.txt |
|
125 Including confml/data.confml in layer root variants/variant_foobar/root.confml |
|
126 |
|
127 Now ``variants/variant_foobar/content/`` contains only ``bar.txt``. |
|
128 |
|
129 Options list |
|
130 ------------ |
|
131 -c CONFIG, --configuration=CONFIG |
|
132 defines the name of the target configuration for the |
|
133 action |
|
134 -p STORAGE, --project=STORAGE |
|
135 defines the location of current project. Default is |
|
136 the current working directory. |
|
137 -r STORAGE, --remote=STORAGE |
|
138 defines the location of remote storage |
|
139 -s CONFIG, --sourceconfiguration=CONFIG |
|
140 defines the name of the remote configuration inside |
|
141 the remote storage for the merge action. Default is |
|
142 the active root of the remote project. |
|
143 --sourcelayer=LAYER_ROOT |
|
144 Defines a specific layer to use as the layer to merge |
|
145 from the remote project. Must be the layer root |
|
146 (ConfML file).For example: --sourcelayer |
|
147 assets/somelayer/root.confml |
|
148 --targetlayer=LAYER_ROOT |
|
149 Defines a specific layer (root) to use as the layer to |
|
150 merge into the target project. Must be the layer root |
|
151 (ConfML file).For example: --targetlayer |
|
152 assets/somelayer/root.confml |
|
153 --rename defines that the merged layers need to be renamed |
|
154 --all Defines that the entire configuration (all layers) |
|
155 needs to be merged. This has no effect when merging |
|
156 layers directly using --sourcelayer and --targetlayer. |
|
157 -l LAYERS, --layer=LAYERS |
|
158 Define the layers of the source configuration that are |
|
159 included to merge action. The layer operation can be |
|
160 used several times in a single command. Note that this |
|
161 can only be used when merging configuration roots, not |
|
162 specific layers using --sourcelayer and --targetlayer. |
|
163 Example -l -1 --layer=-2, which would append a layers |
|
164 -1 and -2 to the layers => layers = -1,-2 |
|
165 --merge-policy=MERGE_POLICY |
|
166 Specifies the merge policy to use when merging layers. |
|
167 Possible values: |
|
168 replace-add - Add/replace files from source layer, but |
|
169 leave other files in the target as they are. |
|
170 overwrite-layer - Overwrite the entire layer (remove |
|
171 all previous content). |