Guide

Upgrading

Rolling updates, dotfile merges, and conflict review.

ShedOS is a rolling release. Once installed, you never reinstall — updates flow from the ShedOS repository through pacman -Syu.

What sets the upgrade apart: your dotfiles are safe. The system tracks which files it shipped and what you’ve edited, and it never silently overwrites your changes.

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.

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.

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 (manifest hash, base snapshot, .shedosnew sidecar) 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 (retention policy) or snapper was disabled, rollback isn’t available for that upgrade — reinstalling affected packages from the ShedOS repo is the fallback.