> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibetunnel.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Git worktree follow mode

# Git Worktree Follow Mode Specification

## Overview

Follow mode is a feature that enables automatic synchronization between Git worktrees and the main repository. It ensures team members stay on the same branch by automatically switching branches when changes are detected.

## Core Concept

Follow mode creates a **unidirectional sync** from a worktree to the main repository:

* When someone switches branches in a worktree
* The main repository automatically follows that branch change
* This keeps the main repository synchronized with active development

## When Follow Mode Should Be Available

### ✅ Follow Mode SHOULD appear when:

1. **Creating a session in a worktree**
   * You've selected a worktree from the dropdown
   * The session will run in that worktree's directory
   * Follow mode will sync the main repository to match this worktree's branch

2. **Viewing worktrees in the Worktree Manager**
   * Each worktree (except main) shows a "Follow" button
   * Enables following that specific worktree's branch

3. **Session list with worktree sessions**
   * Repository headers show follow mode status
   * Dropdown allows changing which worktree to follow

### ❌ Follow Mode should NOT appear when:

1. **No worktree is selected** (using main repository)
   * There's nothing to follow - you're already in the main repo
   * Follow mode has no purpose without a worktree

2. **Repository has no worktrees**
   * No worktrees exist to follow
   * Only the main repository is available

3. **Not in a Git repository**
   * Obviously, no Git features available

## UI Behavior Rules

### Session Creation Form

```typescript theme={null}
// Show follow mode toggle only when:
const showFollowModeToggle = 
  gitRepoInfo?.isGitRepo && 
  selectedWorktree !== undefined &&
  selectedWorktree !== 'none';
```

#### Toggle States:

1. **Worktree Selected**:
   * Show: "Follow Mode" toggle
   * Description: "Keep main repository in sync with this worktree"
   * Default: OFF (user must explicitly enable)

2. **No Worktree Selected**:
   * Hide the entire follow mode section
   * No toggle should be visible

3. **Follow Mode Already Active**:
   * Show: "Follow Mode" toggle (disabled)
   * Description: "Currently following: \[branch-name]"
   * Info: User must disable from worktree manager

### Worktree Manager

Each worktree row shows:

* **"Follow" button**: When not currently following
* **"Following" button** (green): When actively following this worktree
* **No button**: For the main worktree (can't follow itself)

### Session List

Repository headers show:

* **Purple badge**: When follow mode is active, shows branch name
* **Dropdown**: To change follow mode settings per repository

## Technical Implementation

### State Logic

```typescript theme={null}
// Follow mode is only meaningful when:
// 1. We have a worktree to follow
// 2. We're not already in that worktree
// 3. The main repo can switch to that branch

const canEnableFollowMode = (
  worktree: Worktree,
  currentLocation: string,
  mainRepoPath: string
) => {
  // Can't follow if we're in the main repo with no worktree selected
  if (currentLocation === mainRepoPath && !worktree) {
    return false;
  }
  
  // Can't follow the main worktree
  if (worktree.isMainWorktree) {
    return false;
  }
  
  // Can follow if we're creating a session in a worktree
  if (worktree && currentLocation === worktree.path) {
    return true;
  }
  
  return false;
};
```

### Configuration Storage

Follow mode state is stored in Git config:

```bash theme={null}
# Enable follow mode for a branch
git config vibetunnel.followBranch "feature/new-ui"

# Check current follow mode
git config vibetunnel.followBranch

# Disable follow mode
git config --unset vibetunnel.followBranch
```

### Synchronization Rules

1. **Automatic Sync**:
   * Triggered by `post-checkout` git hook in worktrees
   * Only syncs if main repo has no uncommitted changes
   * Disables follow mode if branches have diverged

2. **Manual Override**:
   * Users can always manually switch branches
   * Follow mode doesn't prevent manual git operations
   * Re-enables when returning to the followed branch

## User Experience Guidelines

### Clear Messaging

1. **When Enabling**:
   * "Follow mode will keep your main repository on the same branch as this worktree"
   * "Enable to automatically sync branch changes"

2. **When Active**:
   * "Following worktree: feature/new-ui"
   * "Main repository syncs with this worktree's branch"

3. **When Disabled**:
   * "Follow mode disabled due to uncommitted changes"
   * "Branches have diverged - follow mode disabled"

### Visual Indicators

* **Toggle Switch**: Only visible when applicable
* **Status Badge**: Purple badge with branch name when active
* **Button States**: Clear "Follow"/"Following" states in worktree manager

## Error Handling

### Common Scenarios

1. **Uncommitted Changes**:
   * Disable follow mode automatically
   * Show notification to user
   * Don't lose any work

2. **Branch Divergence**:
   * Detect when branches have different commits
   * Disable follow mode to prevent conflicts
   * Notify user of the situation

3. **Worktree Deletion**:
   * Automatically disable follow mode
   * Clean up git config
   * Update UI immediately

## Summary

Follow mode should be:

* **Contextual**: Only shown when it makes sense
* **Safe**: Never causes data loss or conflicts
* **Clear**: Users understand what it does
* **Automatic**: Works in the background when enabled

The key principle: **Follow mode only exists when there's a worktree to follow**. Without a worktree selection, the feature should not be visible or accessible.