* feat: support issue_id_mode=counter for sequential IDs (GH#2002) When `issue_id_mode=counter` is set via `bd config set issue_id_mode counter`, `bd create` now assigns monotonically increasing integer IDs instead of hash-based IDs. The counter is stored in a new `issue_counter` table (one row per prefix) and incremented atomically within the same transaction as the issue insert. - Add `issue_counter` table to schema (version bumped to 5) - Add migration 006 to create `issue_counter` table on existing databases - Add `GetNextIssueCounter()` to queries.go (standalone transaction, for callers outside CreateIssue) - Modify `generateIssueID()` to check `issue_id_mode` config and use counter path when set to "counter"; hash mode remains the default when unset - Explicit `--id` flag continues to take precedence over counter mode - Tests: TestGetNextIssueCounter_Sequential, TestGetNextIssueCounter_MultiplePrefixes, TestCreateIssue_CounterMode, TestCreateIssue_ExplicitIDOverridesCounter, TestCreateIssue_HashModeDefault, TestMigrateIssueCounterTable * docs: document issue_id_mode=counter feature (GH#2002) Add documentation for the sequential counter ID mode across all relevant docs: - docs/CONFIG.md: new issue_id_mode namespace entry and full example section with tradeoff table, migration guidance, and per-prefix counter isolation - .beads/BD_GUIDE.md: counter mode section with when-to-use, migration considerations, and explicit --id override behavior - docs/ADAPTIVE_IDS.md: alternative counter mode section with cross-reference to CONFIG.md - website/docs/reference/configuration.md: issue_id_mode under ID Generation with comparison table * fix: seed counter from existing issues when enabling counter mode (GH#2002) When issue_id_mode=counter is enabled on a repo that already has manually-created sequential IDs (e.g., plug-1 through plug-50), the counter used to start at 1, causing immediate collisions. Add seedCounterFromExistingIssuesTx() which scans existing issue IDs, finds the highest numeric suffix for the given prefix, and seeds the issue_counter table from there. The function is idempotent (skips if a counter row already exists) and only counts purely-numeric suffixes (ignoring hash-based IDs like test-a3f2). The seeding is called at first counter use: in generateIssueID() (issues.go) and GetNextIssueCounter() (queries.go) when sql.ErrNoRows is returned for the prefix. Add four tests covering: seeding from existing numeric IDs, mixed hash+numeric IDs, fresh repos (counter starts at 1), and already-seeded counters (no regress). * feat: add bd config schema and describe commands for agent discoverability (GH#2002) Adds machine-readable config schema so agents can programmatically discover all available configuration keys without reading source code. - internal/config/schema.go: new ConfigKeyDef struct and Schema slice with 43 entries covering core, sync, routing, jira, linear, gitlab, team, mail, and YAML-only keys; includes type, default, valid values, description, and storage location per key - cmd/bd/config.go: adds 'bd config schema' (table + --json) and 'bd config describe <key>' (single-key detail + --json) subcommands Usage: bd config schema bd config schema --json | jq '.[] | select(.key == "issue_id_mode")' bd config describe issue_id_mode bd config describe jira.url --json * refactor: remove overengineered config schema (keep docs only) Remove the configSchemaCmd and configDescribeCmd subcommands added in the previous commit, along with internal/config/schema.go (390 lines of config key definitions). These are out of scope for GH#2002.
3.1 KiB
3.1 KiB
| id | title | sidebar_position |
|---|---|---|
| configuration | Configuration | 1 |
Configuration
Complete configuration reference for beads.
Configuration Locations
- Project config:
.beads/config.toml(highest priority) - User config:
~/.beads/config.toml - Environment variables:
BEADS_* - Command-line flags: (highest priority)
Managing Configuration
# Get config value
bd config get import.orphan_handling
# Set config value
bd config set import.orphan_handling allow
# List all config
bd config list
# Reset to default
bd config reset import.orphan_handling
Configuration Options
Database
[database]
path = ".beads/beads.db" # Database file location
ID Generation
[id]
prefix = "bd" # Issue ID prefix
hash_length = 4 # Hash length in IDs
Issue ID mode controls whether new issues get hash-based or sequential IDs:
# Use sequential IDs: bd-1, bd-2, bd-3, ...
bd config set issue_id_mode counter
# Use hash-based IDs (default): bd-a3f2, bd-7f3a8, ...
bd config set issue_id_mode hash
| Mode | Example ID | Best for |
|---|---|---|
hash (default) |
bd-a3f2 |
Multi-agent, multi-branch workflows |
counter |
bd-1 |
Single-writer, project-management UIs |
Counter IDs are sequential and human-friendly. Hash IDs are collision-free across concurrent branches. See docs/CONFIG.md for migration guidance and full details.
Import
[import]
orphan_handling = "allow" # allow|resurrect|skip|strict
dedupe_on_import = false # Run duplicate detection after import
| Mode | Behavior |
|---|---|
allow |
Import orphans without validation (default) |
resurrect |
Restore deleted parents as tombstones |
skip |
Skip orphaned children with warning |
strict |
Fail if parent missing |
Export
[export]
path = ".beads/issues.jsonl" # Default export file path (for bd export command)
Git
[git]
auto_commit = true # Auto-commit on sync
auto_push = true # Auto-push on sync
commit_message = "bd sync" # Default commit message
Hooks
[hooks]
pre_commit = true # Enable pre-commit hook
post_merge = true # Enable post-merge hook
pre_push = true # Enable pre-push hook
Deletions
[deletions]
retention_days = 30 # Keep deletion records for N days
prune_on_sync = true # Auto-prune old records
Environment Variables
| Variable | Description |
|---|---|
BEADS_DB |
Database path |
BEADS_LOG_LEVEL |
Log level |
BEADS_CONFIG |
Config file path |
Per-Command Override
# Override database
bd --db /tmp/test.db list
Example Configuration
.beads/config.toml:
[id]
prefix = "myproject"
hash_length = 6
[import]
orphan_handling = "resurrect"
dedupe_on_import = true
[git]
auto_commit = true
auto_push = true
[deletions]
retention_days = 90
Viewing Active Configuration
bd info --json | jq '.config'