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
This commit is contained in:
matt wilkie 2026-07-22 20:44:44 -07:00 • committed by GitHub
commit e7d0fc11e6
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -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 <prefix> --from-jsonl issues.jsonl
bd import # Read .beads/<import.path>
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 <file>`: 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.