Advanced Rollback Guide

Zoi includes a robust rollback system designed to recover from failed installations or problematic updates. This guide explains the underlying transaction mechanism and provides details on what can and cannot be rolled back.

How Transactions Work

Every operation that modifies your Zoi installation (install, uninstall, upgrade) is wrapped in a transaction.

1. Transaction Begin: Zoi generates a unique ID and creates a temporary log in ~/.zoi/pkgs/transactions/.
2. Recording Operations: Each individual file change, symlink creation, and registry update is recorded in the transaction log.
3. Atomic Commits: If all steps in the operation succeed, the transaction is marked as committed.
4. Rollback on Failure: If any step fails, Zoi automatically attempts to revert all changes recorded in the current transaction.

The Last Transaction

You can manually revert the most recent successful operation using the --last-transaction flag:

zoi rollback --last-transaction

Rollback Types

1. Zoi-Native Packages

For packages installed directly by Zoi, rollbacks are highly reliable. Zoi keeps the previous version's directory in the store (if rollback_enabled is true in config.yaml). Rolling back simply swaps the latest symlink and re-links the binaries.

2. Multi-Registry Rollbacks

If an update involves moving a package between different registries or tiers, Zoi tracks the origin handle to ensure it can point back to the correct source during a rollback.

Limitations and Caveats

While Zoi strives for reliable recovery, there are inherent limitations, particularly regarding external tools.

Native Dependency Limitations

Zoi can install dependencies via over 40 external package managers (APT, Homebrew, Cargo, etc.). However, Zoi cannot guarantee rollbacks for these native dependencies.

• No Snapshotting: Zoi does not snapshot your entire OS. If apt install upgrades a system library, Zoi cannot "undo" that library upgrade.
• Dependency Persistence: If a native package manager is used to fulfill a dependency, Zoi will attempt to uninstall it during a rollback if it was newly added, but it won't revert it to a previous version if it was merely upgraded.
• Side Effects: Scripts run in post_install or pre_upgrade hooks might perform actions (like starting a service or creating a database) that Zoi doesn't know how to reverse automatically.

Manual Cleanup

In rare cases where a transaction log is corrupted (e.g. a power loss during the rollback itself), you may need to use zoi doctor to identify broken symlinks or inconsistent records.

Configuration

You can control rollback behavior in your config.yaml:

# Keep previous versions for rollbacks (default: true)
rollback_enabled: true

If disabled, Zoi will delete old versions immediately to save space, making zoi rollback <package> impossible.