Add support for worktrees

[alexrinass]

Extend topic branch workflows to support Git worktrees. When creating a topic branch, users can optionally create a corresponding worktree, enabling parallel development and simplifying AI-assisted or automated workflows where changes can be merged back once completed.

This feature includes:

• Configuring a base directory for automatic worktree creation using a pattern (e.g. ~/Dev/git-flow-next-worktrees/{branch})
• Displaying the status of all managed worktrees, including which ones can be safely pruned
• Automatically switching to the associated worktree when using git flow feature checkout

By integrating worktrees directly into the branch lifecycle, developers can work on multiple features simultaneously without frequent context switching or repository duplication.

[bmcdonnell-fb]

I'm leery of this idea of coupling worktrees to (transient) branches.

One reason is that IIRC, it can be difficult to delete worktrees that contain Git submodules (and my repos often do). Additionally, transient worktrees will create clutter in the recent list in IDEs, and I imagine there would be extra disk/processing churn from features like Intellisense.

Due to considerations like these, my worktrees are long lived, named like MyProj-02.

Food for thought.

[alexrinass]

@bmcdonnell-fb That’s fair feedback, and to be clear this wouldn’t be mandatory or on by default.

Worktree usage would be entirely opt-in. Users who don’t want worktrees — or who prefer long-lived, manually managed ones — wouldn’t need to change anything. Branch creation and deletion would behave exactly as they do today unless worktree integration is explicitly enabled, either globally via configuration or per branch by passing an explicit option.

The motivation is to support workflows that benefit from isolated, parallel checkouts — for example working on multiple features at once, temporarily switching to a bugfix without disturbing ongoing work, or AI/agentic coding and automated workflows where a task can run in its own worktree and be merged back when complete.

Regarding submodules: Git worktrees have a known limitation with submodules. So this feature could detect submodules and warn or error out rather than create a worktree in a situation that’s known to be problematic.

Would this address your concerns, or are there other cases where the opt-in approach still feels risky?

[bmcdonnell-fb]

I'm concerned that even as opt-in (of course), it's at least tacit endorsement of a suspect or problematic workflow.

I wasn't sure my view of the developer landscape is wide enough, so following your latest reply, I had a chat with Claude AI (Sonnet 4.5) about it. It amplified my concerns, and said "[you] should not add this feature".

Excerpts below.

---

Starting with only this prompt, no context of this discussion, it suggests transient worktrees are uncommon.

Are transient, branch-coupled git worktrees a common, well-accepted workflow?

Branch-coupled git worktrees (where each worktree is tied to a specific branch) are a reasonably common and accepted workflow, but not universally so. Here's the landscape:

Common use cases where they're well-accepted:

• Parallel work contexts - Many developers keep worktrees for different types of work (feature development, hotfixes, code review) to avoid constant stashing or context switching
• Long-running branches - Teams with stable development/staging/production branches often maintain persistent worktrees for each
• CI/build isolation - Build systems sometimes use worktrees to test multiple branches simultaneously

The "transient" aspect is less common. Most people who use worktrees tend to keep them around semi-permanently rather than creating/deleting them frequently. The overhead of setting up and tearing down worktrees (plus the mental overhead of remembering where they are) makes truly transient usage less appealing.

Alternative workflows are more prevalent:

• Traditional branch switching in a single working directory remains the default for most developers
• Stashing or committing WIP work before switching
• Using separate clones for parallel work (though this is heavier-weight)

The community perspective: Worktrees are considered a "power user" feature - well-documented, stable, and supported, but not part of the typical Git workflow most people learn. Those who use them tend to appreciate them greatly, but they're far from universal.

If you're considering this workflow, it's perfectly legitimate, but you might find that keeping 2-3 semi-permanent worktrees (rather than constantly creating transient ones) strikes a better balance between flexibility and overhead.

---

Then I shared the preceding content from this discussion.

...

The IDE clutter point is underrated. Modern IDEs are already heavy on indexing and caching. Creating/destroying worktrees frequently means:

• Repeatedly indexing the same codebase in different locations
• IDE "recent projects" getting polluted
• Potential workspace/project file duplication
• Build artifacts and caches scattered across worktrees

...

---

The question is should they add this proposed feature to their "git flow" implementation. i.e. By so doing, should they encourage this workflow of transient and branch-coupled worktrees?

No, they should not add this feature.

Here's why:

1. It normalizes a problematic pattern

Even as opt-in, including this in git-flow signals "this is a recommended workflow." Git-flow is prescriptive by nature - it's an opinionated workflow tool. Adding worktree coupling suggests this is a good practice when the evidence suggests it's fraught with issues for many common scenarios.

2. The submodule problem is a showstopper

This isn't a niche edge case - submodules are widely used in frontend (npm/yarn workspaces), mobile (dependency management), enterprise monorepos, and embedded systems. A feature that "detects and errors out" for a large portion of potential users is a feature that shouldn't exist in the first place. It creates a footgun for users who don't realize their repo has submodules until things break.

3. The automation use case doesn't need git-flow

Alex's strongest argument is AI/automation workflows. But automated systems can already manage worktrees directly with git worktree add/remove. They don't need git-flow's branch lifecycle management - they just need basic Git commands. Adding this to git-flow doesn't make automation easier; it just couples two orthogonal concerns.

4. It conflates workspace and branch lifecycle

Your MyProj-02 approach gets this right: worktrees are where you work, branches are what you work on. These have different lifecycles and different management needs. Coupling them creates impedance mismatches that cause real friction (IDE clutter, disk churn, orphaned state).

5. Git-flow's job is branch management, not workspace management

