git-worktree-agent (gwa)

A terminal UI for managing git worktrees from remote branches with automatic polling and configurable hooks.

Installation

Via npm (recommended)

The easiest way to install gwa is via npm. This works on Linux, macOS, and Windows:

npm install -g git-worktree-agent

After installation, the gwa command will be available globally:

gwa --version

Via npx (no install)

You can also run gwa directly without installing:

npx git-worktree-agent

Via Cargo

If you have Rust installed, you can install via Cargo:

cargo install git-worktree-agent

From Source

git clone https://github.com/peterbartels/git-worktree-agent
cd git-worktree-agent
cargo install --path .

Download Binary

Pre-built binaries are available on the GitHub Releases page for:

• Linux (x64, arm64)
• macOS (x64, Apple Silicon)
• Windows (x64)

Features

• 🔄 Automatic Branch Watching: Polls remote for new branches every 10 seconds (configurable)
• 🌳 Smart Worktree Creation: Automatically creates local worktrees for remote branches
• ⚡ Post-Create Hooks: Run commands like npm install automatically when worktrees are created
• 📋 Track/Untrack Branches: Fine-grained control over which branches to manage
• 🎯 Pattern-Based Filtering: Ignore branches matching glob patterns
• 💾 Persistent Configuration: JSON config file (gitignored for per-user settings)
• 🖥️ Beautiful TUI: Built with ratatui for a modern terminal experience

Quick Start

1. Navigate to your git repository:

   cd /path/to/your/repo

2. Initialize the configuration:

   gwa --init

3. Start the TUI:

   gwa

4. On first run, you'll be prompted to select which branches to create worktrees for.

Usage

TUI Mode (default)

gwa                    # Start in current directory
gwa --path /path/to/repo  # Start in specific directory
gwa --debug            # Enable debug logging

Keyboard Shortcuts

| Key | Action | |-----|--------| | j / ↓ | Move down | | k / ↑ | Move up | | Enter | Create worktree for selected branch | | d | Delete/untrack worktree | | t | Toggle track/untrack branch | | r | Refresh (fetch from remote) | | a | Toggle auto-create mode | | l | View full command logs | | ? | Show help | | q / Esc | Quit |

Command Line Options

# Show current configuration
gwa --show-config

# Set post-create command
gwa --set-command "npm install"

# Set poll interval (in seconds)
gwa --set-poll-interval 30

# Enable auto-create mode
gwa --auto-create

# Initialize configuration interactively
gwa --init

Configuration

The configuration is stored in .gwa-config.json in your repository root. This file is automatically added to .gitignore since settings are typically per-developer.

Example Configuration

{
  "version": 1,
  "poll_interval_secs": 10,
  "post_create_command": "npm install",
  "command_working_dir": null,
  "ignore_patterns": [
    "dependabot/*",
    "renovate/*"
  ],
  "tracked_branches": [
    "feature/my-feature",
    "fix/important-bug"
  ],
  "untracked_branches": [
    "main",
    "develop"
  ],
  "auto_create_worktrees": false,
  "worktree_base_dir": "..",
  "remote_name": "origin",
  "worktrees": []
}

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | poll_interval_secs | number | 10 | How often to check for new branches (seconds) | | post_create_command | string | null | Command to run after creating a worktree | | command_working_dir | string | null | Subdirectory to run commands in (relative to worktree root) | | ignore_patterns | array | [] | Glob patterns for branches to ignore | | tracked_branches | array | [] | Branches to explicitly track | | untracked_branches | array | [] | Branches to explicitly ignore | | auto_create_worktrees | boolean | false | Automatically create worktrees for new branches | | worktree_base_dir | string | ".." | Where to create worktrees (relative to repo root) | | remote_name | string | "origin" | Remote to watch |

How It Works

1. Discovery: GWA discovers the git repository from your current directory
2. Polling: Every N seconds, it fetches from the configured remote
3. Detection: New branches are detected by comparing with known branches
4. Creation: Worktrees are created in the configured base directory
5. Hooks: If configured, post-create commands are run automatically

Worktree Layout

By default, worktrees are created in the parent directory of your repository:

projects/
├── my-repo/              # Main repository (where you run gwa)
│   ├── .git/
│   ├── .gwa-config.json
│   └── ...
├── feature-my-feature/   # Worktree for feature/my-feature
├── fix-important-bug/    # Worktree for fix/important-bug
└── ...

Development

Prerequisites

• Rust 1.70 or later
• Git

Building

# Debug build
cargo build

# Release build
cargo build --release

# Run directly
cargo run

# Run with debug logging
cargo run -- --debug

Testing

# Run tests
cargo test

# Run tests with output
cargo test -- --nocapture

Project Structure

src/
├── main.rs        # Entry point and CLI handling
├── app.rs         # Main application state and TUI logic
├── config.rs      # Configuration management
├── executor.rs    # Command execution for hooks
├── watcher.rs     # Remote branch polling
├── git/
│   ├── mod.rs
│   ├── repository.rs  # Git repository operations
│   └── worktree.rs    # Worktree management
└── ui/
    ├── mod.rs
    ├── branch_list.rs # Branch list widget
    ├── status.rs      # Status bar widget
    ├── logs.rs        # Command logs widget
    └── help.rs        # Help overlay widget

Architecture

• gitoxide (gix): Used for git operations (fetching, reading refs)
• git CLI: Used for worktree operations (create, remove, list)
• ratatui: TUI framework for the terminal interface
• crossterm: Terminal handling (events, rendering)

Building for Release

The project includes scripts for building release binaries:

# Install cross for cross-compilation
cargo install cross

# Build for all platforms
./scripts/build-release.sh

Troubleshooting

"Failed to discover git repository"

Make sure you're running gwa from within a git repository or specify the path:

gwa --path /path/to/repo

"Fetch failed"

Check your network connection and ensure you have access to the remote repository:

git fetch origin

Worktree creation fails

Ensure the target directory doesn't exist and you have write permissions:

ls -la ../  # Check parent directory

Hooks not running

Check the command is valid and the working directory exists:

gwa --show-config  # Verify configuration

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

See DEPLOYMENT.md for information on how releases are managed.

License

MIT License - see LICENSE for details.

Related Projects

• git-worktree - Git's built-in worktree command
• gitoxide - Rust implementation of Git
• ratatui - Rust TUI library