Clean action runtime project state
This commit is contained in:
@@ -1,102 +1,109 @@
|
||||
# Example working scenario
|
||||
# Example Dotfiles Repository
|
||||
|
||||
This folder contains a complete dotfiles + setup configuration for the current `flow` schema.
|
||||
|
||||
## What this example shows
|
||||
|
||||
- Flat repo-root layout with reserved dirs:
|
||||
- `_shared/` (shared configs)
|
||||
- profile dirs (`linux-auto/`, `macos-dev/`)
|
||||
- package-local `_root/` marker for root-targeted files
|
||||
- Unified YAML config under `_shared/flow/.config/flow/*.yaml`
|
||||
- Profile package list syntax: string, type prefix, and object entries
|
||||
- Binary install definition with `asset-pattern`, `platform-map`, `extract-dir`, and `install`
|
||||
- Required env vars, templating, SSH keygen, runcmd, post-link, and config skip patterns
|
||||
`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/flow/.config/flow/config.yaml`
|
||||
- `dotfiles-repo/_shared/flow/.config/flow/packages.yaml`
|
||||
- `dotfiles-repo/_shared/flow/.config/flow/profiles.yaml`
|
||||
- `dotfiles-repo/_shared/...`
|
||||
- `dotfiles-repo/linux-auto/...`
|
||||
- `dotfiles-repo/macos-dev/...`
|
||||
|
||||
## Quick start
|
||||
|
||||
Use the absolute path to this local example repo:
|
||||
|
||||
```bash
|
||||
EXAMPLE_REPO="/ABSOLUTE/PATH/TO/flow-cli/example/dotfiles-repo"
|
||||
```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
|
||||
```
|
||||
|
||||
Initialize and link dotfiles:
|
||||
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
|
||||
flow dotfiles init --repo "$EXAMPLE_REPO"
|
||||
flow dotfiles link --profile linux-auto
|
||||
flow dotfiles status
|
||||
flow dotfiles unlink # remove all managed symlinks
|
||||
flow dotfiles unlink git tmux # remove only specific packages
|
||||
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
|
||||
```
|
||||
|
||||
Manage the dotfiles and any module repos as a unified set:
|
||||
Run flow against that sandbox:
|
||||
|
||||
```bash
|
||||
flow dotfiles repos list
|
||||
flow dotfiles repos status
|
||||
flow dotfiles repos pull
|
||||
flow dotfiles repos push
|
||||
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
|
||||
```
|
||||
|
||||
Edit a package or a specific file under the dotfiles repo:
|
||||
`--skip system` avoids `_root/` paths such as `/etc/hostname` during the demo.
|
||||
|
||||
Useful follow-up commands:
|
||||
|
||||
```bash
|
||||
flow dotfiles edit git --no-commit
|
||||
flow dotfiles edit _shared/flow/.config/flow/profiles.yaml --no-commit
|
||||
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
|
||||
```
|
||||
|
||||
Inspect setup profiles and run a setup:
|
||||
Remove the sandbox when done:
|
||||
|
||||
```bash
|
||||
flow setup list
|
||||
flow setup show linux-auto
|
||||
flow setup run linux-auto \
|
||||
--var TARGET_HOSTNAME=devbox \
|
||||
--var USER_EMAIL=you@example.com \
|
||||
--dry-run
|
||||
flow setup run macos-dev --dry-run
|
||||
rm -rf "$DEMO"
|
||||
```
|
||||
|
||||
`bootstrap` and `provision` remain as aliases for `setup`, so `flow bootstrap run linux-auto` still works.
|
||||
## External Modules
|
||||
|
||||
Install or list packages directly (independent of a setup run):
|
||||
|
||||
```bash
|
||||
flow packages list
|
||||
flow packages list --all
|
||||
flow packages install --profile linux-auto --dry-run
|
||||
flow packages install fd ripgrep --dry-run
|
||||
flow packages remove docker --dry-run
|
||||
```
|
||||
|
||||
## External modules
|
||||
|
||||
A package directory inside the dotfiles repo can pull its contents from a separate
|
||||
git repository by placing a `_module.yaml` file at the package root. Flow clones
|
||||
the module into a shared cache and links from the cached path, so updates flow
|
||||
through `flow dotfiles repos pull`.
|
||||
|
||||
This example does NOT include a real `_module.yaml` (it would pin the example to
|
||||
a flaky external dependency). For reference, a hypothetical `nvim/_module.yaml`
|
||||
would look like:
|
||||
A package directory may mount a separate git repo by adding `_module.yaml` at
|
||||
the package root:
|
||||
|
||||
```yaml
|
||||
# example/dotfiles-repo/nvim/_module.yaml (not committed -- format reference only)
|
||||
source: github:your-org/nvim-config # or a full git URL
|
||||
source: github:your-org/nvim-config
|
||||
ref:
|
||||
branch: main # exactly one of: branch, tag, commit
|
||||
branch: main
|
||||
```
|
||||
|
||||
After adding such a file, the next `flow dotfiles repos pull` will clone the
|
||||
module and `flow dotfiles link --profile linux-auto` will link its contents.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user