From e7d0fc11e6fbbf0dae3069d90ce1abaf3000c6c8 Mon Sep 17 00:00:00 2001 From: matt wilkie Date: Wed, 22 Jul 2026 20:44:44 -0700 Subject: [PATCH] docs(plugin): restore current import guidance (#4976) Document active JSONL import usage, timestamp and ID merge semantics, chunk recovery, memory round trips, and the final commit's working-set safety constraints. Agent-Signature: codex-gpt-5.6-sol-high on behalf of matt wilkie --- plugins/beads/skills/beads/commands/import.md | 84 +++++++++++++++++-- 1 file changed, 75 insertions(+), 9 deletions(-) diff --git a/plugins/beads/skills/beads/commands/import.md b/plugins/beads/skills/beads/commands/import.md index bd00c7de1..318cf83e2 100644 --- a/plugins/beads/skills/beads/commands/import.md +++ b/plugins/beads/skills/beads/commands/import.md @@ -1,18 +1,84 @@ --- -description: Import issues from JSONL format (removed) -argument-hint: (removed) +description: Import issues and memories from JSONL +argument-hint: "[file|-] [--input file] [--dry-run] [--dedup] [--allow-stale]" --- -`bd import` has been **removed**. +`bd import` imports newline-delimited JSON into an existing Beads database. +Issues with new IDs are created and existing IDs use guarded upsert semantics. +The command is not supported in proxied-server mode. -## Migration - -If you need to import issues from a JSONL file, use `bd init` with the `--from-jsonl` flag: +## Usage ```bash -bd init --from-jsonl issues.jsonl +bd import # Read .beads/ +bd import backup.jsonl # Read a specific file +bd import --input backup.jsonl # Same as -i backup.jsonl +bd import - # Read JSONL from stdin +bd export --include-memories | bd import - # Round-trip issues and memories +bd import --dry-run backup.jsonl # Parse and report without writing +bd import --json backup.jsonl # Return a structured result ``` -## Note +With no file argument, the source is the `import.path` file under `.beads/`; +`import.path` defaults to `issues.jsonl`. Use either a positional file or +`--input`/`-i`, not both. The special path `-` reads stdin. With `--global` and +no file, the source is `global-issues.jsonl` in the active Beads directory. -Dolt is the primary storage backend. Manual JSONL import is no longer supported as a standalone command. +Each non-empty line must be a JSON object. Issue records accept the schema +emitted by `bd export`; `title` is the only required issue field. Records with +`"_type":"memory"` and non-empty `key` and `value` fields are imported as +persistent memories. Optional export header records are ignored, and tombstone +rows are skipped. `bd export` omits memories by default; add +`--include-memories` or `--all` when they should be carried into an import. + +## Merge and Safety Semantics + +For records that supply `updated_at`, an incoming row rewrites an existing +issue only when its timestamp is strictly newer. Older records are skipped +wholesale, including their labels, comments, and dependencies. When timestamps +are equal, the local issue row wins, while those auxiliary records still merge. +The stale check is repeated inside the upsert so a concurrent newer local update +is not overwritten. + +If `updated_at` is omitted, the importer fills it with the current time during +the write. A record naming an existing ID can therefore overwrite local state; +include the exported timestamp when stale protection matters. + +Use `--allow-stale` only when deliberately restoring an older snapshot: it +disables that guard and can overwrite newer local issue state. Imports are +upserts, and labels, comments, and dependencies are deduplicated. Re-running +canonical export data or other input with stable issue IDs and preserved +`updated_at` values is safe and converges. Without a preserved timestamp, each +run can appear newer and rewrite the row. An issue record without an ID is +assigned one; re-importing it can create another issue instead of targeting the +first. + +Large issue imports use bounded SQL transaction chunks. If one fails, the +command exits nonzero and keeps the already committed prefix in the Dolt working +set; no final import-summary Dolt commit is created. Re-run stable-ID input to +resume only when its `updated_at` values are also preserved. + +After a successful non-dry import with accepted issue or memory records, the +command calls `store.Commit` with an import summary regardless of the +`dolt.auto-commit` policy. That commit can include unrelated pending working-set +changes; in direct server mode, config (including memories) is excluded from +this commit. When commit isolation matters, run `bd doctor` before importing and +proceed only when its Dolt Status check reports a clean working set. + +The database must already exist; initialize or bootstrap it before importing. +Use `--dry-run` to parse the input, apply optional title deduplication, and +report issue and memory counts without writing. It does not run write-time field +validation or predict stale skips and updates. + +## Flags + +- `--input`, `-i `: read a specific file instead of a positional path. +- `--dry-run`: report parsed record counts without writing. +- `--dedup`: skip an input issue whose title exactly matches, ignoring case, an + existing non-closed issue. Input rows are not compared with one another; if + the existing-issue search fails, title filtering is skipped. +- `--allow-stale`: import older rows too, allowing newer local state to be + overwritten. +- `--json`: use global JSON-output mode for structured counts and IDs. The + `created` count is accepted issue rows, including existing rows, not only new + inserts.