Git-flow should help you manage the develop/master/feature/release branch structure. Once you start managing worktrees, you're in a different domain with different concerns. Feature creep matters for tool adoption and maintenance.

Bottom line: This feature solves a problem that doesn't need solving, creates problems for common use cases (submodules), and encourages a workflow pattern that has significant practical drawbacks. The fact that it's opt-in doesn't change that git-flow would be endorsing and supporting something that's questionable practice for most users.

[alexrinass]

AIs tend to follow and favor the arguments you present to them, so for discussions like this I prefer to stick with human reasoning. 😉

Your introductory question might already nudge an AI in a certain direction. If you instead ask it very briefly, “What are common use-cases for git worktrees?”, it will typically mention things like:

Working on multiple features in parallel
When you need to context-switch between features or tasks frequently, worktrees let you keep each branch in its own directory. You can jump between them instantly without any checkout overhead.

Hotfixes on production branches
If you’re deep into feature work but need to push an urgent fix to main or a release branch, a worktree lets you make that fix without touching your current working directory.

The git-worktree man page also makes it clear that worktrees are very much designed around temporarily pairing worktrees with branches. One of the examples explicitly states:

You are in the middle of a refactoring session and your boss comes in and demands that you fix something immediately. You might typically use git-stash[1] to store your changes away temporarily, however, your working tree is in such a state of disarray (with new, moved, and removed files, and other bits and pieces strewn around) that you don’t want to risk disturbing any of it. Instead, you create a temporary linked worktree to make the emergency fix, remove it when done, and then resume your earlier refactoring session.

This kind of temporary worktree workflow also shows up in many tutorials and matches my own experience of how people tend to use worktrees (myself included). As such, it’s not an uncommon or problematic workflow per se.

While it’s not a workflow for everyone or every scenario, it has become increasingly popular with AI-assisted coding—and it fits very well within a git-flow–style workflow.

Because of that, having an option to create a worktree together with a branch seems like a sensible choice to me.

It’s essentially an existing Git capability that we optionally allow users to take advantage of in a more convenient way.

[bmcdonnell-fb]

AIs tend to follow and favor the arguments you present to them,

Indeed. I thought at least my opening was pretty neutral, though. And I do try to push back, even (especially?) when it agrees with me.

If you instead ask it very briefly, “What are common use-cases for git worktrees?”,

None of your example AI answers speak to my points of contention, though. Transience in particular.

This kind of temporary worktree workflow also shows up in many tutorials and matches my own experience of how people tend to use worktrees (myself included).

Maybe it could make some sense for lightweight repos without submodule? I'm still leery, though.

[Serhioromano]

To my understanding workfree is and alternative to Gitflow. It is way git decided to implement same functionality. So to mee it is either Git Flow or may be even same flow but through Worktrees.

[bmcdonnell-fb]

To my understanding [worktree] is [an] alternative to Gitflow.

Incorrect. They are completely unrelated features. Some may use one or the other, or neither. I use both.

[alexrinass]

@Serhioromano Worktrees aren't really an alternative to git-flow-next, or to any branching workflow — they're a different layer entirely.

A worktree is just a lightweight way to check out multiple branches in parallel without cloning the repository again. Each worktree is a separate working directory, but they all share the same underlying repo: the main repo knows about every linked worktree, and Git can tell you which branch is currently checked out in which worktree. So you don't end up with disconnected copies — it's one repo with several working directories attached.

Because of that, worktrees don't really affect your workflow. They're more of a variant on how you organise your working copies, and git-flow-next runs perfectly well on top of them. You can drive the same feature/release/hotfix flow whether you work in a single checkout or spread across several worktrees.

One small caveat: git switch / git checkout still operate on the current worktree, so if a branch is already checked out elsewhere Git will refuse to switch to it. That's a place where git-flow-next could be smarter — e.g. detect that the target branch lives in another worktree and either cd into that one or run the command from there. That's on our radar.

We also plan to add direct worktree integration to the branch lifecycle (e.g. optionally creating a worktree when you feature start). The original post at the top of this discussion outlines what that would look like.

Out of curiosity — did you run into a specific problem when combining worktrees with git-flow-next, or was this more of a conceptual question?

[gcapnias]

Working with worktrees is one thing, but having agents operate in parallel within them is another.

In the current setup, a person manually creates a new branch with worktree support, it just works—you initiate it, and you’re good to go. There are pros and cons, but it requires knowing what you’re doing.

Ideally, the tool should be able to automatically create branches for features, bug fixes, or even a new type handoff, based on predefined rules—deciding the worktree location either relative to the repository or at a fixed path.

Inside or outside the repository — personally, I prefer outside, but there’s no strict limit. If it’s git-excluded, it can also be inside the repository.

The person or agent overseeing this operation has the full picture, and there’s no context change—you’re still within part of the filesystem that contains the original checkout. The working environment remains untouched.

To switch branches/worktrees, you simply close the solution and open the new one. Merges, checkouts, or other actions happen entirely within that isolated space, keeping the rest of repository unaffected while still allowing interaction.

This setup is great for coding agents—point them to the repository path, isolate their workspace, let work, commit, and submit a PR to the working branch.

[alexrinass]

Turned this into a tracked feature. The umbrella issue with the concept, usage, and a spec breakdown is #171; the individual specs will land as sub-issues under it. Closing this in favor of #171, which is where the work will be tracked.

[alexrinass]

Shipped in v2.1.0 — start --worktree, worktree-aware checkout, list --worktrees, and worktree cleanup on finish/delete. See the announcement for the overview or #171 for the full spec breakdown.