{"slug": "worktrunk-takes-the-friction-out-of-git-worktrees", "title": "Worktrunk takes the friction out of Git worktrees", "summary": "Worktrunk, a command-line tool that wraps Git worktrees, addresses three recurring friction points in parallel development: cold starts, port collisions, and leftover Docker containers and volumes. The tool replaces worktree commands with `wt switch --create`, `wt list` and `wt merge`, and runs lifecycle hooks configured in a single committed `.config/wt.toml` file so behavior is identical across a team. The author, writing on the madewithlove blog, reports using Worktrunk on two projects, with hooks that copy gitignored files via `wt step copy-ignored`, assign each branch a stable port through a `hash_port` filter, and run `docker compose down --volumes` before a worktree is removed.", "body_md": "A while ago I wrote about how I [parallelise myself with Git worktrees](https://madewithlove.com/blog/parallelise-yourself-with-git-worktrees/). I still do. But after a few months of it, the friction started to add up. **Worktrees make parallel work possible. They don't make it pleasant.**\n\n## The friction\n\nThree things kept getting in the way.\n\n**Every worktree starts cold.** The code is there, but the app won't run. No environment variables, no vendor files, nothing that's gitignored. It's like cloning a blank project and running the whole setup again.\n\n**Ports collide.** Spin up a Docker stack in a second worktree and it tries to grab the same database port as the first one. You fix it by hand, or you let Claude fix it. Either way, it takes a while.\n\n**Worktrees leave junk behind.** Remove a worktree and its containers and volumes stay. After a few weeks, you have a machine full of Docker containers nobody needs anymore.\n\nNone of these is a big deal on its own. But when you're [running several agents in parallel](https://madewithlove.com/blog/conductor-running-multiple-ai-coding-agents-in-parallel/), you hit all three many times a day.\n\n## Worktrunk\n\n[Worktrunk](https://worktrunk.dev/) is a small CLI that wraps [Git worktrees](https://git-scm.com/docs/git-worktree). There are other tools that do something similar, but this is the one we've been using on two projects, and it's been very useful.\n\nFirst, it replaces the worktree commands you never remember with a few that make sense:\n\n```\nwt switch --create my-feature   # new branch and worktree in one go\nwt list                         # everything you have open\nwt merge                        # merge it and clean up\n```\n\nThe real power is in the hooks. Worktrunk runs shell commands at points in the worktree lifecycle, such as after a worktree starts or before it's removed. You configure them in a single file committed to the repository, so **it works the same for everyone on the team**.\n\n## The hooks we use\n\nHere's a simplified version of our config. It's just a few lines of shell. Nothing fancy, easy to read and easy to tweak.\n\n```\n# .config/wt.toml\n[[post-start]]\ncopy = \"wt step copy-ignored\"\n\n[[post-start]]\nport = \"echo APP_PORT={{ branch | hash_port }} >> .env\"\n\n[pre-remove]\ncleanup = \"docker compose down --volumes\"\n```\n\n**A warm start.** After a worktree is created, we copy over the gitignored files: the environment file, vendor directories, everything you'd otherwise rebuild. Copying takes milliseconds. Running a full dependency install and filling in an env template does not.\n\n**A port per branch.** The `hash_port` filter turns the branch name into a port number, and we write that into the environment. The same branch always gets the same port. So every worktree has its own port and its own database, and you can tear it down and spin it up again later without thinking about it.\n\n**A clean exit.** Before a worktree is removed, we bring the Docker stack down and delete its volumes. No more leftovers.\n\n## What it looks like in practice\n\nCreate a worktree and everything is there. If it's a change that needs the app running, spin up the stack. If it's a small documentation fix, don't bother. List your worktrees whenever you lose track. Merge, and everything is cleaned up.\n\nIt's a small thing. But small friction compounds, especially when your [job has shifted to orchestrating](https://madewithlove.com/blog/out-with-multitasking-in-with-orchestrating/) instead of typing.\n\n## TL;DR\n\nIf you use Git worktrees for parallel work, give Worktrunk a try. One config file in the repository, and every worktree starts warm, gets its own port and cleans up after itself.\n\nYour disk will thank you.", "url": "https://wpnews.pro/news/worktrunk-takes-the-friction-out-of-git-worktrees", "canonical_source": "https://madewithlove.com/blog/worktrunk-takes-the-friction-out-of-git-worktrees/", "published_at": "2026-10-07 16:47:40+00:00", "updated_at": "2026-10-21 09:13:52.110610+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["Worktrunk", "Git worktrees", "Docker", "madewithlove", "Claude"], "also_reported_by": [], "takeaway": "Worktrunk's post-start and pre-remove hooks let each Git worktree copy gitignored files in milliseconds, derive a stable per-branch port via the hash_port filter, and tear down its Docker stack and volumes on removal, eliminating cold starts, port collisions and leftover containers.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/worktrunk-takes-the-friction-out-of-git-worktrees", "markdown": "https://wpnews.pro/news/worktrunk-takes-the-friction-out-of-git-worktrees.md", "text": "https://wpnews.pro/news/worktrunk-takes-the-friction-out-of-git-worktrees.txt", "jsonld": "https://wpnews.pro/news/worktrunk-takes-the-friction-out-of-git-worktrees.jsonld"}}