# Example Dotfiles Repository

`example/dotfiles-repo` is a complete fixture for the current flow schema. It
contains shared dotfiles, profile-specific dotfiles, package definitions, setup
profiles, root-targeted files, templates, and shell hooks.

## Layout

```text
dotfiles-repo/
  _shared/
    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/init.lua
    system/_root/etc/hostname
    system/_root/usr/local/bin/custom-script.sh
    tmux/.tmux.conf
    zsh/.zshrc
  linux-auto/
    ssh/.ssh/config
  macos-dev/
    ghostty/.config/ghostty/config
```

The fixture demonstrates:

- `_shared/` plus profile-specific layers
- `_root/` absolute-path planning for sudo-backed links
- 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"
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
```

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 system --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 system
```

`--skip system` avoids `_root/` 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` at
the package root:

```yaml
source: github:your-org/nvim-config
ref:
  branch: main
```

This fixture does not include a real module because that would make the example
depend on an external network repo. After adding one, `flow dotfiles repos pull`
clones or updates the module cache, and `flow dotfiles link` links from that
cache.