Explanation

When upgrading an XWiki distribution using the ZIP package on a Unix system, the configuration files must be merged, not simply overwritten, in order to preserve custom settings while integrating new options introduced by the newer version. The following commands illustrate examples of how to move, compare, and merge the configuration files using standard Unix tools.

Assumption

We assume xwiki.new is a symbolic link pointing to the directory where the new XWiki version is installed, and xwiki is the directory of the previous XWiki installation.

Move and Back Up Files

Each configuration file (web.xml, xwiki.cfg, xwiki.properties, struts-config.xml, logback.xml) from the new XWiki installation (xwiki.new) is first moved to a backup copy with the .ori extension.

Compare and Merge Files with sdiff

The sdiff command can then be used to compare:

• the configuration file from the old installation (xwiki/WEB-INF/), 
• the corresponding backup file from the new installation (xwiki.new/WEB-INF/*.ori).

The merged result is written back into the new installation directory.

mv xwiki.new/WEB-INF/web.xml xwiki.new/WEB-INF/web.xml.ori
sudo sdiff xwiki/WEB-INF/web.xml xwiki.new/WEB-INF/web.xml.ori -B -W -E -o xwiki.new/WEB-INF/web.xml

mv xwiki.new/WEB-INF/xwiki.cfg xwiki.new/WEB-INF/xwiki.cfg.ori
sudo sdiff xwiki/WEB-INF/xwiki.cfg xwiki.new/WEB-INF/xwiki.cfg.ori -B -W -E -o xwiki.new/WEB-INF/xwiki.cfg

mv xwiki.new/WEB-INF/xwiki.properties xwiki.new/WEB-INF/xwiki.properties.ori
sudo sdiff xwiki/WEB-INF/xwiki.properties xwiki.new/WEB-INF/xwiki.properties.ori -B -W -E -o xwiki.new/WEB-INF/xwiki.properties

mv xwiki.new/WEB-INF/struts-config.xml xwiki.new/WEB-INF/struts-config.xml.ori
sudo sdiff xwiki/WEB-INF/struts-config.xml xwiki.new/WEB-INF/struts-config.xml.ori -B -W -E -o xwiki.new/WEB-INF/struts-config.xml

mv xwiki.new/WEB-INF/classes/logback.xml xwiki.new/WEB-INF/classes/logback.xml.ori
sudo sdiff xwiki/WEB-INF/classes/logback.xml xwiki.new/WEB-INF/classes/logback.xml.ori -B -W -E -o xwiki.new/WEB-INF/classes/logback.xml