Stow Workflow

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

• Directorydotfiles/ public repo root

  • Directoryzsh/ stow package

    • .zshrc
  • Directoryneovim/ stow package

    • Directory.config

      • Directorynvim

        • init.lua
  • Directoryhypr/ stow package

    • Directory.config

      • Directoryhypr

        • …
  • Directoryghostty/ stow package

    • Directory.config

      • Directoryghostty

        • config
  • Directoryscripts/ stow package

    • Directory.local

      • Directorybin

        • dot
  • Directorydocs/ ignored by .stowrc

    • …
  • Directorydot/ ignored by .stowrc

    • …

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.

Apply stow packages

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 hypr/, ghostty/, herdr/, shell completions, .local/bin, and systemd user units. This keeps ~/.config/herdr/ local while stowing only config.toml, so logs, sockets, and session state never enter the repository. 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.
• 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.conf goes missing even briefly, Hyprland writes 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.conf 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.

Temporarily remove managed links

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.

Caution

The repo root stows to ~/. Anything not ignored in .stowrc becomes a symlink under your home directory. When adding new root-level files or directories that should not be stowed (such as docs/), add a matching --ignore rule.

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.