Configuration

SDF uses a two-tier configuration system that separates team-wide settings from personal preferences.

---

Config files

File	Scope	Location
.sdf/config.json	Repository	Local-only (inside gitignored .sdf/ directory)
~/.config/sdf/config.json	User (global)	Per-machine

When both files exist, repository config takes precedence on a field-by-field basis. Missing files are not errors — SDF works without any config file, using built-in defaults.

Run sdf config show to see the effective merged result.

---

Available settings

branch_prefix

Controls automatic branch name prefixing when creating branches with sdf branch. This is a nested object with three sub-fields.

branch_prefix.enabled

Whether branch prefix enforcement is active.

• Type: boolean
• Default: true

branch_prefix.scope

The scope used as both the branch prefix and the conventional commit scope. When empty, falls back to the stack ID.

• Type: string
• Default: "" (uses stack ID)

branch_prefix.separator

The character placed between the prefix and the branch name.

• Type: string
• Default: "/"

{
  "branch_prefix": {
    "enabled": true,
    "scope": "team-name",
    "separator": "/"
  }
}

With this config, sdf branch add-logging creates team-name/add-logging instead of add-logging.

---

pr_title

Controls how PR titles are generated. This is a nested object with two sub-fields.

pr_title.conventional_commits

PR titles follow the Conventional Commits style, using the scope as the conventional commit scope (e.g., feat(auth): add logging).

• Type: boolean
• Default: true

pr_title.ticket_pattern

A regex pattern used to extract a ticket ID from the branch name and include it in the PR title.

• Type: string
• Default: "" (disabled)

{
  "pr_title": {
    "conventional_commits": true,
    "ticket_pattern": "[A-Z]+-[0-9]+"
  }
}

---

sync

Controls behavior during sdf sync. This is a nested object.

sync.with_content

When enabled, sdf sync also updates PR titles and descriptions using Claude CLI.

• Type: boolean
• Default: false

{
  "sync": {
    "with_content": true
  }
}

---

Setting values

Use sdf config set to update individual keys. Valid keys are dot-separated paths into the config structure.

# Set in repo config (.sdf/config.json)
sdf config set branch_prefix.enabled true
sdf config set branch_prefix.scope team-name
sdf config set branch_prefix.separator /
sdf config set pr_title.conventional_commits false
sdf config set pr_title.ticket_pattern "[A-Z]+-[0-9]+"
sdf config set sync.with_content true

# Set in global config (~/.config/sdf/config.json)
sdf config set --global branch_prefix.scope my-username

Or edit the JSON files directly — they are plain JSON with no schema enforcement beyond what SDF reads.

Valid keys

Key	Type	Default	Description
branch_prefix.enabled	bool	true	Enable/disable branch prefix enforcement
branch_prefix.scope	string	--	Scope string used as branch prefix (empty = use stack ID). Does not affect PR title scope.
branch_prefix.separator	string	/	Separator character between prefix and branch name
pr_title.conventional_commits	bool	true	Enable conventional commit prefixes in PR titles
pr_title.ticket_pattern	string	--	Regex to extract ticket ID from branch name for PR titles
sync.with_content	bool	false	Auto-update PR titles and descriptions during sync
worktree.base_path	string	../{repo}.worktrees	Base directory for per-branch worktrees ({repo} = repo dir name)

---

Example repo config

{
  "branch_prefix": {
    "enabled": true,
    "scope": "team-name",
    "separator": "/"
  },
  "pr_title": {
    "conventional_commits": true
  }
}

Save this as .sdf/config.json in any repo to use these settings. Since .sdf/ is local-only, each developer creates this file on their own machine (or it is created automatically by sdf new and sdf fetch).

---

Example global config

{
  "branch_prefix": {
    "scope": "my-username"
  },
  "sync": {
    "with_content": true
  }
}

This lives in ~/.config/sdf/config.json and applies to all repositories on your machine. Repo-level values override these on a field-by-field basis.