Git Worktrees support

[berkus]

Describe the feature

Similar to vscode gitlens extension, support checking out multiple branches into separate work folders and showing them all as multiple independent project trees within one window. (this uses git worktree commands underneath)

Will add some screeenshots in a bit.

See: https://git-scm.com/docs/git-worktree

[notpeter]

Can you provide a simple example for how to build a mini project demonstrating this setup and how you would like to use it?

[berkus]

@notpeter So, in my repo github.com/metta-systems/vesper I have many branches for parallel workstreams. They are all parts of the same project but they are wildly different in the state of completion and even starting point (some are rebased, some are still off of some older trees).

One approach I tried was:

1. create a .worktrees folder inside the "main" checkout that is open in Zed
2. inside the worktrees folder use "git worktree add" to create various subfolders, each corresponding to a particular branch/workstream/feature
3. open and edit files inside these subtrees from the single zed instance having the top directory with "main" checkout.

This is extremely unwieldy because of a few issues:

1. the subtrees folders get randomly closed/collapsed based on some update logic somewhere, so i could be editing a file in a subtree and suddenly the folder I was in disappears, and i need to go to .worktrees and expand each level manually again
2. zed and rust-analyzer completely go bonkers because there are now some unrelated files inside the main checkout with completely separate Cargo.tomls and workspaces - editing code in this setup is a nightmare.
3. zed does not know that files inside .worktrees folder are actually different checkouts of the same repository, so it doesn't provide any assitance with those - all the worktree/git maintenance commands are manual via cli, the main zed windows shows "main" branch as checked out, even though i'm working in something like "feat/mmu-support".

Another approach

I've tried opening multiple zed windows, each in one of the workspace subpaths of .worktrees folder. That works a bit better, but all maintenance steps are still manual, and there are many zed windows around even though I usually work on one worktree at a time.

What am I expecting?

Native support for "git worktrees" - these are parts of git config, discoverable via git queries. Basically, I want to either replace branch selector or add one more selector next to it that would switch the active zed workspace to one of the defined git worktree locations (these can really be located ANYWHERE - as you specify the disk path for the subtree in the git cli). Also, I would like to see a native Zed support for creating a worktree - i.e. have a default path pattern where a new worktree would be created for branch X.

[berkus]

i.e. the listing of the current setup:

/somewhere/vesper.git <-- this is open in Zed and corresponds to "main" branch
+--.worktrees
      +--feat
            +--feat1.             <-- this is a git worktree registered for feat/feat1 branch
            +--feat2             <-- this is a git worktree registered for feat/feat1 branch
      +--fix
           +--bugfix1.        <-- this is a git worktree registered for fix/bugfix1 branch

The specific naming of the folders is not too important as far as:

1. they are not affecting each other too much (that's why .worktrees is a hidden dir - i don't want it to pollute the main workspace too much)
2. they are relatively independent and can be created and removed without affecting anything else (here it's not too good - ideally the worktree for "main" branch should also be inside .worktrees but zed doesn't support this configuration and it would be too awkward currently)

Ideally, the worktree support would work like one of the vscode worktree extensions does - it creates a BARE git repo checkout to track worktrees and then creates per-branch worktrees beside it, e.g.

vesper.git
+--.bare      <-- bare git repo, solely for shared repo storage
+--.worktrees
      +--main      <-- zed would pick that as just one of the worktrees and let switch to/from it as usual
      +--feat
           +--feat1 ....

[JacobCallahan]

I'm a big fan of using worktrees for larger features, or those that succumb to scope creep. Not sure if it will help with implementation ideas, but below is the bashrc function I made to work with worktrees.

All worktrees are stored in a directory next to the repo root directory.
That directory is named "repo_dir.worktrees".

