Skip to content

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

Add tests for --version, --help-md, and --help-page flags (#220)

Maximilian Roos081087a17131
diff --git a/tests/integration_tests/help.rs b/tests/integration_tests/help.rs
index 8285a61f9..36467352b 100644
--- a/tests/integration_tests/help.rs
+++ b/tests/integration_tests/help.rs
@@ -76,3 +76,95 @@ fn test_help(#[case] test_name: &str, #[case] args_str: &str) {
};
snapshot_help(test_name, &args);
}
+
+/// Test --version flag
+#[test]
+fn test_version() {
+ let mut settings = Settings::clone_current();
+ settings.set_snapshot_path("../snapshots");
+ // Filter out version number for stable snapshots
+ // Formats:
+ // - wt v0.4.0-25-gc9bcf6c0 (version with git commit info)
+ // - wt 7df940e (just git short hash in CI)
+ settings.add_filter(
+ r"wt (v\d+\.\d+\.\d+(-[\w.-]+)?|[a-f0-9]{7,40})",
+ "wt [VERSION]",
+ );
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ cmd.arg("--version");
+ assert_cmd_snapshot!("version", cmd);
+ });
+}
+
+/// Test --help-md flag (raw markdown output without ANSI codes)
+#[test]
+fn test_help_md() {
+ let mut settings = Settings::clone_current();
+ settings.set_snapshot_path("../snapshots");
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ cmd.args(["--help-md"]);
+ assert_cmd_snapshot!("help_md_root", cmd);
+ });
+}
+
+/// Test --help-md for subcommand
+#[test]
+fn test_help_md_subcommand() {
+ let mut settings = Settings::clone_current();
+ settings.set_snapshot_path("../snapshots");
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ cmd.args(["merge", "--help-md"]);
+ assert_cmd_snapshot!("help_md_merge", cmd);
+ });
+}
+
+/// Test --help-page flag for generating doc pages
+#[test]
+fn test_help_page_merge() {
+ let mut settings = Settings::clone_current();
+ settings.set_snapshot_path("../snapshots");
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ cmd.args(["merge", "--help-page"]);
+ assert_cmd_snapshot!("help_page_merge", cmd);
+ });
+}
+
+/// Test --help-page flag for switch command
+#[test]
+fn test_help_page_switch() {
+ let mut settings = Settings::clone_current();
+ settings.set_snapshot_path("../snapshots");
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ cmd.args(["switch", "--help-page"]);
+ assert_cmd_snapshot!("help_page_switch", cmd);
+ });
+}
+
+/// Test --help-page without subcommand shows usage
+#[test]
+fn test_help_page_no_subcommand() {
+ let mut settings = Settings::clone_current();
+ settings.set_snapshot_path("../snapshots");
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ cmd.arg("--help-page");
+ assert_cmd_snapshot!("help_page_no_subcommand", cmd);
+ });
+}
+
+/// Test --help-page with unknown subcommand
+#[test]
+fn test_help_page_unknown_command() {
+ let mut settings = Settings::clone_current();
+ settings.set_snapshot_path("../snapshots");
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ cmd.args(["nonexistent", "--help-page"]);
+ assert_cmd_snapshot!("help_page_unknown", cmd);
+ });
+}
diff --git a/tests/snapshots/integration__integration_tests__help__help_md_merge.snap b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
new file mode 100644
index 000000000..78d4dd538
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_md_merge.snap
@@ -0,0 +1,128 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - merge
+ - "--help-md"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ SOURCE_DATE_EPOCH: "1735776000"
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt merge - Merge worktree into target branch
+
+Squashes commits, rebases, runs hooks, merges to target, and removes the worktree.
+
+Usage: wt merge [OPTIONS] [TARGET]
+
+Arguments:
+ [TARGET]
+ Target branch
+
+ Defaults to default branch.
+
+Options:
+ --no-squash
+ Skip commit squashing
+
+ --no-commit
+ Skip commit and squash
+
+ --no-rebase
+ Skip rebase (fail if not already rebased)
+
+ --no-remove
+ Keep worktree after merge
+
+ --no-verify
+ Skip hooks
+
+ -f, --force
+ Skip approval prompts
+
+ --stage <STAGE>
+ What to stage before committing [default: all]
+
+ Possible values:
+ - all: Stage everything: untracked files + unstaged tracked changes
+ - tracked: Stage tracked changes only (like git add -u)
+ - none: Stage nothing, commit only what's already in the index
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+
+When already on the target branch or in the main worktree, the worktree is preserved automatically.
+
+## Examples
+
+Basic merge to main:
+
+```bash
+wt merge
+```
+
+Merge to a different branch:
+
+```bash
+wt merge develop
+```
+
+Keep the worktree after merging:
+
+```bash
+wt merge --no-remove
+```
+
+Preserve commit history (no squash):
+
+```bash
+wt merge --no-squash
+```
+
+Skip git operations, only run hooks and push:
+
+```bash
+wt merge --no-commit
+```
+
+## Pipeline
+
+`wt merge` runs these steps:
+
+1. **Squash** — Stages uncommitted changes, then combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to
+control what gets staged: `all` (default), `tracked`, or `none`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, uncommitted
+changes are committed separately and individual commits are preserved.
+2. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
+3. **Pre-merge hooks** — Project commands run after rebase, before merge. Failures abort. See [wt hook](@/hook.md).
+4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
+5. **Pre-remove hooks** — Project commands run before removing worktree. Failures abort.
+6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
+7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
+
+Use `--no-commit` to skip all git operations (steps 1-2) and only run hooks and merge. Useful after preparing commits manually with `wt step`.
+Requires a clean working tree.
+
+## See also
+
+- [wt step](@/step.md) — Run individual merge steps (commit, squash, rebase, push)
+- [wt remove](@/remove.md) — Remove worktrees without merging
+- [wt switch](@/switch.md) — Navigate to other worktrees
+
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_md_root.snap b/tests/snapshots/integration__integration_tests__help__help_md_root.snap
new file mode 100644
index 000000000..40a395d4a
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_md_root.snap
@@ -0,0 +1,60 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - "--help-md"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ SOURCE_DATE_EPOCH: "1735776000"
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt - Git worktree management
+
+Usage: wt [OPTIONS] [COMMAND]
+
+Commands:
+ config Manage configuration and shell integration
+ step Run individual workflow operations
+ hook Run hooks independently
+ select Interactive worktree selector
+ list List worktrees and optionally branches
+ switch Switch to a worktree
+ remove Remove worktree and branch
+ merge Merge worktree into target branch
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+ -V, --version
+ Print version
+
+Global Options:
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+
+Getting started
+
+ wt switch --create feature Create worktree and branch
+ wt switch feature Switch to existing worktree
+ wt merge Squash, rebase, and merge to main
+
+Run `wt config shell` to set up directory switching.
+
+Docs: https://worktrunk.dev
+GitHub: https://github.com/max-sixty/worktrunk
+
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_merge.snap b/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
new file mode 100644
index 000000000..a196d7ff1
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_page_merge.snap
@@ -0,0 +1,132 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - merge
+ - "--help-page"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ SOURCE_DATE_EPOCH: "1735776000"
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+<!-- ⚠️ AUTO-GENERATED from `wt merge --help-page` — edit cli.rs to update -->
+
+When already on the target branch or in the main worktree, the worktree is preserved automatically.
+
+## Examples
+
+Basic merge to main:
+
+```bash
+wt merge
+```
+
+Merge to a different branch:
+
+```bash
+wt merge develop
+```
+
+Keep the worktree after merging:
+
+```bash
+wt merge --no-remove
+```
+
+Preserve commit history (no squash):
+
+```bash
+wt merge --no-squash
+```
+
+Skip git operations, only run hooks and push:
+
+```bash
+wt merge --no-commit
+```
+
+## Pipeline
+
+`wt merge` runs these steps:
+
+1. **Squash** — Stages uncommitted changes, then combines all commits since target into one (like GitHub's "Squash and merge"). Use `--stage` to control what gets staged: `all` (default), `tracked`, or `none`. A backup ref is saved to `refs/wt-backup/<branch>`. With `--no-squash`, uncommitted changes are committed separately and individual commits are preserved.
+2. **Rebase** — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
+3. **Pre-merge hooks** — Project commands run after rebase, before merge. Failures abort. See [wt hook](@/hook.md).
+4. **Merge** — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
+5. **Pre-remove hooks** — Project commands run before removing worktree. Failures abort.
+6. **Cleanup** — Removes the worktree and branch. Use `--no-remove` to keep the worktree.
+7. **Post-merge hooks** — Project commands run after cleanup. Failures are logged but don't abort.
+
+Use `--no-commit` to skip all git operations (steps 1-2) and only run hooks and merge. Useful after preparing commits manually with `wt step`. Requires a clean working tree.
+
+## See also
+
+- [wt step](@/step.md) — Run individual merge steps (commit, squash, rebase, push)
+- [wt remove](@/remove.md) — Remove worktrees without merging
+- [wt switch](@/switch.md) — Navigate to other worktrees
+
+## Command reference
+
+```
+wt merge - Merge worktree into target branch
+
+Squashes commits, rebases, runs hooks, merges to target, and removes the worktree.
+
+Usage: wt merge [OPTIONS] [TARGET]
+
+Arguments:
+ [TARGET]
+ Target branch
+
+ Defaults to default branch.
+
+Options:
+ --no-squash
+ Skip commit squashing
+
+ --no-commit
+ Skip commit and squash
+
+ --no-rebase
+ Skip rebase (fail if not already rebased)
+
+ --no-remove
+ Keep worktree after merge
+
+ --no-verify
+ Skip hooks
+
+ -f, --force
+ Skip approval prompts
+
+ --stage <STAGE>
+ What to stage before committing [default: all]
+
+ Possible values:
+ - all: Stage everything: untracked files + unstaged tracked changes
+ - tracked: Stage tracked changes only (like git add -u)
+ - none: Stage nothing, commit only what's already in the index
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+```
+
+<!-- END AUTO-GENERATED from `wt merge --help-page` -->
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_no_subcommand.snap b/tests/snapshots/integration__integration_tests__help__help_page_no_subcommand.snap
new file mode 100644
index 000000000..5019aa7ab
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_page_no_subcommand.snap
@@ -0,0 +1,20 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - "--help-page"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ SOURCE_DATE_EPOCH: "1735776000"
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+Usage: wt <command> --help-page
+Commands with pages: merge, switch, remove, list
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
new file mode 100644
index 000000000..1fa134d85
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
@@ -0,0 +1,134 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - switch
+ - "--help-page"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ SOURCE_DATE_EPOCH: "1735776000"
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+<!-- ⚠️ AUTO-GENERATED from `wt switch --help-page` — edit cli.rs to update -->
+
+Switches to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
+
+## Examples
+
+```bash
+wt switch feature-auth # Switch to worktree
+wt switch - # Previous worktree (like cd -)
+wt switch --create new-feature # Create new branch and worktree
+wt switch --create hotfix --base production
+```
+
+For interactive selection, use [`wt select`](@/select.md).
+
+## Creating worktrees
+
+When the target branch has no worktree, worktrunk:
+
+1. Creates worktree at configured path
+2. Runs [post-create hooks](@/hook.md#post-create) (blocking)
+3. Switches to new directory
+4. Spawns [post-start hooks](@/hook.md#post-start) (background)
+
+The `--create` flag creates a new branch from the `--base` branch (defaults to default branch). Without `--create`, the branch must already exist.
+
+```bash
+wt switch feature # Existing branch → creates worktree
+wt switch --create feature # New branch and worktree
+wt switch --create fix --base release # New branch from release
+wt switch --create temp --no-verify # Skip hooks
+```
+
+## Shortcuts
+
+| Shortcut | Meaning |
+|----------|---------|
+| `^` | Default branch (main/master) |
+| `@` | Current branch/worktree |
+| `-` | Previous worktree (like `cd -`) |
+
+```bash
+wt switch - # Back to previous
+wt switch ^ # Main worktree
+wt switch --create fix --base=@ # Branch from current HEAD
+```
+
+## Argument resolution
+
+Switches to the branch's worktree if one exists, otherwise creates one at the expected path.
+
+If the expected path is occupied by a different branch's worktree, an error is raised.
+
+## See also
+
+- [wt select](@/select.md) — Interactive worktree selection
+- [wt list](@/list.md) — View all worktrees
+- [wt remove](@/remove.md) — Delete worktrees when done
+- [wt merge](@/merge.md) — Integrate changes back to main
+
+## Command reference
+
+```
+wt switch - Switch to a worktree
+
+Usage: wt switch [OPTIONS] <BRANCH>
+
+Arguments:
+ <BRANCH>
+ Branch or worktree name
+
+ Shortcuts: '^' (main), '-' (previous), '@' (current)
+
+Options:
+ -c, --create
+ Create a new branch
+
+ -b, --base <BASE>
+ Base branch
+
+ Defaults to default branch.
+
+ -x, --execute <EXECUTE>
+ Command to run after switch
+
+ Replaces the wt process with the command after switching, giving it full terminal control. Useful for launching editors, AI agents, or other
+ interactive tools.
+
+ Especially useful in shell aliases to create a worktree and start working in one command:
+
+ alias wsc='wt switch --create --execute=claude'
+
+ Then wsc feature-branch creates the worktree and launches Claude Code.
+
+ -f, --force
+ Skip approval prompts
+
+ --no-verify
+ Skip hooks
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+```
+
+<!-- END AUTO-GENERATED from `wt switch --help-page` -->
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_unknown.snap b/tests/snapshots/integration__integration_tests__help__help_page_unknown.snap
new file mode 100644
index 000000000..6aafd1e74
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_page_unknown.snap
@@ -0,0 +1,20 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - nonexistent
+ - "--help-page"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ SOURCE_DATE_EPOCH: "1735776000"
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+Unknown command: nonexistent
diff --git a/tests/snapshots/integration__integration_tests__help__version.snap b/tests/snapshots/integration__integration_tests__help__version.snap
new file mode 100644
index 000000000..228e6df3f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__version.snap
@@ -0,0 +1,19 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - "--version"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ SOURCE_DATE_EPOCH: "1735776000"
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt [VERSION]