pkg-history(1)

NAME

pkg-history - list the transactions this machine committed, or show one

SYNOPSIS

pkg history [--package NAME] [-n N]

pkg history info N

pkg history export N [--output PATH]

DESCRIPTION

Something broke after yesterday's upgrade. What changed? That's the question this command answers.

Every transaction that changes the installed set or the selection roots gets a number. pkg stores a record of what it changed, and a snapshot of what was installed afterwards, under /var/lib/pkg/history/. The same number starts its line in /var/log/pkg.log, so you can find it there too. pkg history reads those records. It only reads, so it needs no privileges.

A transaction that changes nothing doesn't get a number. Reinstalling the build that's already installed isn't a change.

COMMANDS

pkg history

Lists transactions, newest first. Each row has the number, the time (UTC), the kind, the user, a summary of what changed, and the command as it was typed. The user is the sudo caller, when there was one.

The kind is the subcommand that made the transaction:

install, remove, autoremove, upgrade, upgrade-to, rollback: the command of the same name.
bundle-install, offline-apply: pkg bundle install and pkg offline upgrade, which apply a bundle; see pkg-bundle(1) and pkg-offline(1).
roots: a change to the selection roots that changed no package.
compose: the transactions a composed image was built from.
apply: a caller that didn't say.

What does the ! mean?

A number marked ! follows a change made outside pkg: the installed set that transaction started from isn't the one the previous transaction left behind. Something else touched the store in between. And if the installed set right now isn't what the newest transaction left, you get a warning on stderr saying so.

pkg history info N

One transaction, in full. The command, the user, both state digests, and every subpackage it installed (+), replaced (~) or removed (-), with the label and payload digest on each side. Then the roots it added and dropped and, for a rollback, its target and the pins it wrote.

It also tells you when the snapshot after it has been pruned. A rollback onto that transaction then has to be worked out from a later snapshot.

pkg history export N

Writes the installed set right after transaction N as a pins file, the same format pkg offline export-pins writes. You can feed it to pkg upgrade --to to put a machine back in that state, or to pkg offline bundle-create to build a bundle for it.

OPTIONS

--package NAME: Only transactions that installed, replaced or removed a subpackage of NAME, or added or dropped it as a root.
-n, --limit N: At most N transactions.
--output PATH: (export) Where to write. A directory, or a path ending in /, gets <hostname>.history-N.pins.toml. Anything else is used as the file name. Defaults to the current directory.

All global options apply; see pkg(1).

RETENTION

How far back does it go?

[history] in pkg.toml(5) sets how many records and snapshots are kept: 1000 records and 50 snapshots by default. Whatever gets pruned can no longer be rolled back to. The newest is always kept.

JSON

{ "ok": true, "kind": "history", "records": [ ... ], "breaks": [ <N>, ... ], "drift_since": <N> | null }

breaks are the ! transactions. drift_since names the newest one when the installed set has changed outside pkg since.

info prints "kind": "history-record" with the record as stored, plus snapshot_retained and break_before. export prints "kind": "history-export" with the path it wrote and a subpkgs count. See pkg-cli/JSON.md for the record's fields.

EXAMPLES

The last ten things that happened

pkg history -n 10

Everything that ever touched openssl

pkg history --package openssl

What did #48 actually do?

pkg history info 48 grep ' #48 ' /var/log/pkg.log

Saving the state after #47 for later

pkg history export 47 --output /root/

EXIT STATUS

0 on success. 1 when the installed state or its history can't be read, or when N names a transaction that isn't recorded. export also fails when the state after N can no longer be rebuilt from what retention kept.