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
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.
Top comments (0)