# Example working scenario

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

## 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"
```

Initialize and link dotfiles:

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

Manage the dotfiles and any module repos as a unified set:

```bash
flow dotfiles repos list
flow dotfiles repos status
flow dotfiles repos pull
flow dotfiles repos push
```

Edit a package or a specific file under the dotfiles repo:

```bash
flow dotfiles edit git --no-commit
flow dotfiles edit _shared/flow/.config/flow/profiles.yaml --no-commit
```

Inspect setup profiles and run a setup:

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

`bootstrap` and `provision` remain as aliases for `setup`, so `flow bootstrap run linux-auto` still works.

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:

```yaml
# example/dotfiles-repo/nvim/_module.yaml  (not committed -- format reference only)
source: github:your-org/nvim-config       # or a full git URL
ref:
  branch: main                            # exactly one of: branch, tag, commit
```

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.