87 lines
4.5 KiB
Markdown
87 lines
4.5 KiB
Markdown
# Command reference
|
|
|
|
Epoch Forge operates on the current working directory; it does not yet search
|
|
parent directories. `efo <command> --help` is the authoritative syntax.
|
|
|
|
## Repository and timeline
|
|
|
|
- `efo init [--force]` creates `.epoch` and `epoch/0/epochinfo.json`. The normal
|
|
form requires an empty directory; `--force` permits unrelated existing files
|
|
but never overwrites `.epoch` or epoch 0.
|
|
- `efo migrate --to 2` validates and previews migration without writing.
|
|
Add `--yes` to create a byte-for-byte manifest backup and initialise the
|
|
version-2 index/worktree. Migration is explicit and format-1 repositories
|
|
remain supported.
|
|
- `efo recover` deterministically rolls back a prepared replacement or verifies
|
|
a committed one. It is safe to repeat.
|
|
- `efo lock inspect` reports writer ownership. `efo lock break --yes` removes
|
|
an abandoned lock only after explicit confirmation; run `efo recover` next.
|
|
- `efo status [EPOCH_ID]` shows an epoch summary, tags, and entity counts.
|
|
- `efo epoch log [-c N]` shows epochs around the current epoch.
|
|
- `efo epoch next` creates and checks out the next snapshot. It refuses while
|
|
later snapshots exist.
|
|
- `efo epoch switch ID_OR_TAG` checks out an existing snapshot without deleting
|
|
later ones.
|
|
- `efo epoch summary TEXT` and `efo epoch tag TAG` annotate the current epoch.
|
|
- `efo epoch diff START [END]` reports added, removed, and modified entities.
|
|
`END` defaults to the current epoch.
|
|
- `efo epoch fsck` performs a read-only consistency check of epoch IDs, tags,
|
|
and entity UUIDs. It does not repair damage.
|
|
- `efo epoch reset` permanently deletes every epoch after the current one.
|
|
|
|
## Entities
|
|
|
|
The built-in nouns are `org`, `chr`, `town`, `event`, `calamity`, and `blocker`.
|
|
`character` aliases `chr`; `organization` and `organisation` alias `org`:
|
|
|
|
```text
|
|
efo <noun> add [NAME | --rng-name] [OPTIONS]
|
|
efo <noun> edit <NAME|@UUID> [OPTIONS]
|
|
efo <noun> show [NAME|@UUID]
|
|
efo <noun> diff <NAME|@UUID> [--epoch-id ID_OR_TAG]
|
|
efo <noun> del <NAME|@UUID>
|
|
```
|
|
|
|
Names match by prefix. `@UUID` is the stable form printed in detailed output;
|
|
short UUID prefixes are accepted. Avoid ambiguous prefixes.
|
|
|
|
Common add/edit options include `--stats key:value ...`, `--position x,y`,
|
|
`--duration`, `--bounds`, `--effect`, faction/reach/description/relationship
|
|
options, and prestige controls. `edit --delta` adds supplied stats rather than
|
|
replacing them. See nested help (for example `efo chr add --help`) for exact
|
|
syntax and values. Mutations write the current epoch immediately; staging does
|
|
not exist in format 1. After format-2 migration, entity mutations edit only the
|
|
worktree. Use `efo diff`, `efo stage --all`, `efo stage --world`, or
|
|
`efo stage --kind KIND ID...`,
|
|
and `efo diff --staged` to prepare history. `efo restore --staged ...` copies
|
|
HEAD into the index; `efo restore --worktree ...` copies the index into the
|
|
worktree. Both restore modes require either `--all` or an entity kind and IDs.
|
|
`efo commit -m MESSAGE` refuses unstaged or empty commits, creates an immutable
|
|
epoch using a manifest-last transaction, and realigns all three layers.
|
|
`efo log` shows the resulting parent-linked history newest first.
|
|
`efo switch ID` requires clean state and changes all layers without reusing
|
|
epoch IDs. `efo revert ID` applies that epoch's inverse and commits it; overlap
|
|
with later changes aborts without mutation. `efo prune-future` previews future
|
|
epochs, while `--yes` moves them into a backup. Restore using the exact command
|
|
printed after pruning. Legacy `efo epoch reset` is deprecated and remains only
|
|
for format-1 compatibility.
|
|
|
|
`efo epoch summary` and `efo epoch tag` edit format-2 worktree metadata;
|
|
`stage --world` selects it. `efo epoch next` requires a clean worktree, includes
|
|
already staged changes, advances entity time, and commits one new monotonic ID.
|
|
`efo epoch fsck` validates format-2 layers and every immutable epoch.
|
|
|
|
`efo show all` lists every collection in the current epoch. `show character`,
|
|
`show town`, `show event`, `show calamity`, and `show blocker` select one
|
|
collection. Use `<noun> show IDENTIFIER` for full details of one entity.
|
|
|
|
## Generation and output
|
|
|
|
`efo gen character|town|event|exotic|calamity|blocker` prints generated content
|
|
without creating or changing repository files.
|
|
|
|
Output is human-readable Unicode, with Nerd Font icons enabled by default. A
|
|
portable build replaces those icons with textual/standard-Unicode labels; use
|
|
`cargo install --path bin_efo --no-default-features`. Stable JSON output is
|
|
planned. A panic is always a bug.
|