DEV Community: Satoshi Ebisawa

git-worktreeinclude: A Tiny CLI for Safely Carrying Over Ignored Files Across Git Worktrees

Satoshi Ebisawa — Tue, 17 Mar 2026 15:58:02 +0000

https://github.com/satococoa/git-worktreeinclude

What is this?

git-worktreeinclude is a CLI for safely copying Git-ignored files from the original worktree to another worktree based on the definitions in .worktreeinclude.

Do you use git worktree?
Ever since I started using CLI-based coding agents, I’ve been using worktrees every day in my development workflow.

The main benefit of worktrees is that they let you separate contexts for different tasks and work on them in parallel. Now that parallel work has become normal in team development and AI-assisted development, worktrees have become an essential part of my workflow.

To make worktrees more convenient, I’ve also released OSS like the following:
https://github.com/satococoa/wtp

Satoshi Ebisawa

Jul 28 '25

wtp: A Better Git Worktree CLI Tool

#git #go #productivity

Comments 1

3 min read

Recently, I’ve mostly been using the Codex app as my coding agent.
The Codex app makes it easy to work in parallel across local environments, worktrees, and the cloud, and it also has a mechanism for running setup scripts right after a worktree is created.

With this mechanism, you can copy .env from the main worktree or run pnpm install.
Also, this configuration can be managed as PROJECT_ROOT/.codex/environments/environment.toml, which makes it possible to share it across a team.

Example configuration
https://x.com/satococoa/status/2018562572132520118

I had also been using a small tool I made to easily copy files from the main worktree.
https://github.com/satococoa/wtcp

However, in team development, the files people want to copy right after creating a worktree often differ from person to person.

I also considered adding PROJECT_ROOT/.codex/environments/environment.toml to .gitignore, but it never felt quite right.

That was when I learned about the .worktreeinclude mechanism.
I thought it would be nice if Codex had something like this too, so I went ahead and built it myself for now.

Basic usage

Basically, it works the same way as Claude Code’s .worktreeinclude.

First, place a .worktreeinclude file in the main worktree and list the files you want to carry over between worktrees.

.env
.env.local
.vscode/settings.json
.mise.local.toml

Then run the following in the newly created worktree.

git worktreeinclude apply

That’s it.
This copies only the files that are listed in .worktreeinclude and ignored by Git, from the main worktree to the current worktree.

If you combine it with the Codex app’s setup script, you can also run it automatically right after a worktree is created.

Features

The key feature of this tool is that, rather than simply copying files, it is designed to behave in a safety-first way.

Only files that are listed in .worktreeinclude and ignored by Git are eligible to be copied.
This helps avoid accidentally copying files that are tracked by Git across worktrees.

Also, if a file with different contents already exists at the destination, it will not overwrite it by default.
You can explicitly overwrite it only when needed by passing --force.

It’s designed for the use case where you want to carry over local-only files, but you want to avoid a sloppy sync mechanism that could cause accidents.

Closing

I think this is especially a good fit for people who use git worktree regularly or who combine coding agents with parallel work across multiple tasks.

I’ve already introduced it into a project I use for work, and it has been useful for me.
If it sounds useful, give it a try.

wtp: A Better Git Worktree CLI Tool

Satoshi Ebisawa — Mon, 28 Jul 2025 13:42:36 +0000

Working with multiple tasks in parallel using Claude Code has become my daily routine, making git worktree essential for my workflow.

While git worktree is convenient, after creating and deleting worktrees multiple times daily, I started noticing some pain points:

The worktree add command is somewhat verbose and tedious
- When creating worktrees based on branch names, you end up typing the branch name twice
- For existing branches: git worktree add .worktrees/hoge hoge
- For new branches: git worktree add -b hoge .worktrees/hoge
I almost always need to manually copy .env files and run npm install after creation
- While Claude Code helps with this when needed, it's more efficient to automate these repetitive tasks
Cleaning up both worktree and branch separately after completing work is tedious

While a simple shell script could solve these requirements, I decided to build a proper CLI tool with Claude Code.

https://github.com/satococoa/wtp

Main Features

wtp add

While git worktree requires specifying both path and branch name, wtp only needs the branch name.

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

# Review PR (existing remote branch)
wtp add fix/hogefuga

The worktree path is automatically generated according to .wtp.yml configuration (defaults to ../worktrees). Remote branch tracking is also automatic.

post create hook

Define post_create in .wtp.yml to automatically execute commands after worktree creation.

hooks:
  post_create:
    - type: copy
      from: .env.example
      to: .env
    - type: command
      command: "npm install"

Automate common tasks like copying .env files and installing dependencies.

remove --with-branch

Since deleting worktree and branch separately is tedious, I made it possible to delete both together.

# With regular git worktree
git worktree remove feature/done
git branch -d feature/done

With wtp, you can delete both in one command.

wtp remove feature/done --with-branch

Warnings are shown for unmerged branches.

Usage Examples

When urgent fixes come in during development

# Create new worktree while keeping current feature work
wtp add -b hotfix/urgent-bug

# Fix bug and create PR
# ...

# Delete both worktree and branch after completion
wtp remove hotfix/urgent-bug --with-branch

