NAME

mergesiteset — merge a siteXY.tgz set with OpenBSD installation sets

SYNOPSIS

DESCRIPTION

mergesiteset automates upgrades of custom siteXY.tgz files to a different release of OpenBSD. Files found in the siteXY.tgz set are merged with changes found in the official installation sets of the target OpenBSD release.

Root privileges are not required. Regardless, file permissions and ownership are preserved in the generated archive.

mergesiteset will attempt to download OpenBSD release sets and verify their integrity using signify(1). If sets and signatures are already present then the download step is skipped, and only verification is performed. The verification step requires corresponding signify(1) keys in /etc/signify.

Text files will be merged using a 3-way merge tool. For each text file found in siteXY.tgz, mergesiteset obtains three versions to perform this merge: The version of the file as it appeared in the OpenBSD release implied by the filename of siteXY.tgz, the version of the file as it appears in the target release of OpenBSD, and the version of the file as it appears in site.XY.tgz. These versions are provided as input to the 3-way merge tool.

Merge conflicts can be resolved in two ways, either via an interactive sdiff(1) menu or by editing files with conflict markers in a text editor. The interactive sdiff(1) menu is ideal for resolving conflicts in line-based configuration files. Editing files with conflict markers is ideal for merging scripts, program code, or files which contain paragraphs of text.

The options for mergesiteset are as follows:

-a architecture

Set the OpenBSD architecture for which installation sets will be fetched. Defaults to the OpenBSD architecture of the running system.

-d datadir

The directory where mergesiteset will persist files such as downloaded OpenBSD installation sets. This option overrides the MERGESITESET_DATADIR environment variable.

The default data directory is the current working directory.

-D droplist

Drop selected files from the merged site set. The droplist argument is the path to a file which lists files to drop, one per line. Lines in droplist must match the output of tar -ztf exactly in order to match.

-o outfile

Write the result to outfile. By default, the result will be written to siteXY.tgz where XY is a placeholder for the target OpenBSD release version.

-n

Disable interactive conflict resolution. Unless the -M option is used to script conflict resolution, files with merge conflicts will contain conflicts markers in the generated siteZY.tgz and must be edited before they can be used.

-M mergescript

Resolve merge conflicts non-interactively with a mergescript. This is useful when merges with known conflict cases need to be performed in an automated way.

It is recommended to perform the merge manually once and record the merge commands used to obtain the desired result, and then pass the merge commands used in interactive mode as a mergescript.

Instead of letting sdiff(1) prompt for merge commands interactively, the specified mergescript is pied into sdiff -o. Individual sdiff merge commands in the mergescript must be separated by hyphens and must not contain any whitespace. Supported sdiff(1) merge commands are:

l | 1

Choose left set of diffs.

r | 2

Choose right set of diffs.

bl | b1

Choose both, left set of diffs first.

br | b2

Choose both, right set of diffs first.

e

Start editing an empty file, which will be merged into outfile upon exiting the editor.

el

Start editing file with left set of diffs.

er

Start editing file with right set of diffs.

eb

Start editing file with both sets of diffs.

For non-interative use, commands which use an editor can be scripted with ed(1). See the EXAMPLES section.

When multiple files encounter merge conflicts, the -M option can be specified multiple times. Conflicted files will be merged with their correspdoning merge script in order of appearance.

-r version

Target the specified OpenBSD release version. By default mergesiteset attempts to target the next release of OpenBSD following the version implied by the provided siteXY.tgz. Mutually exclusive with the -s option. Equivalent to the -s option if the version “snapshot” is specified.

-s

Target the latest available OpenBSD snapshot instead of a release of OpenBSD. Mutually exclusive with the -r option.

-u upgrade-script

Add the specified upgrade-script file to the merged site set as upgrade.site(5), which will be run on the upgraded OpenBSD system during the final stages of the upgrade process.

-q

Quiet mode. Only display error messages.

EXAMPLES

Merge site76.tgz with files found in the OpenBSD 7.8 release:

The result will be written to site78.tgz.

Use a merge script to resolve a 3-chunk merge conflict in one file, by choosing first the old chunk version only (1), then the new chunk version only (2), and then use both, prepending the new version before the old version (b2):

Use ed(1) as a non-interactive editor for automated conflict resolution:

ENVIRONMENT

MERGESITESET_DATADIR

The directory where mergesiteset will persist files such as downloaded OpenBSD installation sets. This environment variable can be overridden with the -d option. The default data directory is the current working directory.

MERGESITESET_MIRROR

The OpenBSD mirror to fetch installation sets from. Defaults to https://cdn.openbsd.org/pub/OpenBSD. When downloading snapshots a non-CDN mirror will usually be faster. A complete list of available mirrors is at https://www.openbsd.org/ftp.html.

SEE ALSO

merge(1), sdiff(1), sysmerge(8)

AUTHORS

Stefan Sperling <stsp@openbsd.org>