Guide

Upgrading

ShedOS is a rolling release. Once installed, you never reinstall — shedman update pulls in new packages whenever you choose.

Your edited dotfiles stay safe. The system tracks which files it shipped and what you’ve changed, and never silently overwrites your edits.

The flow

Waybar shows a pending-updates badge when packages are waiting.
Click it, or run the updater in a terminal.
Confirm. Pacman (and yay, for AUR) prompt again with their own lists before anything is installed.
If any dotfiles need reconciling, you’ll be offered the review TUI.

Nothing destructive runs without an explicit y. Every upgrade interactively lists what it's about to do. While you review the pending lists, a stale mirrorlist (older than four hours) is re-ranked in the background and installed after you confirm; and when ShedOS's own packages changed — not just upstream ones — the run ends with a "ShedOS updated" summary and a notification linking the changelog.

How dotfile sync works

For each file ShedOS ships, three things are tracked: the pristine default (as installed), your live copy in $HOME, and a hash of the last version you were given. On upgrade, one of four actions runs per file:

Case	Condition	Action
seed	No `$HOME` copy	Copy the default in.
noop	Upstream unchanged	Nothing.
auto	You haven't edited the file	Back up, install the new default.
conflict	Both you and upstream changed it	Drop a sidecar file; your copy is untouched.

A file you edited is never overwritten. The only write to your live copy is the auto case, which requires a byte-for-byte match with the last-known version.

Resolving conflicts

After an upgrade with conflicts, the updater offers to launch a full-screen merge review:

Three-pane diff (YOURS · BASE · THEIRS) when a base snapshot is available; two-pane otherwise.
Per-hunk: take yours, take theirs, take both, skip, undo.
Whole-file: take all yours, take all theirs.
Atomic save: your file is backed up, the sidecar is removed, and the manifest advances. A crash mid-save can't corrupt the live file.

Single-sided hunks are pre-marked, so trivial conflicts collapse to a single keystroke.

Rolling back an upgrade

Every shedman update run brackets the upgrade with a pre- and post-snapshot of / (btrfs, via snapper). If an upgrade breaks something, restoring the pre-state is two commands:

shedman update --list-snapshots
shedman update --rollback <N>

Pick the pre-upgrade snapshot number from the list. A reboot applies the rollback. $HOME is intentionally not rolled back — your work since the upgrade is preserved. Run shedman rollback --undo before rebooting if you change your mind.

Before a risky change of your own, take a manual checkpoint: shedman snapshot <label>. Checkpoints list with shedman snapshot --list, appear in shedman upgrade-history, and restore through the same shedman rollback path.

And if a boot ever goes truly wrong — three consecutive boots that never reach the login screen — the system recovers itself: it boots a safe, writable copy of the newest snapshot automatically and a desktop notification explains what happened and how to make the recovery permanent.

Note Snapshots live on the same disk. For full data resilience, pair snapshots with an offsite backup (borg, restic, etc.).

Opting files out of dotfile sync

If you've customised a file and want ShedOS to stop tracking it entirely, add a matcher to ~/.config/shedos/sync-exclude:

install -Dm644 /usr/share/shedos/sync-exclude.example \
~/.config/shedos/sync-exclude

One glob per line, # for comments. Globs match against the path relative to $HOME:

.config/hypr/hyprland.conf   # keep my bindings — never drop a .shedosnew
.config/waybar/*             # opt an entire directory out

Excluded paths are never seeded, auto-updated, or flagged as conflicts. Any leftover state from before the exclude is auto-purged on the next shedman config —sync run. Your live file is never touched.

FAQ

Can I skip the config sync? Yes — answer N at the sync prompt. Packages stay upgraded; dotfiles are unchanged.

A config file has a .shedosnew sibling. What is it? That's the upstream version of a file you've edited. Open the merge review from the updater, or diff and reconcile it manually.

What if the rollback snapshot is missing? shedman update --list-snapshots shows everything snapper knows about. If the pre-snapshot was cleaned up or snapper was disabled, rollback isn't available for that upgrade — reinstalling affected packages from the ShedOS repo is the fallback.

← Getting started FAQ →