From: Stuart Henderson <stu@spacehopper.org>
Subject: Re: pkg_add.1: improve clarity for -U
To: tech@openbsd.org
Date: Fri, 2 May 2025 10:28:47 +0100

On 2025/05/01 21:56, Josh Grosse wrote:
> For consideration.

> diff --git usr.sbin/pkg_add/pkg_add.1 usr.sbin/pkg_add/pkg_add.1
> index 67be4b80179..17b3fc12687 100644
> --- usr.sbin/pkg_add/pkg_add.1
> +++ usr.sbin/pkg_add/pkg_add.1
> @@ -109,7 +109,9 @@ with
>  .Fl u
>  whenever possible, but
>  .Fl U
> -can be much faster.
> +can be much faster, and is intended for use when running -current, if
> +a new package needs to be added without conducting a full update of all
> +packages.
>  .It
>  Replace existing packages with explicit other versions, using option
>  .Fl r .

-U is a bit of a hack and I think mostly useful for ports developers.

Diff below gives a better reason *not* to use it.

Perhaps pkg_add should reject -Uu, afaict it is meaningless, and there
is some meme which won't go away about running -Uu for updates.

Bonus -u -> .Fl u fix.

Index: pkg_add.1
===================================================================
RCS file: /cvs/src/usr.sbin/pkg_add/pkg_add.1,v
diff -u -p -r1.168 pkg_add.1
--- pkg_add.1	2 Oct 2024 09:14:08 -0000	1.168
+++ pkg_add.1	2 May 2025 09:24:00 -0000
@@ -104,12 +104,14 @@ The
 .Ar pkg-name ...
 specified on the command line are new packages that may require updating
 dependencies first.
-It is recommended to keep all packages in-synch
+It is recommended to update all packages
 with
 .Fl u
-whenever possible, but
+before installing a new package, but
 .Fl U
-can be much faster.
+can be much faster (at the risk of possibly leaving an inconsistent
+set of packages).
+Mainly for use with -current snapshots.
 .It
 Replace existing packages with explicit other versions, using option
 .Fl r .
@@ -685,7 +687,9 @@ Dependencies from the old packages are a
 package.
 .El
 .Pp
-To update packages in -u mode,
+To update packages in
+.Fl u
+mode,
 .Nm
 performs the following steps.
 .Bl -enum