Sitecore package installation options explained

28 November 2012 at 00:00 by Martijn van der Put - Post a comment

A lot of times there is some ignorance with developers about the possible package installation options. This also included myself. Sort of like an old habit I always use the "overwrite" option for data templates and layouts and the merge-clear option for content-items.

Looking at the description that is shown in the popup dialog during package installation, got me confused about the difference between the options and sub-options.

The descriptions of the installation options in the package installation wizard says:

Overwrite  Replace the entire subtree with the subtree in the package 
Merge - Clear Leave the subtree and replace any matching items and versions with those from the package but do not replace any subitems.
Merge - Append Leave the subtree. Overwrite nothing. Append any matching items to the existing subtree by giving them incremental numbers.
Merge - Overwrite Leave the subtree and replace any matching items and versions with those from the package. 
Skip Take no action and move on to the next item.

Looking at these descriptions, the Overwrite and Skip seem obvious although the description could be a bit better. But what about the merge-clear, merge-append and merge-overwrite? Those got me really confused.

The correct description of what each option does should be something like this:

Overwrite  Items with the same ID (along with it's descendants) will be removed and replaced by items from the package. 
Skip Items with the same ID from the target database will remain unchanged; the item from the package will be skipped.
Merge - Clear all existing versions for a language of the item being installed are removed prior to adding new versions. This options 'clears out' the versions of the language and creates one new version.
Merge - Append item versions from the package are added 'on-top' of the existing versions of the item. This preserves history, but numbers the package versions with numbers higher than the existing version numbers. A user can merge information between versions afterwards.
Merge - Merge if there is a version with the same number in the item, the Installation Wizard will overwrite it, otherwise a new version with the specific number is added. This makes it possible to replace specific versions of items.

As you can see, the Merge-options doesn't remove items, but instead, merges versions of an item.

The Merge-Append option could be useful when updating content from a testing or acceptance environment to a production environment (or vice versa) where the customer has already started creating content without losing any of the previous content.