DOCSEARCHbyAlgolia
Submit Docs

wtp (Worktree Plus)

repository·main·Indexed 19 days ago

https://github.com/satococoa/wtp

An extension of Git's worktree functionality designed to automate the setup of development environments. wtp provides automated path generation, atomic branch/worktree removal, and a hook system via .wtp.yml for copying files, symlinking shared directories, or running setup commands. It includes shell integration for tab completion and a `wtp cd` command for seamless navigation between worktrees.

Tokens
8.3K
Snippets
33
Records
42
Agent score
67%

What's inside wtp

  1. Use post-create hooks in wtp

    main

    Hooks are executed automatically after a worktree is created. They are processed in the order they are defined and their output is streamed to the terminal.

    Supported Hook Types

    • copy: Copies files from a source to a destination. For relative paths, if to is omitted, it defaults to the value of from.
    • command: Executes a shell command. By default, these commands run within the context of the newly created target worktree.
    • symlink: Creates symbolic links.

    Hook Environment Variables

    When running a command hook, the following environment variables are available to your script:

    • GIT_WTP_WORKTREE_PATH: The path to the new worktree.
    • GIT_WTP_REPO_ROOT: The root path of the main git repository.

  2. How branch resolution works in wtp

    main

    When specifying a branch for a new worktree, wtp follows a specific resolution logic via ResolveBranch:

    1. It first attempts to find a matching local branch.
    2. If no local branch exists, it checks for a matching remote branch.
    3. If multiple remote branches match the name, the operation will fail with an error to prevent ambiguity.

  3. Create worktrees with wtp add

    main

    Use wtp add to create a new worktree. Unlike standard git worktree, wtp automatically generates sensible paths based on branch names (e.g., feature/auth goes to ../worktrees/feature/auth).

    Common Usage Patterns

    • From existing branch: wtp add <branch_name> (tracks remote if not found locally).
    • New branch: wtp add -b <new_branch_name>.
    • New branch from commit: wtp add -b <new_branch_name> <commit_hash>.
    • Track specific remote: wtp add -b <local_branch> <remote_branch>.
    • Run command after setup: wtp add -b <branch> --exec "<command>".
    • Quiet mode (scripting): wtp add -b <branch> --quiet (prints only the absolute path).
    # Create worktree from existing branch
wtp add feature/auth

# Create worktree with new branch
wtp add -b feature/new-feature

# Create new branch from specific commit
wtp add -b hotfix/urgent abc1234

# Create worktree and run a command inside it after hooks
wtp add -b feature/new-feature --exec "npm test"

# Script-friendly output: print only the created absolute path
wtp add -b feature/new-feature --quiet

# Create new branch tracking a different remote branch
wtp add -b feature/test origin/main

  4. Validate Homebrew formula template rendering

    main

    If you are modifying the Homebrew installation or completion behavior, you must update the template located at packaging/homebrew/wtp.rb.tmpl. Before releasing, validate that your changes render correctly using the render-homebrew-formula.sh script with a specific version and checksum.

    To validate, run the script with the following flags:

    • --version: The version string to use in the formula.
    • --sha256: The checksum of the asset.
    • --output: The destination path for the rendered .rb file.
    scripts/render-homebrew-formula.sh --version <version> --sha256 <sha256> --output /tmp/wtp.rb

  5. Resolve ambiguous branch errors

    main

    If wtp add fails because a branch exists in multiple remotes, follow these steps to create a local tracking branch for the specific remote you want to use:

    1. Create the tracking branch: git branch --track <branch_name> <remote>/<branch_name>
    2. Run the wtp command again: wtp add <branch_name>
    # Example: resolving a conflict between origin and upstream
git branch --track feature origin/feature
wtp add feature

  6. Set up shell integration and tab completion

    main

    To enable tab completion and the wtp cd navigation command, you must initialize the shell integration.

    If installed via Homebrew

    No manual setup is required. Simply press TAB after typing wtp to trigger a lazy-load of the integration.

    If installed via Go

    Add the following line to your shell configuration file:

    • Bash: Add eval "$(wtp shell-init bash)" to ~/.bashrc or ~/.bash_profile. (Requires bash-completion v2).
    • Zsh: Add eval "$(wtp shell-init zsh)" to ~/.zshrc.
    • Fish: Add wtp shell-init fish | source to ~/.config/fish/config.fish.

    Navigation with wtp cd

    Once integrated, you can jump between worktrees easily:

    • wtp cd <name>: Switch to a worktree by name.
    • wtp cd @: Switch to the main worktree.
    • wtp cd: Switch to the main worktree (shorthand for @).
    # Bash
eval "$(wtp shell-init bash)"

# Zsh
eval "$(wtp shell-init zsh)"

# Fish
wtp shell-init fish | source

# Usage examples
wtp cd feature/auth
wtp cd @

  7. Format code using go tool task

    main

    The authoritative way to format code in this project is using the fmt task. This task uses golangci-lint fmt (which combines gofmt and goimports) and automatically handles module prefixing to ensure forks and renamed modules stay correctly grouped.

    go tool task fmt

  8. Remove a worktree with uncommitted changes

    main

    By default, wtp prevents the removal of a worktree if it contains uncommitted changes to prevent data loss. To bypass this check and remove the worktree anyway, use the --force flag.

    # Use --force to override uncommitted changes check
wtp remove <worktree_path> --force

  9. Set up a local development environment for wtp

    main

    To contribute to or develop wtp locally, follow these steps to clone the repository, install Go dependencies, and build the binary using the provided task runner.

    # Clone repository
git clone https://github.com/satococoa/wtp.git
cd wtp

# Install dependencies
go mod download

# Run tests
go tool task test

# Build
go tool task build

# Run locally
./wtp --help

  10. Install wtp

    main

    You can install wtp using Homebrew, Go, or by downloading the binary directly.

    Homebrew (macOS/Linux)

    brew install satococoa/tap/wtp

    Go

    go install github.com/satococoa/wtp/v2/cmd/wtp@latest

    Download Binary

    Download the latest binary from GitHub Releases and move it to your PATH (e.g., /usr/local/bin/).

    # macOS (Apple Silicon)
curl -L https://github.com/satococoa/wtp/releases/latest/download/wtp_Darwin_arm64.tar.gz | tar xz
sudo mv wtp /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/satococoa/wtp/releases/latest/download/wtp_Linux_x86_64.tar.gz | tar xz
sudo mv wtp /usr/local/bin/

# Linux (ARM64)
curl -L https://github.com/satococoa/wtp/releases/latest/download/wtp_Linux_arm64.tar.gz | tar xz
sudo mv wtp /usr/local/bin/

  11. Integrate wtp with your shell for auto-navigation

    main

    Because a child process cannot change the directory of its parent shell, wtp cd only prints the target path. To enable actual directory switching and automatic navigation after running wtp add, you must initialize shell integration.

    Use the following commands to generate the necessary integration scripts for your specific shell:

    # For bash
wtp shell-init bash

# For zsh
wtp shell-init zsh

# For fish
wtp shell-init fish

    Alternatively, you can use wtp hook <shell> to generate scripts specifically for hook execution environments.

  12. Configure wtp using .wtp.yml

    main

    Configuration for wtp is managed via a .wtp.yml file.

    Key configuration details:

    • base_dir: Defines the directory where worktrees are stored. The default value is ../worktrees.
    • Hooks: You can define post-create hooks of types copy, command, or symlink to automate setup tasks when a new worktree is created.