Worktrees

Overview

Worktrees provide a safe, isolated workspace for Friday sessions by creating a temporary copy of your repository. This feature allows you to run more than one Friday session on the same working directory at the same time in isolation. Changes happen in a separate directory that's automatically cleaned up when your session ends, and any uncommitted work is auto-committed before cleanup.

Note: Worktrees are created as sibling directories to your repository with the naming pattern: repo-name.worktree.YYYYMMDD-HHMMSS

Quick Start

  1. Navigate to your repository directory
  2. Start Friday with the --worktree or --wt flag
  3. Friday creates a temporary worktree and switches to it automatically
  4. Work on your tasks as normal
  5. When you exit Friday, the worktree is automatically cleaned up

Usage

Basic Usage

Create a worktree with an automatically generated branch name (format: worktree-branch-<random>):

friday --worktree

Or use the short form:

friday --wt

Friday automatically creates a new branch named worktree-branch-<5 char hex> (e.g. worktree-branch-a3f9c) for the worktree.

Specifying a Base Branch

Create a worktree based on a specific branch (checks local branches first, then remote):

friday --worktree main

friday --wt feature/my-branch

How It Works

  • When you start Friday with --worktree, it creates a new directory alongside your repository
  • The worktree is a full working copy that shares the same Git history as your main repository
  • All Friday operations happen in this isolated worktree
  • When you exit Friday, any uncommitted changes are automatically committed with message: WIP: auto-commit from worktree cleanup
  • Since the worktree runs on a named branch, your commits are always reachable; no orphaned commits
  • The worktree directory is then removed, but all commits remain in your Git history

Examples

Example 1: Quick Experimentation

You want to try out a new feature without affecting your current work:

# Start Friday in a worktree
friday --worktree

# Friday creates: ~/projects/my-app.worktree.20241024-143000
# Friday automatically creates a branch: worktree-branch-a3f9c
# You work on your feature...
# When done, exit Friday
# Worktree is automatically cleaned up; your commits remain on worktree-branch-a3f9c

Example 2: Working from a Specific Branch

You want to create a feature based on a specific branch:

# Start Friday with a branch
friday --worktree develop

# Friday creates a worktree based on the 'develop' branch
# Your changes will be based on develop's current state

Example 3: Directory Structure

Here's what your directory structure looks like when using worktrees:

~/projects/
  ├── my-app/                          # Your original repository
  │   ├── src/
  │   ├── tests/
  │   └── ...
  └── my-app.worktree.20241024-143000/  # Temporary worktree (auto-removed)
      ├── src/
      ├── tests/
      └── ...

Example 4: Finding Your Work After Cleanup

After the worktree is removed, your commits are still accessible on the auto-generated branch:

# Start Friday in a worktree
friday --worktree

# Make some changes...
# Exit Friday

# Friday automatically:
# 1. Commits any uncommitted changes with message: "WIP: auto-commit from worktree cleanup"
# 2. Removes the worktree directory
# Your work remains on the named branch (e.g. worktree-branch-a3f9c) in your Git history

Example 5: Combining with Autostart Mode

You can combine worktrees with the prompt flag to start working immediately:

friday --worktree -p "Add user authentication feature"

# Friday creates a worktree and immediately starts working on your request