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

Downgrading to Specific Versions

While rollback is useful for quickly undoing the very last action, you may sometimes need to return to a much older version of a package. For this, Zoi provides the zoi downgrade command.

zoi downgrade <package>

This command initiates an interactive process:

1. Version Discovery: Zoi scans your local installation store, your archive cache, and the registry metadata to find every version of the package that has ever been on your system.
2. Interactive Selection: You are presented with a list of discovered versions (newest first).
3. Clean Installation: Once you select a version, Zoi performs a fresh, dependency-aware installation of that specific version.

Use downgrade when a simple rollback isn't enough, or if you need to jump back multiple versions at once.

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.