# Return to original work
wtp cd feature/new-auth

PR Review

# When review request comes in (for existing remote branch)
wtp add feature/pr-123

# Actually run the application for review
# ...

# Delete worktree after review (remote branch remains)
wtp remove feature/pr-123

Other Features

wtp list

Display worktree list in a clean format.

% wtp list
PATH                           BRANCH           STATUS  HEAD
----                           ------           ------  ----
@                              main             managed 99c30171
feature/add-auth               feature/add-auth managed 99c30171
fix/123/hogefuga*              fix/123/hogefuga managed 99c30171

wtp cd

Navigate between worktrees with shell integration and tab completion.

# Move to worktree
wtp cd feature/auth

# Return to main worktree
wtp cd @

# Tab completion is available
wtp cd <TAB>

Configuration File (.wtp.yml)

Define project-specific settings. Generate initial config with wtp init:

wtp init

Complete configuration file structure:

version: "1.0"
defaults:
  base_dir: "../worktrees"  # worktree creation location

hooks:
  post_create:
    # File copying
    - type: copy
      from: ".env.example"
      to: ".env"

    # Command execution (environment variables can be set)
    - type: command
      command: "bundle install"
      env:
        RAILS_ENV: "development"

Installation

Homebrew

brew install satococoa/tap/wtp

Go install

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

Shell Integration

When installed via Homebrew:

zsh: Completion files are automatically placed. No additional setup needed if FPATH is correctly configured
bash/fish: Completion files are placed, but refer to each shell's documentation for detailed setup

Manual shell integration setup (when installed via go install, etc.):

# Zsh: Add to ~/.zshrc
eval "$(wtp completion zsh)"

# Bash: Add to ~/.bashrc
eval "$(wtp completion bash)"

# Fish: Add to ~/.config/fish/config.fish
wtp completion fish | source

📝 I primarily use zsh, so bash/fish functionality is untested

Why Go?

I consulted with Claude Code on language choice. Reasons for choosing Go:

Single binary distribution (easy installation via brew or go install)
Easy cross-platform support
Static typing helps AI write more stable code

After actually developing with it, I found Go well-suited for Agentic Coding. With static typing and built-in fmt and linting, minimal configuration is needed. Adding golangci-lint and GoReleaser makes CI/CD work seamlessly.

Summary

I created a tool to solve the tedious aspects of git worktree. If you have similar frustrations, please give it a try.

GitHub: https://github.com/satococoa/wtp

Boost Productivity: Using git-worktree with AI Coding Tools

Satoshi Ebisawa — Wed, 14 May 2025 15:01:44 +0000

Are you enjoying working with your favorite coding agents (GitHub Copilot, Cursor, Claude Code, OpenAI Codex, ...etc.) ?

Even these agents are getting faster and faster, you'll often find yourself waiting for them to finish their work.
While waiting for them, what do you usually do?

Editing your code while agents are working will confuse them. So, is waiting all you can do?

If you use git-worktree, you can do all of the following while your agents are working:

Fix another pull request to respond to your colleagues' code review
Fetch your colleagues' pull request and review locally
Tackle other issues
Work on documentation or tests in a separate branch
Handle urgent bug fixes
Let one agent generate code in one branch while you review another agent's output in a different branch

What's git-worktree?

git worktree lets you check out multiple branches into separate directories simultaneously. Unlike git checkout which switches your entire working directory, worktrees create additional working directories that all link back to your main repository.

The main benefits:

Work on multiple branches at once without stashing/committing
Each directory has its own independent state
All worktrees share the same Git history (efficient storage)
Perfect for parallel development workflows

How to use

# Create a worktree for an existing branch
git worktree add ../feature-login feature/login

# Create a new branch and worktree in one command
git worktree add -b fix/api-error ../api-fix main

# List all your worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../feature-login

Remember that .env files and other files in .gitignore won't be copied to new worktrees. Copy these manually when needed.

Conclusion

By combining git worktree with coding agents, you unlock a truly parallel development workflow. While agents are busy generating code in one directory, you can be productive in another. This approach eliminates idle waiting time and maximizes your productivity.

How to setup an official GitHub MCP Server without Docker nor Installing

Satoshi Ebisawa — Sat, 10 May 2025 14:29:09 +0000

GitHub offers an official GitHub MCP Server that enhances AI assistants with GitHub capabilities:
https://github.com/github/github-mcp-server

While the official installation process recommends Docker, you don't actually need it.

If you're familiar with other MCPs, you know the npx or uvx approach that doesn't require Docker or installation.

You can use github-mcp-server in the same way.

Quick Setup (Example for Claude Desktop)

"github": {
  "command": "/Users/satoshi/.local/share/mise/shims/go",
  "args": [
    "run",
    "github.com/github/github-mcp-server/cmd/github-mcp-server@latest",
    "stdio",
    "--dynamic-toolsets"
  ],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR PAT>",
    "HOME": "/Users/satoshi"
  }
}

Important notes:

In command, enter your full path to the Go executable (find it with which go)
go run compiles and runs Go programs without an explicit "Install" process (similar to npx or uvx)
The HOME environment variable is required specifically for Claude Desktop
You'll need a GitHub Personal Access Token with appropriate permissions