# Flow Example

`example/` is a single complete fixture for the current flow schema. It contains
one dotfiles repository plus one local module repository, showcasing shared
dotfiles, profile-specific dotfiles, package definitions, setup profiles,
root-targeted files, external modules, templates, and shell hooks.

## Layout

```text
example/
  dotfiles-repo/
    _shared/
      _root/etc/hostname
      _root/usr/local/bin/custom-script.sh
      bin/.local/bin/flow-hello
      flow/.config/flow/config.yaml
      flow/.config/flow/packages.yaml
      flow/.config/flow/profiles.yaml
      git/.gitconfig
      nvim/.config/nvim/_module.yaml
      tmux/.tmux.conf
      zsh/.zshrc
    linux-auto/
      ssh/.ssh/config
    macos-dev/
      ghostty/.config/ghostty/config
  module-repos/
    nvim-config/
      init.lua
      lua/plugins.lua
```

The fixture demonstrates:

- `_shared/` plus profile-specific layers
- `_root/` absolute-path planning for sudo-backed links
- `_module.yaml` external module planning with a local module repository
- flow config and manifest overlay under `_shared/flow/.config/flow`
- package-manager, cask, and binary package definitions
- profile package shorthand and object overrides
- required env vars, templating, SSH key generation, `runcmd`, `post-link`, and
  config skip patterns

## Try It Safely

Use a temporary HOME/XDG sandbox so the example cannot touch your real dotfiles.
`dotfiles init` clones with git, so first copy the fixture into a temporary git
repo:

```bash
DEMO="$(mktemp -d)"
mkdir -p "$DEMO/home"
cp -a example/dotfiles-repo "$DEMO/dotfiles-src"
cp -a example/module-repos "$DEMO/module-repos"

git -C "$DEMO/module-repos/nvim-config" init -q -b main
git -C "$DEMO/module-repos/nvim-config" config user.email e2e@example.com
git -C "$DEMO/module-repos/nvim-config" config user.name "flow example"
git -C "$DEMO/module-repos/nvim-config" add -A
git -C "$DEMO/module-repos/nvim-config" commit -q -m initial

git -C "$DEMO/dotfiles-src" init -q -b main
git -C "$DEMO/dotfiles-src" config user.email e2e@example.com
git -C "$DEMO/dotfiles-src" config user.name "flow example"
git -C "$DEMO/dotfiles-src" add -A
git -C "$DEMO/dotfiles-src" commit -q -m initial

cd "$DEMO"
```

Run flow against that sandbox:

```bash
HOME="$DEMO/home" \
XDG_CONFIG_HOME="$DEMO/config" \
XDG_DATA_HOME="$DEMO/data" \
XDG_STATE_HOME="$DEMO/state" \
uv run flow dotfiles init --repo "$DEMO/dotfiles-src"

HOME="$DEMO/home" \
XDG_CONFIG_HOME="$DEMO/config" \
XDG_DATA_HOME="$DEMO/data" \
XDG_STATE_HOME="$DEMO/state" \
uv run flow dotfiles link --profile linux-auto --skip _root --dry-run

HOME="$DEMO/home" \
XDG_CONFIG_HOME="$DEMO/config" \
XDG_DATA_HOME="$DEMO/data" \
XDG_STATE_HOME="$DEMO/state" \
uv run flow dotfiles link --profile linux-auto --skip _root
```

`--skip _root` avoids root-targeted paths such as `/etc/hostname` during the demo.

Useful follow-up commands:

```bash
HOME="$DEMO/home" XDG_CONFIG_HOME="$DEMO/config" XDG_DATA_HOME="$DEMO/data" XDG_STATE_HOME="$DEMO/state" uv run flow dotfiles status
HOME="$DEMO/home" XDG_CONFIG_HOME="$DEMO/config" XDG_DATA_HOME="$DEMO/data" XDG_STATE_HOME="$DEMO/state" uv run flow dotfiles repos list
HOME="$DEMO/home" XDG_CONFIG_HOME="$DEMO/config" XDG_DATA_HOME="$DEMO/data" XDG_STATE_HOME="$DEMO/state" uv run flow setup list
HOME="$DEMO/home" XDG_CONFIG_HOME="$DEMO/config" XDG_DATA_HOME="$DEMO/data" XDG_STATE_HOME="$DEMO/state" uv run flow setup show linux-auto
HOME="$DEMO/home" XDG_CONFIG_HOME="$DEMO/config" XDG_DATA_HOME="$DEMO/data" XDG_STATE_HOME="$DEMO/state" uv run flow packages install --profile linux-auto --dry-run
```

Remove the sandbox when done:

```bash
rm -rf "$DEMO"
```

## External Modules

A package directory may mount a separate git repo by adding `_module.yaml`
under the desired mount path:

```yaml
source: module-repos/nvim-config
ref:
  branch: main
```

The example nvim package mounts `example/module-repos/nvim-config` at
`.config/nvim`. Flow implements modules through `_module.yaml`; it does not
implement a top-level `_modules/` dotfiles layout convention. `flow dotfiles
repos pull` clones or updates module caches, and `flow dotfiles link` links
from those caches.