Where Is the CLI Argument Parsing Logic Located in Worktrunk?

Worktrunk's CLI argument parsing logic is centralized in src/main.rs, where the clap 4 command tree is constructed and matched against raw arguments to produce a typed Cli enum.

Worktrunk is a fast, safe Git worktree management tool written in Rust. The CLI argument parsing logic leverages the clap 4 crate to define a hierarchical command structure with subcommands, flags, and options. All parsing orchestration—from building the command tree to dispatching to concrete implementations—originates in the main entry point before delegating to specialized modules.

Central CLI Construction in src/main.rs

The foundation of Worktrunk's command-line interface sits in src/main.rs. This file constructs the root clap::Command and defines every top-level subcommand.

The builder pattern initializes the application metadata and enforces that a subcommand is always required:

let mut cmd = clap::Command::new("wt")
    .about("Worktrunk – fast, safe Git worktree management")
    .subcommand_required(true)
    .arg_required_else_help(true)
    // … subcommands such as “switch”, “list”, “merge”, etc.

Each subcommand attaches its own flags and arguments to this root command. The file establishes the complete grammar that clap uses to validate user input.

Parsing the Arguments into a Typed Enum

After construction, the CLI argument parsing logic in src/main.rs converts raw argv into a structured Rust enum. The process clones the command definition and invokes get_matches() to parse the input:

let matches = cmd.clone().get_matches();
let cli = <Cli as clap::FromArgMatches>::from_arg_matches(&matches)
    .expect("failed to map arguments to CLI enum");

The from_arg_matches method maps the parsed arguments onto the Cli enum variants. This transformation allows the application to use exhaustive pattern matching for dispatch:

match cli {
    Cli::Status { verbose } => commands::status::run(verbose),
    // …other variants dispatch to src/commands/*
}

Supporting CLI Infrastructure

While src/main.rs houses the primary parsing logic, several auxiliary modules refine the interface.

Help Customization in src/help.rs

The src/help.rs module augments clap's generated output. It overrides formatting and inserts Worktrunk-specific documentation sections through the augment_help function:

pub fn augment_help(clap_output: &str, ctx: Option<&str>) -> String {
    // Insert Worktrunk‑specific notes, fix fence formatting, etc.
}

Markdown Processing in src/md_help.rs

Documentation generation relies on src/md_help.rs. This file post-processes help text to normalize markdown fences, ensuring consistent formatting when generating external documentation.

Command Implementation in src/commands/*

Once parsing completes, execution flows to src/commands/*. These files contain the concrete logic for each subcommand (e.g., switch, list, merge), receiving their arguments as strongly-typed parameters from the Cli enum.

Summary

• src/main.rs contains the complete CLI argument parsing logic, constructing the clap 4 command tree and converting matches into a typed Cli enum.
• The application uses clap::FromArgMatches::from_arg_matches to bridge raw arguments with Rust's type system.
• src/help.rs customizes help output formatting beyond clap's defaults.
• src/md_help.rs handles markdown normalization for documentation generation.
• Concrete command logic lives in src/commands/*, triggered after successful parsing.

Frequently Asked Questions

Where does Worktrunk define its command-line flags and options?

Worktrunk defines all flags, options, and subcommands in src/main.rs using clap 4's builder API. Each subcommand attaches its specific arguments to the root clap::Command before the parsing phase begins.

How does Worktrunk convert command-line strings into Rust types?

The conversion happens through clap::FromArgMatches::from_arg_matches, called in src/main.rs. This method transforms the raw argument matches into the strongly-typed Cli enum, enabling exhaustive pattern matching for command dispatch.

Can I customize the help text output in Worktrunk?

Yes. While clap generates default help, src/help.rs provides the augment_help function to modify output formatting, insert custom sections, and fix fence formatting for terminal display.

Where is the actual logic for subcommands like switch or list implemented?

The implementation resides in src/commands/*. After src/main.rs parses arguments into the Cli enum, it dispatches to the appropriate module in this directory, passing strongly-typed parameters extracted during parsing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}