.Dd February 14, 2016
.Dt SYSMERGE 8
.Os
.Sh NAME
.Nm sysmerge
.Nd upgrade current operating system from a sysroot
.Sh SYNOPSIS
.Nm sysmerge
.Op Fl cfpsw
.Op Fl t Ar target
.Op Fl \-booting
.Op Fl \-hook-finalize
.Op Fl \-hook-prepare
.Ar source
.Sh DESCRIPTION
.Nm
upgrades the current operating system by copying the system files from the
specified
.Ar source
directory (usually a sysroot) onto the current root filesystem.
This is meant to be used when building the operating system from source as
described in
.Xr development 7 .
.Pp
.Nm
installs the
.Sy system
manifest from the tix repository in the
.Ar source
directory, as well as all the ports found.
If a full upgrade is done, then all ports not found will be uninstalled.
Upgrade hooks will be run if further actions are needed to migrate the system to
the new version as described in
.Xr following-development 7 .
The
.Xr initrd 7
is regenerated using
.Xr update-initrd 8 .
If grub is enabled in
.Xr upgrade.conf 5 ,
then the bootloader is reinstalled and reconfigured as needed.
.Pp
.Nm
is an automatic and non-interactive upgrade.
It is meant to be used as part of the development process to upgrade to locally
built versions.
The
.Xr sysupgrade 8
program is by contrast an interactive program.
.Pp
The options are as follows:
.Bl -tag -width "12345678"
.It Fl \-booting
It's boot time, complete the system upgrade that was delayed.
This is meant to be used by
.Xr init 8
through the
.Sy merge
boot target.
This installs the
.Pa /sysmerge
directory onto the root filesystem and removes the
.Pa /sysmerge
directory.
.It Fl c , Fl \-cancel
Cancel a pending upgrade that would trigger on the next boot.
Remove the
.Pa /sysmerge
directory and restore the old
.Xr kernel 7
and
.Xr initrd 7 .
.It Fl f , Fl \-full
Full system upgrade that uninstalls ports not present in the
.Ar source
directory.
.It Fl \-hook-finalize
Run the post-upgrade hooks.
This is meant to be used by the old
.Nm
when it invokes the new
.Nm
during a non-waiting upgrade.
.It Fl \-hook-prepare
Run the pre-upgrade hooks.
This is meant to be used by the old
.Nm
when it invokes the new
.Nm
during a non-waiting upgrade.
.It Fl s , Fl \-system
Upgrade the system.
This option is implied unless
.Fl \-ports
is passed.
.It Fl t , Fl \-target Ns = Ns Ar target
Upgrade the installation in the
.Ar target
directory rather than the root filesystem.
This option is supported if the
.Pa target
is the
.Pa /
directory or only has ports installed and no system.
This option is unsupported if
.Ar target
has the system installed and is not the
.Pa / directory .
Instead one should
.Xr chroot 8
into the
.Pa target
and run the old
.Nm
inside rather than the new
.Nm .
However, this option may be useful for repairing installations and should work
in practice, however it is untested and might not properly handle incompatible
changes across releases.
.It Fl p , Fl \-ports
Upgrade the ports.
This option is implied unless
.Fl \-system
is passed.
.It Fl w , Fl \-wait
Wait until the next boot to complete the upgrade, rather than finishing it now.
The upgrade is installed into the
.Pa /sysmerge
directory instead, with the new kernel and initrd files in
.Pa /boot/sysmerge .
The new
.Xr kernel 7
has a new
.Xr initrd 7
that runs
.Sy /sysmerge/sbin/sysmerge --booting
on boot through the
.Sy chain-merge
.Xr init 8
boot target, which performs the operating system upgrade.
The bootloader configuration is regenerated with a menu option to perform
the upgrade if grub is enabled in
.Xr upgrade.conf 5 ,
otherwise the
.Pa /etc/default/grub.d/10_sortix.cache
bootloader fragment can be used to manually bootload the upgrade.
.El
.Sh FILES
.Bl -tag -width "/etc/default/grub.d/10_sortix.cache" -compact
.It Pa /boot/sortix.bin
Old system
.Xr kernel 7 .
.It Pa /boot/sortix.initrd
Old system
.Xr initrd 7 .
.It Pa /boot/sysmerge/
New system kernel and initrd files.
.It Pa /etc/default/grub.d/10_sortix.cache
GRUB configuration fragment that boots the new system.
.It Pa /etc/machine
Processor platform of this installation.
.It Pa /etc/sortix-release
The current system release.
.It Pa /etc/upgrade.conf
Controls the bootloader upgrade behavior (see
.Xr upgrade.conf 5 ) .
.It Pa /share/sysinstall/hooks/
A file per upgrade hook indicating that it doesn't need to be run.
.It Pa /sysmerge/
The pending systen upgrade is stored here.
.El
.Sh SEE ALSO
.Xr development 7 ,
.Xr initrd 7 ,
.Xr installation 7 ,
.Xr kernel 7 ,
.Xr upgrade 7 ,
.Xr sysinstall 8 ,
.Xr sysupgrade 8