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

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:

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:

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:

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:

rm -rf "$DEMO"

External Modules

A package directory may mount a separate git repo by adding _module.yaml at the package root:

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.