---
title: Stow Workflow
description: How dotfiles packages are applied into your home directory with GNU Stow.
sidebar:
  order: 3
---

The repository is a [GNU Stow](https://www.gnu.org/software/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.

<FileTree>

- **dotfiles/** public repo root
  - **zsh/** stow package
    - .zshrc
  - **neovim/** stow package
    - .config
      - nvim
        - init.lua
  - **hypr/** stow package
    - .config
      - hypr
        - ...
  - **uwsm/** stow package
    - .config
      - uwsm
        - env.d
          - 90-dotfiles
  - **ghostty/** stow package
    - .config
      - ghostty
        - config
  - **scripts/** stow package
    - .local
      - bin
        - dot
  - docs/ ignored by `.stowrc`
  - dot/ ignored by `.stowrc`

</FileTree>

## 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.

```bash title="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 `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](/omarchy/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.

```bash title="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.