beads/website/docs/reference/configuration.md
Giulio Mecocci 87f32865cf
feat: support issue_id_mode=counter for sequential IDs (#2013)
* 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.
2026-02-22 23:49:46 -08:00

3.1 KiB

id title sidebar_position
configuration Configuration 1

Configuration

Complete configuration reference for beads.

Configuration Locations

  1. Project config: .beads/config.toml (highest priority)
  2. User config: ~/.beads/config.toml
  3. Environment variables: BEADS_*
  4. 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'