Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

feat(config): [ci] platform override and documentation improvements (#465)

Maximilian Rooseba155344634
diff --git a/dev/wt.example.toml b/dev/wt.example.toml
index 06ac8fddc..6302d57c9 100644
--- a/dev/wt.example.toml
+++ b/dev/wt.example.toml
@@ -89,3 +89,12 @@
# ============================================================================
# [list]
# url = "http://localhost:{{ branch | hash_port }}"
+
+# ============================================================================
+# CI Platform Override
+# ============================================================================
+# Override CI platform detection for GitHub Enterprise or self-hosted GitLab
+# with custom domains where URL detection fails.
+#
+# [ci]
+# platform = "github" # or "gitlab"
diff --git a/docs/content/config.md b/docs/content/config.md
index ef7458b95..dc68a5c3d 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -176,6 +176,17 @@ url = "http://localhost:{{ branch | hash_port }}"
URLs are dimmed when the port isn't listening. The template supports `{{ branch }}` with filters `hash_port` (port 10000-19999) and `sanitize` (filesystem-safe).
+### CI platform override
+
+The `[ci]` section overrides CI platform detection for GitHub Enterprise or self-hosted GitLab with custom domains:
+
+```toml
+[ci]
+platform = "github" # or "gitlab"
+```
+
+By default, the platform is detected from the remote URL. Use this when URL detection fails (e.g., `git.mycompany.com` instead of `github.mycompany.com`).
+
## Shell integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
@@ -199,6 +210,20 @@ wt config shell init fish | source
Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.
+### Skip first-run prompt
+
+On first run without shell integration, Worktrunk offers to install it. Suppress this prompt in CI or automated environments:
+
+```toml
+skip-shell-integration-prompt = true
+```
+
+Or via environment variable:
+
+```bash
+export WORKTRUNK_SKIP_SHELL_INTEGRATION_PROMPT=true
+```
+
## Environment variables
All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.
@@ -243,7 +268,7 @@ WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \
| `WORKTRUNK_CONFIG_PATH` | Override user config file location |
| `WORKTRUNK_DIRECTIVE_FILE` | Internal: set by shell wrappers to enable directory changes |
| `WORKTRUNK_SHELL` | Internal: set by shell wrappers to indicate shell type (e.g., `powershell`) |
-| `WORKTRUNK_MAX_CONCURRENT_COMMANDS` | Max parallel git commands (default: 32). Lower if hitting resource limits. |
+| `WORKTRUNK_MAX_CONCURRENT_COMMANDS` | Max parallel git commands (default: 32). Lower if hitting file descriptor limits. |
| `NO_COLOR` | Disable colored output ([standard](https://no-color.org/)) |
| `CLICOLOR_FORCE` | Force colored output even when not a TTY |
@@ -576,6 +601,15 @@ With `--project`, creates `.config/wt.toml` in the current repository:
# ============================================================================
# [list]
# url = "http://localhost:{{ branch | hash_port }}"
+
+# ============================================================================
+# CI Platform Override
+# ============================================================================
+# Override CI platform detection for GitHub Enterprise or self-hosted GitLab
+# with custom domains where URL detection fails.
+#
+# [ci]
+# platform = "github" # or "gitlab"
```
### Command reference
@@ -791,7 +825,7 @@ Caches GitHub/GitLab CI status for display in [`wt list`](@/list.md#ci-status).
### How it works
-1. **Platform detection** — Detected from remote URL (github.com → GitHub, gitlab.com → GitLab)
+1. **Platform detection** — From `[ci] platform` in project config, or detected from remote URL (github.com → GitHub, gitlab.com → GitLab)
2. **CLI requirement** — Requires `gh` (GitHub) or `glab` (GitLab) CLI, authenticated
3. **What's checked** — PRs/MRs first, then branch pipelines for branches with upstream
4. **Caching** — Results cached 30-60 seconds per branch+commit
diff --git a/docs/content/list.md b/docs/content/list.md
index bf959f43a..265782092 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -148,20 +148,29 @@ Rows are dimmed when [safe to delete](@/remove.md#branch-cleanup) (`_` same comm
Query structured data with `--format=json`:
```bash
+# Current worktree path (for scripts)
+wt list --format=json | jq -r '.[] | select(.is_current) | .path'
+
+# Branches with uncommitted changes
+wt list --format=json | jq '.[] | select(.working_tree.modified)'
+
# Worktrees with merge conflicts
wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
-# Uncommitted changes
-wt list --format=json | jq '.[] | select(.working_tree.modified)'
+# Branches ahead of main (needs merging)
+wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
+
+# Integrated branches (safe to remove)
+wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
-# Current worktree
-wt list --format=json | jq '.[] | select(.is_current)'
+# Branches without worktrees
+wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
-# Branches ahead of the default branch
-wt list --format=json | jq '.[] | select(.main.ahead > 0)'
+# Worktrees ahead of remote (needs pushing)
+wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
-# Integrated branches (ready to clean up)
-wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty")'
+# Stale CI (local changes not reflected in CI)
+wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
```
**Fields:**
diff --git a/docs/content/select.md b/docs/content/select.md
index b86bbe859..9b2b6a604 100644
--- a/docs/content/select.md
+++ b/docs/content/select.md
@@ -48,6 +48,19 @@ Toggle between views with number keys:
Branches without worktrees are included — selecting one creates a worktree. (`wt list` requires `--branches` to show them.)
+## Configuration
+
+### Pager
+
+The preview panel pipes diff output through git's pager (typically `less` or `delta`). Override pager behavior in user config:
+
+```toml
+[select]
+pager = "delta --paging=never"
+```
+
+This is useful when the default pager doesn't render correctly in the embedded preview panel.
+
## See also
- [`wt list`](@/list.md) — Static table view with all worktree metadata
diff --git a/docs/content/step.md b/docs/content/step.md
index 6f1850244..6c0dd804c 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -36,6 +36,42 @@ wt step push
- `push` — Fast-forward target to current branch
- `for-each` — [experimental] Run a command in every worktree
+## Options
+
+### `--stage`
+
+Controls what to stage before committing. Available for `commit` and `squash`:
+
+| Value | Behavior |
+|-------|----------|
+| `all` | Stage all changes including untracked files (default) |
+| `tracked` | Stage only modified tracked files |
+| `none` | Don't stage anything, commit only what's already staged |
+
+```bash
+wt step commit --stage=tracked
+wt step squash --stage=none
+```
+
+Configure the default in user config:
+
+```toml
+[commit]
+stage = "tracked"
+```
+
+### `--show-prompt`
+
+Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
+
+```bash
+# Inspect the rendered prompt
+wt step commit --show-prompt | less
+
+# Pipe to a different LLM
+wt step commit --show-prompt | llm -m gpt-5-nano
+```
+
## See also
- [`wt merge`](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
diff --git a/src/cli.rs b/src/cli.rs
index 72df2d162..318b7b43a 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -513,7 +513,7 @@ Without a subcommand, runs `get`."#
## How it works
-1. **Platform detection** — Detected from remote URL (github.com → GitHub, gitlab.com → GitLab)
+1. **Platform detection** — From `[ci] platform` in project config, or detected from remote URL (github.com → GitHub, gitlab.com → GitLab)
2. **CLI requirement** — Requires `gh` (GitHub) or `glab` (GitLab) CLI, authenticated
3. **What's checked** — PRs/MRs first, then branch pipelines for branches with upstream
4. **Caching** — Results cached 30-60 seconds per branch+commit
@@ -1482,20 +1482,29 @@ Rows are dimmed when [safe to delete](@/remove.md#branch-cleanup) (`_` same comm
Query structured data with `--format=json`:
```console
+# Current worktree path (for scripts)
+wt list --format=json | jq -r '.[] | select(.is_current) | .path'
+
+# Branches with uncommitted changes
+wt list --format=json | jq '.[] | select(.working_tree.modified)'
+
# Worktrees with merge conflicts
wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
-# Uncommitted changes
-wt list --format=json | jq '.[] | select(.working_tree.modified)'
+# Branches ahead of main (needs merging)
+wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
+
+# Integrated branches (safe to remove)
+wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
-# Current worktree
-wt list --format=json | jq '.[] | select(.is_current)'
+# Branches without worktrees
+wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
-# Branches ahead of the default branch
-wt list --format=json | jq '.[] | select(.main.ahead > 0)'
+# Worktrees ahead of remote (needs pushing)
+wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
-# Integrated branches (ready to clean up)
-wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty")'
+# Stale CI (local changes not reflected in CI)
+wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
```
**Fields:**
@@ -1899,6 +1908,19 @@ Toggle between views with number keys:
Branches without worktrees are included — selecting one creates a worktree. (`wt list` requires `--branches` to show them.)
+## Configuration
+
+### Pager
+
+The preview panel pipes diff output through git's pager (typically `less` or `delta`). Override pager behavior in user config:
+
+```toml
+[select]
+pager = "delta --paging=never"
+```
+
+This is useful when the default pager doesn't render correctly in the embedded preview panel.
+
## See also
- [`wt list`](@/list.md) — Static table view with all worktree metadata
@@ -1938,6 +1960,42 @@ wt step push
- `push` — Fast-forward target to current branch
- `for-each` — [experimental] Run a command in every worktree
+## Options
+
+### `--stage`
+
+Controls what to stage before committing. Available for `commit` and `squash`:
+
+| Value | Behavior |
+|-------|----------|
+| `all` | Stage all changes including untracked files (default) |
+| `tracked` | Stage only modified tracked files |
+| `none` | Don't stage anything, commit only what's already staged |
+
+```bash
+wt step commit --stage=tracked
+wt step squash --stage=none
+```
+
+Configure the default in user config:
+
+```toml
+[commit]
+stage = "tracked"
+```
+
+### `--show-prompt`
+
+Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
+
+```bash
+# Inspect the rendered prompt
+wt step commit --show-prompt | less
+
+# Pipe to a different LLM
+wt step commit --show-prompt | llm -m gpt-5-nano
+```
+
## See also
- [`wt merge`](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
@@ -2601,6 +2659,17 @@ url = "http://localhost:{{ branch | hash_port }}"
URLs are dimmed when the port isn't listening. The template supports `{{ branch }}` with filters `hash_port` (port 10000-19999) and `sanitize` (filesystem-safe).
+### CI platform override
+
+The `[ci]` section overrides CI platform detection for GitHub Enterprise or self-hosted GitLab with custom domains:
+
+```toml
+[ci]
+platform = "github" # or "gitlab"
+```
+
+By default, the platform is detected from the remote URL. Use this when URL detection fails (e.g., `git.mycompany.com` instead of `github.mycompany.com`).
+
## Shell integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
@@ -2624,6 +2693,20 @@ wt config shell init fish | source
Without shell integration, `wt switch` prints the target directory but cannot `cd` into it.
+### Skip first-run prompt
+
+On first run without shell integration, Worktrunk offers to install it. Suppress this prompt in CI or automated environments:
+
+```toml
+skip-shell-integration-prompt = true
+```
+
+Or via environment variable:
+
+```bash
+export WORKTRUNK_SKIP_SHELL_INTEGRATION_PROMPT=true
+```
+
## Environment variables
All user config options can be overridden with environment variables using the `WORKTRUNK_` prefix.
@@ -2668,7 +2751,7 @@ WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \
| `WORKTRUNK_CONFIG_PATH` | Override user config file location |
| `WORKTRUNK_DIRECTIVE_FILE` | Internal: set by shell wrappers to enable directory changes |
| `WORKTRUNK_SHELL` | Internal: set by shell wrappers to indicate shell type (e.g., `powershell`) |
-| `WORKTRUNK_MAX_CONCURRENT_COMMANDS` | Max parallel git commands (default: 32). Lower if hitting resource limits. |
+| `WORKTRUNK_MAX_CONCURRENT_COMMANDS` | Max parallel git commands (default: 32). Lower if hitting file descriptor limits. |
| `NO_COLOR` | Disable colored output ([standard](https://no-color.org/)) |
| `CLICOLOR_FORCE` | Force colored output even when not a TTY |
diff --git a/src/commands/config.rs b/src/commands/config.rs
index 076fc7508..7d3ab77d3 100644
--- a/src/commands/config.rs
+++ b/src/commands/config.rs
@@ -246,14 +246,18 @@ fn render_runtime_info(out: &mut String) -> anyhow::Result<()> {
/// Run full diagnostic checks (CI tools, commit generation) and render to buffer
fn render_diagnostics(out: &mut String) -> anyhow::Result<()> {
use super::list::ci_status::{CiPlatform, CiToolsStatus, get_platform_for_repo};
+ use worktrunk::config::ProjectConfig;
writeln!(out, "{}", format_heading("DIAGNOSTICS", None))?;
- // Check CI tool based on detected platform
- let platform = Repository::current()
+ // Check CI tool based on detected platform (with config override support)
+ let repo = Repository::current();
+ let project_config = ProjectConfig::load(&repo, true).ok().flatten();
+ let platform_override = project_config.as_ref().and_then(|c| c.ci_platform());
+ let platform = repo
.worktree_root()
.ok()
- .and_then(|root| get_platform_for_repo(root.to_str()?));
+ .and_then(|root| get_platform_for_repo(root.to_str()?, platform_override));
match platform {
Some(CiPlatform::GitHub) => {
diff --git a/src/commands/list/ci_status.rs b/src/commands/list/ci_status.rs
index 3a805a96f..b0e4eb68e 100644
--- a/src/commands/list/ci_status.rs
+++ b/src/commands/list/ci_status.rs
@@ -7,9 +7,11 @@ use worktrunk::path::sanitize_for_filename;
use worktrunk::shell_exec::run;
use worktrunk::utils::get_now;
-/// CI platform detected from remote URL
-// TODO: Add a `[ci] platform = "github" | "gitlab"` override in project config
-// for cases where URL detection fails or users want to force a specific platform.
+/// CI platform detected from project config override or remote URL.
+///
+/// Platform is determined by:
+/// 1. Project config `[ci] platform = "github" | "gitlab"` (takes precedence)
+/// 2. Remote URL detection (searches for "github" or "gitlab" in URL)
#[derive(Debug, Clone, Copy, PartialEq, Eq, strum::Display, strum::EnumString)]
#[strum(serialize_all = "lowercase")]
pub enum CiPlatform {
@@ -29,8 +31,33 @@ fn detect_platform_from_url(url: &str) -> Option<CiPlatform> {
}
}
-/// Get the CI platform for a repository by checking its origin remote URL.
-pub fn get_platform_for_repo(repo_root: &str) -> Option<CiPlatform> {
+/// Get the CI platform for a repository.
+///
+/// If `platform_override` is provided (from project config `[ci] platform`),
+/// uses that value directly. Otherwise, detects platform from the origin
+/// remote URL.
+///
+/// # Arguments
+///
+/// * `repo_root` - Repository root path
+/// * `platform_override` - Optional platform from `[ci] platform` in project config
+pub fn get_platform_for_repo(
+ repo_root: &str,
+ platform_override: Option<&str>,
+) -> Option<CiPlatform> {
+ // Config override takes precedence
+ if let Some(platform_str) = platform_override {
+ if let Ok(platform) = platform_str.parse::<CiPlatform>() {
+ log::debug!("Using CI platform from config override: {}", platform);
+ return Some(platform);
+ }
+ log::warn!(
+ "Invalid CI platform in config: '{}'. Expected 'github' or 'gitlab'.",
+ platform_str
+ );
+ }
+
+ // Fall back to URL detection
let url = get_remote_url_for_repo(repo_root)?;
detect_platform_from_url(&url)
}
@@ -126,6 +153,32 @@ mod tests {
);
}
+ #[test]
+ fn test_platform_override_github() {
+ // Config override should take precedence over URL detection
+ assert_eq!(
+ "github".parse::<CiPlatform>().ok(),
+ Some(CiPlatform::GitHub)
+ );
+ }
+
+ #[test]
+ fn test_platform_override_gitlab() {
+ // Config override should take precedence over URL detection
+ assert_eq!(
+ "gitlab".parse::<CiPlatform>().ok(),
+ Some(CiPlatform::GitLab)
+ );
+ }
+
+ #[test]
+ fn test_platform_override_invalid() {
+ // Invalid platform strings should not parse
+ assert!("invalid".parse::<CiPlatform>().is_err());
+ assert!("GITHUB".parse::<CiPlatform>().is_err()); // Case-sensitive
+ assert!("GitHub".parse::<CiPlatform>().is_err()); // Case-sensitive
+ }
+
#[test]
fn test_ttl_jitter_range_and_determinism() {
use std::path::Path;
@@ -1142,7 +1195,7 @@ impl PrStatus {
/// Detect CI status without caching (internal implementation)
///
- /// Platform is determined by the remote URL (github.com vs gitlab.com).
+ /// Platform is determined by project config override or remote URL detection.
/// For unknown platforms (e.g., GitHub Enterprise with custom domains), falls back
/// to trying both platforms.
/// PR/MR detection always runs. Workflow/pipeline fallback only runs if `has_upstream`.
@@ -1152,8 +1205,15 @@ impl PrStatus {
repo_root: &str,
has_upstream: bool,
) -> Option<Self> {
- // Determine platform from remote URL
- let platform = get_platform_for_repo(repo_root);
+ use worktrunk::config::ProjectConfig;
+
+ // Load project config for platform override
+ let repo = Repository::at(repo_root);
+ let project_config = ProjectConfig::load(&repo, false).ok().flatten();
+ let platform_override = project_config.as_ref().and_then(|c| c.ci_platform());
+
+ // Determine platform (config override or URL detection)
+ let platform = get_platform_for_repo(repo_root, platform_override);
match platform {
Some(CiPlatform::GitHub) => {
diff --git a/src/commands/list/mod.rs b/src/commands/list/mod.rs
index b36208ffa..8ebde7951 100644
--- a/src/commands/list/mod.rs
+++ b/src/commands/list/mod.rs
@@ -228,14 +228,16 @@ pub fn handle_list(
if !ci_tools.any_available() {
use ci_status::{CiPlatform, get_platform_for_repo};
use color_print::cformat;
- use worktrunk::git::Repository;
+ use worktrunk::config::ProjectConfig;
use worktrunk::styling::hint_message;
- // Detect platform from repo's remote URL
- let platform = Repository::current()
+ // Detect platform from repo's remote URL (with config override support)
+ let project_config = ProjectConfig::load(&repo, true).ok().flatten();
+ let platform_override = project_config.as_ref().and_then(|c| c.ci_platform());
+ let platform = repo
.worktree_root()
.ok()
- .and_then(|root| get_platform_for_repo(root.to_str()?));
+ .and_then(|root| get_platform_for_repo(root.to_str()?, platform_override));
// Only show hint for the relevant platform's tool
let hint = match platform {
diff --git a/src/config/mod.rs b/src/config/mod.rs
index 2ad661a75..350fed3dd 100644
--- a/src/config/mod.rs
+++ b/src/config/mod.rs
@@ -31,7 +31,8 @@ pub use deprecation::normalize_template_vars;
pub use expansion::{expand_template, sanitize_branch_name};
pub use hooks::HooksConfig;
pub use project::{
- ProjectConfig, ProjectListConfig, find_unknown_keys as find_unknown_project_keys,
+ ProjectCiConfig, ProjectConfig, ProjectListConfig,
+ find_unknown_keys as find_unknown_project_keys,
};
pub use user::{
CommitGenerationConfig, StageMode, UserProjectConfig, WorktrunkConfig,
diff --git a/src/config/project.rs b/src/config/project.rs
index 6d469a85e..ece6eef10 100644
--- a/src/config/project.rs
+++ b/src/config/project.rs
@@ -32,6 +32,26 @@ pub struct ProjectListConfig {
pub url: Option<String>,
}
+/// Project-level CI configuration.
+///
+/// Override CI platform detection when URL-based detection fails (e.g., GitHub
+/// Enterprise or self-hosted GitLab with custom domains).
+///
+/// # Example
+///
+/// ```toml
+/// [ci]
+/// platform = "github" # or "gitlab"
+/// ```
+#[derive(Debug, Serialize, Deserialize, Clone, Default, PartialEq)]
+pub struct ProjectCiConfig {
+ /// CI platform override. When set, skips URL-based platform detection.
+ ///
+ /// Values: "github" or "gitlab"
+ #[serde(default)]
+ pub platform: Option<String>,
+}
+
impl ProjectListConfig {
/// Returns true if any list configuration is set.
pub fn is_configured(&self) -> bool {
@@ -39,6 +59,13 @@ impl ProjectListConfig {
}
}
+impl ProjectConfig {
+ /// Get the CI platform override if configured.
+ pub fn ci_platform(&self) -> Option<&str> {
+ self.ci.as_ref().and_then(|ci| ci.platform.as_deref())
+ }
+}
+
/// Project-specific configuration with hooks.
///
/// This config is stored at `<repo>/.config/wt.toml` within the repository and
@@ -77,6 +104,10 @@ pub struct ProjectConfig {
#[serde(default)]
pub list: Option<ProjectListConfig>,
+ /// CI configuration (platform override)
+ #[serde(default)]
+ pub ci: Option<ProjectCiConfig>,
+
/// Captures unknown fields for validation warnings
#[serde(flatten, default, skip_serializing)]
unknown: std::collections::HashMap<String, toml::Value>,
@@ -156,6 +187,7 @@ mod tests {
assert!(config.hooks.post_merge.is_none());
assert!(config.hooks.pre_remove.is_none());
assert!(config.list.is_none());
+ assert!(config.ci.is_none());
}
// ============================================================================
@@ -276,6 +308,51 @@ url = "http://localhost:{{ branch | hash_port }}"
assert!(!config.is_configured());
}
+ // ============================================================================
+ // CiConfig Tests
+ // ============================================================================
+
+ #[test]
+ fn test_deserialize_ci_platform_github() {
+ let contents = r#"
+[ci]
+platform = "github"
+"#;
+ let config: ProjectConfig = toml::from_str(contents).unwrap();
+ assert!(config.ci.is_some());
+ let ci = config.ci.unwrap();
+ assert_eq!(ci.platform.as_deref(), Some("github"));
+ }
+
+ #[test]
+ fn test_deserialize_ci_platform_gitlab() {
+ let contents = r#"
+[ci]
+platform = "gitlab"
+"#;
+ let config: ProjectConfig = toml::from_str(contents).unwrap();
+ assert!(config.ci.is_some());
+ let ci = config.ci.unwrap();
+ assert_eq!(ci.platform.as_deref(), Some("gitlab"));
+ }
+
+ #[test]
+ fn test_deserialize_ci_empty() {
+ let contents = r#"
+[ci]
+"#;
+ let config: ProjectConfig = toml::from_str(contents).unwrap();
+ assert!(config.ci.is_some());
+ let ci = config.ci.unwrap();
+ assert!(ci.platform.is_none());
+ }
+
+ #[test]
+ fn test_ci_config_default() {
+ let config = ProjectCiConfig::default();
+ assert!(config.platform.is_none());
+ }
+
// ============================================================================
// find_unknown_keys Tests
// ============================================================================
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index bd64d043e..522c39c2e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -338,3 +338,12 @@ With --project, creates .config/wt.toml in the current repositor
# ============================================================================
# [list]
# url = "http://localhost:{{ branch | hash_port }}"
+ 
+ # ============================================================================
+ # CI Platform Override
+ # ============================================================================
+ # Override CI platform detection for GitHub Enterprise or self-hosted GitLab
+ # with custom domains where URL detection fails.
+ #
+ # [ci]
+ # platform = "github" # or "gitlab"
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 67af42c14..5d1b3973c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -188,6 +188,15 @@ The [list] section adds a URL column to wt list:
URLs are dimmed when the port isn't listening. The template supports {{ branch }} with filters hash_port (port 10000-19999) and sanitize
(filesystem-safe).
+CI platform override
+
+The [ci] section overrides CI platform detection for GitHub Enterprise or self-hosted GitLab with custom domains:
+
+ [ci]
+ platform = "github" # or "gitlab"
+
+By default, the platform is detected from the remote URL. Use this when URL detection fails (e.g., git.mycompany.com instead of github.mycompany.com).
+
Shell integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
@@ -207,6 +216,16 @@ Or manually add to the shell config:
Without shell integration, wt switch prints the target directory but cannot cd into it.
+Skip first-run prompt
+
+On first run without shell integration, Worktrunk offers to install it. Suppress this prompt in CI or automated environments:
+
+ skip-shell-integration-prompt = true
+
+Or via environment variable:
+
+ export WORKTRUNK_SKIP_SHELL_INTEGRATION_PROMPT=true
+
Environment variables
All user config options can be overridden with environment variables using the WORKTRUNK_ prefix.
@@ -241,12 +260,12 @@ Override the LLM command in CI to use a mock:
Other environment variables
- Variable Purpose
- ───────────────────────────────── ──────────────────────────────────────────────────────────────────────────
- WORKTRUNK_BIN Override binary path for shell wrappers (useful for testing dev builds)
- WORKTRUNK_CONFIG_PATH Override user config file location
- WORKTRUNK_DIRECTIVE_FILE Internal: set by shell wrappers to enable directory changes
- WORKTRUNK_SHELL Internal: set by shell wrappers to indicate shell type (e.g., powershell)
- WORKTRUNK_MAX_CONCURRENT_COMMANDS Max parallel git commands (default: 32). Lower if hitting resource limits.
- NO_COLOR Disable colored output (standard)
+ Variable Purpose
+ ───────────────────────────────── ─────────────────────────────────────────────────────────────────────────────────
+ WORKTRUNK_BIN Override binary path for shell wrappers (useful for testing dev builds)
+ WORKTRUNK_CONFIG_PATH Override user config file location
+ WORKTRUNK_DIRECTIVE_FILE Internal: set by shell wrappers to enable directory changes
+ WORKTRUNK_SHELL Internal: set by shell wrappers to indicate shell type (e.g., powershell)
+ WORKTRUNK_MAX_CONCURRENT_COMMANDS Max parallel git commands (default: 32). Lower if hitting file descriptor limits.
+ NO_COLOR Disable colored output (standard)
CLICOLOR_FORCE Force colored output even when not a TTY
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status.snap
index 23d757d26..326449705 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status.snap
@@ -48,7 +48,7 @@ Caches GitHub/GitLab CI status for display in wt list.
How it works
-1. Platform detection — Detected from remote URL (github.com → GitHub, gitlab.com → GitLab)
+1. Platform detection — From [ci] platform in project config, or detected from remote URL (github.com → GitHub, gitlab.com → GitLab)
2. CLI requirement — Requires gh (GitHub) or glab (GitLab) CLI, authenticated
3. What's checked — PRs/MRs first, then branch pipelines for branches with upstream
4. Caching — Results cached 30-60 seconds per branch+commit
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index a8d4d6b10..f0bd3aeff 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -156,20 +156,29 @@ Rows are dimmed when safe to delete (_ same commit with clean working tr
Query structured data with --format=json:
+ # Current worktree path (for scripts)
+ wt list --format=json | jq -r '.[] | select(.is_current) | .path'
+ 
+ # Branches with uncommitted changes
+ wt list --format=json | jq '.[] | select(.working_tree.modified)'
+ 
# Worktrees with merge conflicts
wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'

- # Uncommitted changes
- wt list --format=json | jq '.[] | select(.working_tree.modified)'
+ # Branches ahead of main (needs merging)
+ wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
+ 
+ # Integrated branches (safe to remove)
+ wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'

- # Current worktree
- wt list --format=json | jq '.[] | select(.is_current)'
+ # Branches without worktrees
+ wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'

- # Branches ahead of the default branch
- wt list --format=json | jq '.[] | select(.main.ahead > 0)'
+ # Worktrees ahead of remote (needs pushing)
+ wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'

- # Integrated branches (ready to clean up)
- wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty")'
+ # Stale CI (local changes not reflected in CI)
+ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
Fields:
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
index b87993a36..8a605c94a 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
@@ -168,20 +168,29 @@ content integrated).
Query structured data with --format=json:
+ # Current worktree path (for scripts)
+ wt list --format=json | jq -r '.[] | select(.is_current) | .path'
+ 
+ # Branches with uncommitted changes
+ wt list --format=json | jq '.[] | select(.working_tree.modified)'
+ 
# Worktrees with merge conflicts
wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'

- # Uncommitted changes
- wt list --format=json | jq '.[] | select(.working_tree.modified)'
+ # Branches ahead of main (needs merging)
+ wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
+ 
+ # Integrated branches (safe to remove)
+ wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'

- # Current worktree
- wt list --format=json | jq '.[] | select(.is_current)'
+ # Branches without worktrees
+ wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'

- # Branches ahead of the default branch
- wt list --format=json | jq '.[] | select(.main.ahead > 0)'
+ # Worktrees ahead of remote (needs pushing)
+ wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'

- # Integrated branches (ready to clean up)
- wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty")'
+ # Stale CI (local changes not reflected in CI)
+ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
Fields:
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index cc2d85669..c59ff2efc 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -69,6 +69,36 @@ Manual merge workflow with review between steps:
- push — Fast-forward target to current branch
- for-each — [experimental] Run a command in every worktree
+Options
+
+`--stage`
+
+Controls what to stage before committing. Available for commit and squash:
+
+ Value Behavior
+ ─────── ───────────────────────────────────────────────────────
+ all Stage all changes including untracked files (default)
+ tracked Stage only modified tracked files
+ none Don't stage anything, commit only what's already staged
+
+ wt step commit --stage=tracked
+ wt step squash --stage=none
+
+Configure the default in user config:
+
+ [commit]
+ stage = "tracked"
+
+`--show-prompt`
+
+Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
+
+ # Inspect the rendered prompt
+ wt step commit --show-prompt | less
+ 
+ # Pipe to a different LLM
+ wt step commit --show-prompt | llm -m gpt-5-nano
+
See also
- wt merge — Runs commit → squash → rebase → hooks → push → cleanup automatically