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
}