# Function to manage Git worktrees interactively (external directory structure, corrected exit path)
worktree() {
  # Determine the common .git directory path
  local common_git_dir
  common_git_dir=$(git rev-parse --git-common-dir 2>/dev/null)
  if [[ -z "$common_git_dir" ]]; then
    echo "System Alert: Operation must be performed within a Git repository or its worktree." >&2
    return 1
  fi

  # Determine the main repository root path from the common git directory
  local main_repo_root_path
  main_repo_root_path=$(dirname "$common_git_dir")

  # Derive repository name and parent directory from the main repo root
  local repo_name
  repo_name=$(basename "$main_repo_root_path")
  local parent_dir
  parent_dir=$(dirname "$main_repo_root_path")
  local worktree_base_dir="${parent_dir}/${repo_name}.worktrees"

  # Simplified main branch detection (relative to the main repo context)
  local main_branch
  if git --git-dir="$common_git_dir" --work-tree="$main_repo_root_path" show-ref --verify --quiet refs/heads/main; then
      main_branch="main"
  else
      main_branch="master" # Assumes master if main doesn't exist
  fi
  local target_name="$1"

  if [[ -n "$target_name" ]]; then
    # Handle Provided Worktree Name
    local target_path="${worktree_base_dir}/${target_name}"
    # Check if the absolute path exists in the worktree list
    if git worktree list --porcelain | grep "^worktree " | cut -d ' ' -f 2- | grep -q "^${target_path}$"; then
      echo "Navigating to existing worktree: $target_path"
      cd "$target_path" || return 1
    else
      # Create new worktree
      echo "Worktree '$target_name' not found at expected location. Creating..."
      local branch_choice
      # List branches from the main repository context
      branch_choice=$(git --git-dir="$common_git_dir" --work-tree="$main_repo_root_path" branch --format='%(refname:short)' | fzf --height 15% --reverse --prompt="Select source branch for '$target_name': ")
      if [[ -n "$branch_choice" ]]; then
        # Ensure the base directory exists
        mkdir -p "$worktree_base_dir" || { echo "System Alert: Failed to create base directory $worktree_base_dir" >&2; return 1; }
        echo "Executing: git worktree add \"$target_path\" \"$branch_choice\""
        # Run git worktree add from the main repo context for consistency
        if git --git-dir="$common_git_dir" --work-tree="$main_repo_root_path" worktree add "$target_path" "$branch_choice"; then
           echo "Worktree created. Navigating to $target_path"
           cd "$target_path" || return 1
        else
           echo "System Alert: 'git worktree add' command failed." >&2
           # Simple cleanup attempt
           if [[ -d "$target_path" ]] && ! ls -A "$target_path" | grep -qv '.git'; then
               rmdir "$target_path" 2>/dev/null
           fi
           return 1
        fi
      else
        echo "Worktree creation cancelled."
        return 1
      fi
    fi
  else
    # Handle No Worktree Name Provided
    # List worktree *names* located in the designated external directory
    local worktree_names
    # Use porcelain format for more reliable parsing
    worktree_names=$(git worktree list --porcelain | grep "^worktree " | cut -d ' ' -f 2- | awk -v base="$worktree_base_dir/" '$0 ~ "^" base { sub(base, "", $0); print $0 }')


    local selection
    local exit_option="Exit (Switch to '$main_branch' in main directory)"
    local options="$exit_option\n$worktree_names"

    selection=$(echo -e "$options" | fzf --height 25% --reverse --prompt="Select worktree or Exit: ")

    if [[ "$selection" == "$exit_option" ]]; then
      # Use the correctly identified main repository root path
      echo "Navigating to main repository directory '$main_repo_root_path' and checking out '$main_branch'."
      cd "$main_repo_root_path" && git switch -f "$main_branch"
    elif [[ -n "$selection" ]]; then
      # Selection is a worktree name, reconstruct the path
      local selected_path="${worktree_base_dir}/${selection}"
      if [[ -d "$selected_path" ]]; then
         echo "Navigating to selected worktree: $selected_path"
         cd "$selected_path" || return 1
      else
         echo "System Alert: Selected worktree path '$selected_path' not found." >&2
         return 1
      fi
    else
       echo "No selection made."
    fi
  fi
  return 0
}

[medoror-mo]

Any updates on this? Imagine the desired functionality resembles this plugin that VS Code has for gitworktrees https://marketplace.visualstudio.com/items?itemName=GitWorktrees.git-worktrees

[fastjames]

Was this addressed in #4670 ?

[heksesang]

That issue only addressed the problem that you couldn't open a worktree directory in Zed with any sort of git support. This discussion is about making worktree-based workflows work more smoothly than they do today.

[heksesang]

Another issue steming from no worktree support in Zed is that if you do open a repository using worktrees in Zed and try to switch to a branch that you already have a worktree for, you get a very non-descriptive error that the checkout command failed. Not very good UX at all.

[aexvir]

with agentic development being more and more popular I'm finding worktrees to be essential for keeping parallel workstreams, so far I haven't seen any editor that embraces worktrees and offers a higher level control over these workstreams

this, in my mind, could align quite well with the vision that Nathan shared in the discussion with Steve, where perhaps collab channels could be used to define workstreams for agents to iterate on top of; if each channel would be backed up by its own worktree then features can be actually be built in parallel with little friction, be it with llms involved or not

for me an mvp of this would be some flag in the settings to let me manage branches as worktrees, so users that want will opt-in would get each branch in its own worktree; no changes on the ui, when switching branch it would switch worktree, creating and deleting branches would delete worktrees and so on

[jarlbrak]

with agentic development being more and more popular I'm finding worktrees to be essential for keeping parallel workstreams, so far I haven't seen any editor that embraces worktrees and offers a higher level control over these workstreams

this, in my mind, could align quite well with the vision that Nathan shared in the discussion with Steve, where perhaps collab channels could be used to define workstreams for agents to iterate on top of; if each channel would be backed up by its own worktree then features can be actually be built in parallel with little friction, be it with llms involved or not

for me an mvp of this would be some flag in the settings to let me manage branches as worktrees, so users that want will opt-in would get each branch in its own worktree; no changes on the ui, when switching branch it would switch worktree, creating and deleting branches would delete worktrees and so on

Check out Crystal. I use it when there is enough ambiguity in my prompt to warrant exploring different solutions from parallel workflows.

[AlvaroParker]

Hi! I've opened a draft PR #38719 although as a separate component to branches (similiar to how vscode does it for for > worktree ... commands).

[greg-truewind]

seems like with agentic development this is more needed as I see our engineers try to parallelize their workflows with multiple agents running. I think seamless switching between workspaces to help agent to progress on a task would be so powerful. conductor attempts to do this but it abstracts code editor entirely, I still want to be in the weeds of changing small code pieces as an agents run along in multiple worktrees

[plasticine]

Whatever gets built here it would be awesome if it could be generic or extensible enough to accomodate other worktree-ish workflows — Workspaces in Jujutsu for example 🙏