Skip to content

docs: generate reports a tree, and --list is the per-file form #30

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
Kinflou merged 1 commit into from
Oct 13, 2026
Merged

docs: generate reports a tree, and --list is the per-file form #30

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
22 changes: 21 additions & 1 deletion docs/docs/guide/codegen/generating-code.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ idiomatic output for a past schema shape.
## Running it

```
comline generate [--target <lang>] [--out <dir>] [--layout <tpl>] [--mode <m>] [--watch]
comline generate [--target <lang>] [--out <dir>] [--layout <tpl>] [--mode <m>] [--dry-run] [--list] [--watch]
```

`generate` validates the project and writes the code. Unlike `comline build` it
Expand All @@ -148,9 +148,29 @@ repeatedly and from CI.
comline generate # every configured target, per comline.toml
comline generate --target rust # just rust
comline generate --target rust --out ./bind # override this target's output root
comline generate --dry-run # report without writing anything
comline generate --watch # regenerate on schema / config change
```

Each target's files are reported as a tree:

```
⚙️ language: typescript, version: 5.0, mode: lib
generated/typescript/
├─ package.json
├─ src/
│ ├─ index.ts
│ ├─ std/
│ │ └─ http.ts
│ └─ types.ts
└─ tsconfig.json
```

`--list` prints one line per file instead, naming the schema each came from
(`api.ids → generated/rust/api.rs`) — and the package version, when several are
generated at once. `--dry-run` and `--list` are independent: the first decides
whether anything is written, the second how it is reported.

`comline clean` removes the generated output (the whole `out` directory when it
is a dedicated one, e.g. `generated/`). It leaves `.comline/` alone —
`comline reset` is the command that discards the version history.
Expand Down
8 changes: 5 additions & 3 deletions docs/docs/reference/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ parse → resolve imports → validate → (freeze into .comline/) → (generate
| `comline add <name> <dir>` / `comline add <name> --git <uri> --commit <sha> --version <v>` | Add a dependency to `config.idp`, imported as `use <name>::…`: resolved first (a git pin is fetched into `.comline/deps-cache/`), then written with its `hash` pinned. `--no-hash` skips the pin. |
| `comline check` | Parse, resolve and validate. No `.comline/` write (beyond fetching git dependencies), no version bump — safe for editors, hooks, CI. |
| `comline build [--release] [--watch]` | Compile, validate, freeze a new immutable version into `.comline/`; print the changelog and the bump. `--release` is currently a no-op. |
| `comline generate [--target <lang>] [--out <dir>] [--layout <tpl>] [--mode <m>] [--external-std] [--no-external-std] [--dry-run] [--watch]` | Validate (no freeze), then write generated code. Location/layout from [`comline.toml`](congregation/comline-toml.md); targets from there or `config.idp`. |
| `comline generate [--target <lang>] [--out <dir>] [--layout <tpl>] [--mode <m>] [--external-std] [--no-external-std] [--dry-run] [--list] [--watch]` | Validate (no freeze), then write generated code. Location/layout from [`comline.toml`](congregation/comline-toml.md); targets from there or `config.idp`. |
| `comline diff <old> [<new>]` | Show schema changes between two built versions. Each argument is a version (`0.2.0`), a commit hash (4+ chars), or `HEAD` (`<new>` default). |
| `comline clean [--dry-run]` | Remove generated code (the `generate` output root or files). Never touches `.comline/`. |
| `comline reset [--force] [--dry-run]` | **Destructive.** Delete `.comline/` — the whole version history, no undo — *and* generated code. Next `build` starts over at `0.0.1`. On a terminal it shows how many versions will be lost and makes you type `reset`; without a terminal it refuses (exit `2`) unless `--force`. |
Expand All @@ -49,8 +49,10 @@ reference `comline_std` as its own crate instead of inlining it, and
`--no-external-std` inlines it; either overrides
[`comline.toml`](congregation/comline-toml.md)'s `[generate] external_std`,
which itself defaults to on in `lib` mode and off in `code` mode.
`--dry-run` lists the files each target would write, as a tree, and writes
nothing. Today `rust` and `typescript` are the generators, and both do `code`
Each target's files are drawn as a tree. `--list` prints them one per line
instead, with the schema each came from — and, when several package versions
are generated at once, the version each line belongs to. `--dry-run` writes
nothing and reports either way. Today `rust` and `typescript` are the generators, and both do `code`
and `lib` mode.

## Global flags
Expand Down
Loading