Stow Workflow

How dotfiles packages are applied into your home directory with GNU Stow.

The repository is a GNU Stow package root targeting ~/. Each top-level directory (zsh, neovim, starship, uwsm, hypr, ghostty, scripts, …) is a stow package whose contents are symlinked into your home directory.

Always use dot stow

Apply packages with dot stow (or dot update, which refreshes stow). Do not run GNU stow directly from the repo root: dot applies the correct backup, no-folding, and public-then-private flow. The first-use dot install and dot init commands add the adopt step; dot stow is the steady-state relink.

dot stow            # stow public + private
dot stow --public   # public only
dot stow --private  # private only

What dot stow does

• Lays down public packages first, then the private overlay from ~/.config/dotfiles-private.
• Stows any package that targets runtime-owned directories with --no-folding, including uwsm/, hypr/, ghostty/, herdr/, shell completions, .local/bin, and systemd user units. This keeps generated UWSM migration files and Herdr runtime state out of the source directories. For Hypr it also creates/repairs the ~/.config/hypr/host symlink for the active host.
• Before stow, moves unmanaged real files or directories that block active package targets into the repo’s backup/ directory and logs each source-to-backup path. This includes host-specific packages such as chromium--laptop. It does not follow an unmanaged parent symlink into an external tree; those conflicts are left for manual resolution.
• Before public stow, backs up the retired timmo001/omarchy-ghostty clone at ~/.config/ghostty when present, so the ghostty/ package can own that path.
• Before public stow, removes the retired timmo001/omarchy-uwsm checkout, including Quattro’s generated migration files, then links only the intentional 90-dotfiles override.
• During dot install and dot init, public packages use --adopt, but a committed-wins pre-pass first backs up differing live files so stock config cannot silently overwrite committed public files. Any remaining adopted changes are reported for review. Private packages use normal stow without --adopt.

Hypr package handling

The Hypr package is treated differently from every other stow package.

Hyprland enables config autoreload by default. If ~/.config/hypr/hyprland.lua goes missing even briefly, Hyprland can write a default stub as a real file. That stub then blocks the next stow because stow cannot replace a regular file with a symlink.

To avoid that gap, the steady-state dot stow flow and the install flow used by dot install and dot init never unstow the hypr package. Before stowing Hypr, they atomically repair ~/.config/hypr/hyprland.lua when the link is missing or points at the wrong target: the link is created through a temporary path and renamed into place, so Hyprland never sees a missing file. The idempotent stow step then fills in any other missing Hypr files without an unstow/restow cycle.

After the Hypr package is laid down, dot stow also creates or repairs the ~/.config/hypr/host symlink for the active OMARCHY_HOST. See Host Overrides for how host overrides are selected.

Unstowing packages

Use dot clean when you need to remove the symlinks that dot stow manages, for example before inspecting a conflict or proving whether a file is coming from the dotfiles repo.

dot clean   # unstow private packages first, then public packages
dot stow    # reapply the managed symlinks afterwards

dot clean discovers stow packages the same way dot stow does: top-level package directories only, excluding repo internals such as dot/, docs/, and backup/. Host-specific packages (name--host) are included only when their suffix matches the resolved Omarchy host, from OMARCHY_HOST or the current ~/.config/hypr/host link. If the private overlay is available, it is unstowed before the public repo so overlay links are removed before the base packages.

The command removes managed Stow links; it is not a general home-directory cleanup tool. Re-run dot stow or dot update after a clean to restore the expected links and host repairs.

Ignore rules

.stowrc sets the stow target and ignore rules. Files that should never be symlinked into ~/ are ignored there, including top-level docs, the dot/ source, the docs/ site, and repo metadata. Keep .stowrc ignore rules in sync when adding root-only files.

Health check

dot doctor runs a dry-run restow to detect drift, alongside its other checks. Run it after changing stow packages to confirm nothing is broken.