Skip to content

Workspace Manager (ws)

A CLI tool for managing git workspaces and worktrees, designed for working on multiple branches across repositories.

Installation

  • uv is assumed to be installed
  • ws just needs to be put on your $PATH, I symlink to ~/.local/bin/ws with stow

Core Concepts

  • Workspace: A folder containing worktrees for a specific task/ticket
  • Worktree: A git worktree allowing multiple branches to be checked out simultaneously
  • Areas: Workspaces are organized into personal and work areas

Commands

Create & Manage Workspaces

ws create                    # Interactive workspace creation
ws create work TICKET-123    # Create workspace with args
ws add                       # Add worktree to workspace (interactive)
ws list                      # List all workspaces and their worktrees
ws close                     # Remove workspace and all worktrees

ws open                      # Open workspace in tmux (picker)
ws open -a                   # Open any repo/workspace (ta replacement)
ws open TICKET-123          # Open specific workspace

Git Integration

ws git                       # Open lazygit in current repo or pick from workspace
ws status                    # Show workspaces with uncommitted changes
ws status -v                 # Detailed table with branches, changes, commits

Workflow Example

# Create workspace for a new ticket
ws create work TICKET-456 "Fix authentication bug"

# Add worktrees for the repos you need
ws add work TICKET-456       # Interactive: pick repo & branch
# Creates: ~/projects/work.workspaces/TICKET-456/backend-feature-auth

# Open workspace in tmux
ws open TICKET-456

# Check status across all worktrees
ws status -v

# When done, clean up
ws close work TICKET-456

Directory Structure

~/projects/
 personal/                 # Personal repos
 work/                     # Work repos
 personal.workspaces/      # Personal workspaces
    my-feature/
        repo1-main/
        repo1-feature/
 work.workspaces/         # Work workspaces
     TICKET-123/
         backend-main/
         backend-feature-auth/
         frontend-develop/

Features

  • Branch-specific folders: Multiple branches from same repo (e.g., backend-main, backend-feature)
  • Smart detection: Commands detect if you're in a workspace/repo and act accordingly
  • FZF integration: Interactive selection with fuzzy finding
  • Tmux integration: Seamless session management
  • .envrc propagation: Copies .envrc files from parent repos to worktrees

Tips

  • Use ws git in tmux for quick lazygit access (bind to prefix + C-k)
  • Run ws status -v for end-of-day review