110 lines
3.4 KiB
Markdown
110 lines
3.4 KiB
Markdown
# 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.
|