.\" ==================================================================================
.\" portsreinstall-upgrade(8) manual page
.\" Copyright (C) 2018 Mamoru Sakaue, MwGhennndo, All Rights Reserved.
.\" ==================================================================================
.TH PORTSREINSTALL\-UPGRADE 8 "22 September 2018" "FreeBSD" "FreeBSD System Manager's Manual"
.SH NAME
portsreinstall\-upgrade \- Support utility for \fBportsreinstall\fR(8) to update a target environment using packages built in a builder environment
.SH SYNOPSIS
.B portsreinstall-upgrade
[
.I
OPTIONS
] [
.B
\-\-
] [
.I
command
]
.SH DESCRIPTION
This utility applies updates of packages to a target environment using packages built in a builder environment.
The executable file of this utility is installed outside the scope of the search paths, and dispatched from the builder environment to target environments by \fBportsreinstall packupgrade create\fR command followed by \fBportsreinstall packupgrade crop\fR command.
.SH ROBUSTNESS AGAINST TERMINATION AND RESTART
Execution of this utility can be terminated at any points and restarted from there with the same options saved in the temporary database (independent among utilities). The saved options can be changed by the ways depending on the assigned groups of the options. The options and execution progress are reset to the default by running with \fB\-R\fR option.
.SH ARGUMENTS
One of the following \fIcommands\fR can be given for optional operations or confirmation.
.TP
\fBdo\fR
(Default) Apply the update of packages.
.TP
\fBclean\fR
.PD 0
.TP
\fBclean [normal]\fR
Clean up the temporary database.
.TP
\fBclean force\fR
Attempt to clean up the temporary database without checking the lock and privilege.
.TP
\fBoptions\fR
Show saved option settings and expected effects of option-resetting options \fB\-M\fR.
With \fB\-a\fR option, the first, second and third columns denote the option-resetting options, reset options and remaining options, respectively.
.TP
.RE
.SH OPTIONS
If duplicated or conflicting ones are set, the last ones are effective.
The end of options can be explicitly specified by \fB\-\-\fR.
Short options can be given in compact forms, for example, \fB\-V \-a\fR to be \fB\-Va\fR.
.PD
.TP
\fB*NOTE*\fR
Option settings are loaded from the saved configuration (independent of \fBportsreinstall\fR(8)) unless explicitly reset by \fB\-M\fR option.
The saved options can be checked by \fBportsreinstall-upgrade options\fR command.
.PD
.SS Group 1: Just show messages and exit without operation
.IP \fB\-H\fR
.PD 0
.TP
\fB\-\-long\-help\fR
Show a long help whose content is the same as the manual page.
.PD
.IP \fB\-h\fR
.PD 0
.TP
\fB\-\-help\fR
.PD 0
.TP
\fB\-\-short\-help\fR
Show a short help.
.PD
.IP \fB\-V\fR
.PD 0
.TP
\fB\-\-show\-version\fR
Show the current version.
.PD
.SS Group 2: Effective anytime
.IP \fB\-a\fR
.PD 0
.TP
\fB\-\-batch\-mode\fR
Suppress messages so as to be friendly for batch operations.
Comments are suppressed as much as possible.
It is noted that log output in build/installation processes are not suppressed.
.PD
.IP \fB\-M\fR
.PD 0
.TP
\fB\-\-reset\-minor\-options\fR
Reset option settings for minor controls.
Option settings for group 4 are once reset and replaced with the newly specified ones.
Check the saved options by \fBportsreinstall options\fR command before specifying this option.
.PD
.IP \fB\-S\fR
.PD 0
.TP
\fB\-\-no\-opening\-message\fR
Suppress the credit, opening and terminating messages.
Option \fB\-a\fR takes higher priority over this option.
.PD
.SS Group 3: Saved and transferred to restarted runs, renewable by \-M option
Option settings in this group are saved at the first \fBdo\fR or \fBprepare\fR run, and transferred to the following runs.
Reset of the saved values for this group is available by appending \fB\-M\fR with newly specified options.
.IP \fB\-c\fR
.PD 0
.TP
\fB\-\-suppress\-cleaning\-obsolete\-database\fR
Suppress cleaning the temporary database even if its obsolete.
This option suppresses the default behavior that the temporary database is automatically cleaned up if it is older than the ports tree or portsreinstall itself is to be upgraded.
Use of this option may cause unexpected results and basically unrecommended.
.PD
.IP \fB\-n\fR
.PD 0
.TP
\fB\-\-dry\-run\fR
No operation is carried out (just for seeing what will be done).
This option is effective for \fBdo\fR command so that no deinstallation and (re)installation process is actually carried out.
By this option, ports/packages to be deinstalled or (re)installed can be confirmed without making changes to the current situation of packages.
.PD
.SS Group 4: Saved and not renewable until cleaning
.IP \fB\-P\fR
.PD 0
.TP
\fB\-\-packages\-dir\fR
Specifies the directory where packages created by the builder environment are located.
The default is ${PACKAGES}/${PKGREPOSITORYSUBDIR} by default (which is usually /usr/ports/packages/All).
.PD
.SH DETAILS
.SS Overview
This utility is a supporting tool of \fBportsreinstall\fR(8) to apply packages updates to a target environment using packages built by a builder environment using \fBportsreinstall packupgrade create\fR command followed by \fBportsreinstall packupgrade crop\fR command.
On-the-fly smart entire upgrade of all installed ports and robustness against termination/restart is pursued by this tool.
.PP
The update proceeds from the lowest level of the dependence hierarchy to the highest, where for each port the old version and conflicts are first deinstalled and then the new version is installed.
Obsolete and leaf ports are deinstalled at the final stage.
.PD
.SH "ENVIRONMENT VARIABLES"
See the corresponding section of \fBportsreinstall\fR(8).
The variables are conveyed to the forked environment from the target host.
.SH HISTORY
This utility first appeared as a part of \fBportsreinstall\fR(8) version 4.0.0 released on June 29, 2018.
.SH "SEE ALSO"
\fBportsreinstall\fR(8),
\fBportsreinstall\-chroot\fR(8),
\fBportsreinstall\-chroot\-mount\fR(8).
.SH COPYRIGHT
This software is distributed under the 2-Clause BSD License.
.PP
(C)\ 2018\ Mamoru\ Sakaue,\ MwGhennndo,\ All\ Rights\ Reserved.
.PP
Email:\ sakaue.mamoru@samurai.mwghennn.net
.PP
Homepage:\ http://www.mwghennndo.com/software/portsreinstall/