Skip to content

docs(skill): document clean-git requirement and /tmp filter gotchas #61

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
christophergeyer merged 1 commit into from
Apr 17, 2026
Merged

docs(skill): document clean-git requirement and /tmp filter gotchas #61

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions roar/cli/templates/agents/SKILL.md.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,9 @@ Workloads should NOT need to know which backend is active.

## Gotchas

- **Clean git state is required.** `roar run` refuses to execute if the git working tree has uncommitted changes — including untracked files. There's no `--dirty` bypass; commit (or stash, or gitignore) first. Lineage ties to a commit, so this is by design.
- **Add `.roar/` to `.gitignore` before your first run.** Otherwise it becomes an untracked change that trips the clean-tree check above on the next run. `roar init` prompts to add it; say yes. If you run `roar init -n` (skip) you'll need to add it yourself.
- **Default config filters `/tmp`.** `ignore_tmp_files = true` in the generated `config.toml` silently drops any I/O under `/tmp`. If a run shows `in:0 out:0` or a missing `Inputs/Outputs` section and you're working under `/tmp`, that's why — move the workdir or edit `.roar/config.toml` to flip the filter. Other default filters hide system reads (`/sys`, `/etc`) and installed-package reads.
- **Ray workers**: `ROAR_WRAP=1` is set on the driver but NOT on Ray workers. `ROAR_SESSION_ID` and `ROAR_JOB_ID` are propagated. Use those if a worker needs to detect provenance context.
- **Osmo workers**: no env var propagation today.
- **Don't make user code import roar** for tracking purposes — capture is transparent. The only exception is `from roar import require` for the abort-if-not-tracked guard.
Expand Down
2 changes: 2 additions & 0 deletions roar/cli/templates/agents/agents_section.md.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ This project uses [roar](https://github.com/treqs/roar) to capture lineage for M

- **Run scripts with provenance:** prefer `roar run <cmd>` over bare `<cmd>` (e.g. `roar run python train.py`).
- **Don't modify code to use roar.** Capture is transparent. The exception: `from roar import require` at the top of a script aborts if it isn't being run under `roar run`.
- **Clean git state is required.** `roar run` refuses to execute with uncommitted changes (including untracked files). No `--dirty` bypass. Make sure `.roar/` is in `.gitignore`.
- **Avoid `/tmp` for workdirs.** Default config has `ignore_tmp_files = true`, which silently drops I/O under `/tmp` — a run there will show `in:0 out:0`.
- **Inspect lineage:** `roar show <ref>`, `roar log`, `roar dag`. Add `--all` to `roar show` to disable truncation.
- **Don't commit `.roar/`** — it's local lineage state.
- **`roar --help` is the source of truth** for current command behavior.
Loading