Skip to content

Configuration

Customize stackit behavior with configuration options.

Layered configuration

Stackit uses a layered configuration system:

  1. Personal settings (highest priority) — Stored in .git/config, not shared
  2. Team settings — Stored in .stackit.yaml, committed and shared with team
  3. Defaults (lowest priority) — Built-in sensible defaults

This allows teams to define shared settings that individual developers can override locally.

Managing configuration

Interactive configuration

Use the interactive TUI to manage all settings:

stackit config

Initialize team configuration

Create a .stackit.yaml file with all available options:

stackit config init

List current configuration

View all current configuration values:

stackit config --list

Set a value

stackit config set <key> <value>

Get a value

stackit config get <key>

Remove a value

stackit config unset <key>

Available options

Auto-generated content

The options below are auto-generated from the config metadata registry.

Trunk branches

trunk

Primary trunk branch

Default: main

Example:

stackit config set trunk main

trunks

Additional trunk branches (e.g., release branches)

Default: (not set)

Example:

stackit config set trunks "develop, release"

Branch naming

branch.pattern

Branch naming pattern

Placeholders: {username}, {date}, {message}, {scope}

Default: (not set)

Example:

stackit config set branch.pattern "{username}/{date}/{message}"

PR submission

submit.footer

Include navigation footer

Default: true

Example:

stackit config set submit.footer false

submit.draft

Create as draft

Default: false

Example:

stackit config set submit.draft true

submit.web

Open in browser: always, created, never

Default: never

Options: always, created, never

Example:

stackit config set submit.web never

submit.labels

Default labels

submit.reviewers

Default reviewers

submit.assignees

Default assignees

Merge settings

merge.method

Merge method: squash, merge, rebase

Default: (not set)

Options: squash, merge, rebase

Example:

stackit config set merge.method squash

CI validation

ci.command

Command to run

Default: (not set)

Example:

stackit config set ci.command "make test"

ci.timeout

Timeout in seconds

Default: 600

Example:

stackit config set ci.timeout 600

Other settings

undo.depth

Max snapshots

Default: 10

Example:

stackit config set undo.depth 10

maxConcurrency

0 = auto-detect

Default: 0

Example:

stackit config set maxConcurrency 0

Worktree settings

worktree.basePath

Base directory (empty = auto)

worktree.autoClean

Clean during sync

Default: true

Example:

stackit config set worktree.autoClean false

Split command

split.hunkSelector

tui or git

Default: tui

Options: tui, git

Example:

stackit config set split.hunkSelector tui

PR navigation

always, never, multiple

Default: multiple

Options: always, never, multiple

Example:

stackit config set navigation.when multiple

body, comment, none

Default: body

Options: body, comment, none

Example:

stackit config set navigation.location body

Current branch marker

Default: 👈

Example:

stackit config set navigation.marker 👈

Show merged history

Default: true

Example:

stackit config set navigation.showMerged false

Team configuration (.stackit.yaml)

For team-wide settings that should be shared across all contributors, create a .stackit.yaml file in your repository root and commit it to version control. Team settings act as defaults that individual developers can override in their personal git config.

See the Team Collaboration Guide for collaboration patterns using shared configuration.

# .stackit.yaml - Team-wide defaults

trunk: main
trunks:
  - develop
  - staging

# Branch naming pattern
branch:
  pattern: "{username}/{date}/{message}"

# PR submission settings
submit:
  footer: true
  draft: false
  web: never
  labels:
    - needs-review
  reviewers:
    - teammate1
  assignees: []

# Merge method: squash, merge, rebase
merge:
  method: squash

# CI validation
ci:
  command: "make test"
  timeout: 600

# Undo history
undo:
  depth: 10

# Worktree settings
worktree:
  basePath: ""
  autoClean: true

# Split command
split:
  hunkSelector: tui

# Concurrency
maxConcurrency: 0

# PR navigation display
navigation:
  when: multiple
  location: body
  marker: 👈
  showMerged: true

# Post-worktree-create hooks (require approval on first run)
hooks:
  post-worktree-create:
    - npm install
    - mise install

Worktree hooks

The hooks.post-worktree-create option allows you to run commands automatically after creating a worktree with stackit create -w.

This is useful for:

  • Installing dependencies (npm install, bundle install, pip install -r requirements.txt)
  • Setting up environment files
  • Running initialization scripts
  • Configuring IDE settings

Security

For safety, the first time a hook is encountered, stackit prompts for approval:

This repo wants to run "npm install" after creating worktrees. Allow? [y/N]
  • The default answer is "No" for security
  • Approvals are stored locally in git config
  • Approvals persist across sessions
  • Hooks have a 60-second timeout

Example configurations

Node.js project:

hooks:
  post-worktree-create:
    - npm install

Python project:

hooks:
  post-worktree-create:
    - python -m venv .venv
    - .venv/bin/pip install -r requirements.txt

Multi-step setup:

hooks:
  post-worktree-create:
    - npm install
    - cp .env.example .env
    - npm run setup

Configuration file location

Stackit configuration is stored in .git/config under the [stackit] section.

You can also edit it directly:

git config --local stackit.submit.footer true

Scope-specific configuration

Configuration is repository-specific by default. To set global defaults:

git config --global stackit.submit.footer false

Next steps