pkg-pin(1)

NAME

pkg-pin, pkg-unpin - hold packages at a build, or release them

SYNOPSIS

pkg pin [NAME...]

pkg unpin NAME...

pkg unpin --all

DESCRIPTION

Sometimes you need a package to stay where it is. The new openssl breaks the one application you can't fix this week, or you're in the middle of debugging something and don't want it to move under you. pkg pin holds a package at the build that's installed right now, and pkg upgrade leaves it alone until you say otherwise.

pkg pin NAME writes the pin to /etc/pkg/pins.d/local.toml: the version and release, and the payload digest of every installed subpackage. There's no separate "hold" feature. A hold is just a pin at the installed build. See pkg-pins.d(5) for the file.

Where does a pin sit?

Above every repository. When pkg asks the chain which build of a name to use, the pin answers first, so the repositories never get a say.

What can't be pinned?

A package that isn't installed. A multi-installable one, since a pin names one build and there are several side by side. And one whose subpackages are at different builds: run pkg upgrade on it first, so there's one build to hold. A name another file already pins, such as a rollback's, is refused too, until that pin is released.

Pinning a name that's already in local.toml just replaces its pin with the installed build.

Listing and releasing

pkg pin with no names lists every local pin: the name, the pinned build, how that compares to what the repositories name, where it came from and which file holds it.

pkg unpin removes the pins of the names you give it, from whichever file holds them, and deletes a file it leaves empty. --all removes every pin.

Pinning or unpinning also cleans up a rollback's pins file whose rollback never committed. Listing doesn't touch anything.

A pin stays visible

A pin is how a machine stops getting fixes for a package while every command still succeeds. That's dangerous if nobody notices, so it's always reported. pkg-upgrade(1) and pkg-check-update(1) list every pinned package the repositories would move, as held by a pin, and check-update doesn't count it as an available update. pkg-list(1) shows pins.d as its repository.

Nothing walks past a pin

pkg install name=version, pkg upgrade --to, an offline or bundle upgrade, and a rollback all refuse to move a pinned package off its pin, and they name the file that pins it. --force doesn't override that. Release the pin first. That's the point of having one.

OPTIONS

--all: (unpin only.) Release every local pin. Can't be combined with names.

All global options apply, including --pins-dir; see pkg(1).

OUTPUT

pinned openssl at 3.5.1-2 (/etc/pkg/pins.d/local.toml)

The listing, one line per pin:

openssl 3.5.1-2 [Common has 3.5.1-4] pkg pin -- /etc/pkg/pins.d/local.toml

The bracket says how the pin compares to the chain: matches the chain, the repository and build it would otherwise get, no repo pins it, or chain not reachable when the repositories couldn't be read. The chain is read from cached metadata, as pkg-list(1) reads it, so the listing works offline and the comparison is as current as the last command that went online.

EXAMPLES

pkg pin openssl pkg pin pkg upgrade # openssl is reported as held by a pin pkg unpin openssl

EXIT STATUS

0 on success. 1 when a name can't be pinned for one of the reasons above, pkg unpin names a package that isn't pinned or gets neither a name nor --all, or a pins file can't be read or written.