Skip to content

docs: document path normalization and workspace-root escape error #48

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
raphaelvigee merged 1 commit into from
Jun 25, 2026
Merged

docs: document path normalization and workspace-root escape error #48

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
5 changes: 4 additions & 1 deletion website/docs/plugins/buildfile.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,10 @@ target(
```

By default paths are resolved relative to the BUILD file's package; pass
`abs = True` to resolve from the workspace root instead.
`abs = True` to resolve from the workspace root instead. Paths are lexically
normalized — `./` prefixes and empty segments are collapsed, `..` components
resolve against the package path, and a path whose `..` segments escape the
workspace root is an error.

### `target()` — what buildfile reads, and what it forwards

Expand Down
6 changes: 5 additions & 1 deletion website/docs/plugins/exec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,10 @@ target(
`support_files` declares files a target produces that are **not** outputs — kept
in the sandbox for the command's own use but not published to dependents.

Output and support-file paths are lexically normalized: `./` prefixes and empty
segments are stripped, `..` resolves against the package path, and a path that
escapes the workspace root is an error.

## Environment passthrough

`pass_env` and `runtime_pass_env` each accept a list of variable names to
Expand Down Expand Up @@ -207,7 +211,7 @@ target(
`cache` accepts a bare bool or a dict with up to three keys:

| Key | Type | Default | Meaning |
|-----|------|---------|---------|
|-----|------|---------|--------|
| `enabled` | bool | `true` | Enable local caching for this target. |
| `remote` | bool | `true` | Enable remote caching for this target. Set `false` when outputs embed host-local paths that cannot be safely shared across machines. |
| `history` | int | `1` | Number of past revisions to retain in the local cache (minimum `1`). |
Expand Down
Loading