Skip to content

TASKS.md

Latest commit

 

History

History
306 lines (244 loc) · 9.93 KB

TASKS.md

File metadata and controls

306 lines (244 loc) · 9.93 KB

Worktree CLI Development Tasks

Recent Enhancements 🎉

  • Module renamed to github.com/todoengineering/wt
  • Fixed bug where editor didn't open in tmux session context
  • Enhanced repository name detection for worktrees
  • Implemented TOML configuration system with XDG compliance
  • Added file copying feature for untracked files (.env, certificates, etc.)

Completed ✅

  • Initialize Go module structure
  • Set up Cobra CLI framework
  • Create project directory structure
  • Implement basic worktree list command
    • Check if in Git repository
    • Get repository name
    • List worktrees from standard directory
    • Sort worktrees alphabetically

Core Commands ✅

worktree new <name>

  • Validate Git repository context
  • Create new Git branch
  • Create worktree directory structure
  • Run git worktree add command
  • Open in configured editor ($EDITOR)
  • Create/switch tmux session
  • Handle interactive mode (prompt for name)
  • Copy configured files to new worktree

worktree switch [name]

  • Interactive worktree selection with fzf
  • Direct selection by name
  • Open in configured editor
  • Create/switch tmux session
  • Handle editor in tmux session context

worktree open ✅

  • Check fzf availability
  • List all projects in worktree base directory
  • Interactive project selection with fzf
  • List worktrees for selected project
  • Interactive worktree selection with fzf
  • Open in configured editor
  • Create/switch tmux session

worktree checkout ✅

  • Check fzf availability
  • Fetch remote branches
  • List all branches (local and remote)
  • Filter out current branch and HEAD
  • Interactive branch selection with fzf
  • Check if worktree already exists
  • Create worktree for selected branch
  • Handle special characters in branch names
  • Open in configured editor
  • Create/switch tmux session

worktree delete ✅

  • Check fzf availability
  • List all worktrees for current repo
  • Interactive worktree selection with fzf
  • Show confirmation prompt
  • Validate confirmation input
  • Prevent deletion of main worktree
  • Run git worktree remove --force
  • Clean up orphaned directories

CLI Simplification & UX 🧭

Goal: Make the tool simpler and more intuitive by consolidating overlapping commands, introducing consistent flags, and clarifying defaults. This plan captures the intended changes with examples and acceptance criteria.

Command Consolidation

  • Collapse wt switch into wt open

    • Behavior: wt open opens an existing worktree and switches/creates a tmux session, and opens the editor (current behavior of both open and switch).
    • Scope default: If inside a Git repo, list that repo’s worktrees; if outside, list across projects.
    • Remove wt switch command entirely (no deprecation alias needed).
    • Acceptance:
      • Running wt open in a repo shows only that repo’s worktrees.
      • Running wt open --all shows a project → worktree picker across all projects.
      • wt switch command is no longer available.

  • Rename wt checkout to wt branch OR merge into wt new --from

    • Chosen: Option A - Merge into wt new with a --from <branch> flag to attach a new worktree to an existing branch.
      • Example: wt new feature-login --from origin/feature-login
      • Example: wt new --from origin/release-1.2 (auto name from branch)
      • Benefit: Fewer top-level commands; a single verb to “add a worktree”.
    • Acceptance:
      • Users can create a worktree from an existing branch via new --from.
      • Existing “worktree already exists” detection still offers to switch instead of duplicating.
    • Notes:
      • Removed checkout command (no deprecation alias needed; not yet live).

Common Flags (consistent behavior)

  • --no-editor: Skip launching the editor after create/open

    • Applies to: open, new
    • Example: wt open --no-editor

  • --no-tmux: Skip creating/switching tmux sessions

    • Applies to: open, new
    • Example: wt new ticket-42 --no-tmux

  • --force on delete: Skip confirmation prompt

    • Applies to: delete
    • Example: wt delete ticket-42 --force

  • Scope flags

  • --all for cross-project operations

    • Applies to: open, list
    • Examples:
      • wt open --all → project → worktree picker across all projects
      • wt list --all → list all projects and their worktrees

  • --project <name> to filter to a specific repository (when outside any repo)

    • Applies to: open, list
    • Status: Implemented for open (flag --project); pending for list.
    • Example: wt open --project my-repo

  • Output flags for scripting on list

  • --json → machine-readable output

  • --path-only → just the filesystem paths (one per line)

    • Examples:
      • wt list --json | jq '.'
      • wt list --path-only | xargs -I{} du -sh {}

Default Behavior Adjustments

  • open default scope:

    • In a repo → list only that repo’s worktrees (skip project selection).
    • Outside a repo → show project → worktree interactive selection.
    • Acceptance: Behavior matches above without requiring flags.

  • open <worktree-name> shortcut when inside a repo

    • Example: wt open feature-x jumps directly if it exists; otherwise shows friendly error with suggestions.

  • open --all accepts <repo>/<worktree> to jump directly

    • Example: wt open --all my-repo/feature-x

Aliases (optional)

  • ls → list
  • rm → delete

Bugs

  • When i run "wt open --all --json" is doesn't output json

Migration Guide (add to README)

  • Before → After
    • wt switch → wt open (or wt open --all outside a repo)
    • wt checkout → wt new --from <branch>
    • wt list → unchanged; add --all, --json, --path-only
    • wt delete → unchanged; add --force

Examples:

# Open an existing worktree in current repo
wt open
wt open payment-refactor

# Open across projects
wt open --all
wt open --all my-repo/payment-refactor

# Create worktree on a new branch
wt new feature/signup-flow

# Create worktree from an existing branch
wt new release-1.2 --from origin/release-1.2

# List worktrees
wt list
wt list --all
wt list --json
wt list --path-only

# Delete worktree
wt delete feature/signup-flow
wt delete feature/signup-flow --force

# Suppress integrations when desired
wt open --no-editor
wt new feature/foo --no-tmux

Deprecation Strategy

  • Print a one-line deprecation notice when switch or checkout are used, pointing to the replacement command.
  • Keep aliases for at least one minor release cycle.
  • Update --help for root and affected commands with new flags and examples.

Implementation Checklist

  • Wire --no-editor and --no-tmux through editor/tmux helpers without breaking defaults.
  • Add --all and --project plumbing to open/list selection paths.
  • Add JSON and path-only output modes to list with stable schema.
  • Rename checkout → branch OR add --from to new and remove checkout.
  • Implement aliasing + deprecation messages.
  • Update README command docs and usage examples.
  • Consider shell completions update once flags settle (bash/zsh/fish).

Integration Features 🔧

Editor Integration

  • Read $EDITOR environment variable
  • Parse editor command with flags
  • Validate editor availability
  • Handle editor launch errors
  • Support common editors (code, vim, emacs, etc.)

Tmux Integration

  • Check if tmux is installed
  • Detect if running inside tmux
  • Create detached tmux sessions
  • Switch between tmux sessions
  • Attach to tmux sessions from outside
  • Handle session name conflicts

Utility Functions 📦

Git Operations

  • Check Git installation
  • Validate Git repository
  • Get current branch
  • List local branches
  • List remote branches
  • Create new branches
  • Run worktree commands

File System

  • Create directory structures
  • Clean up orphaned directories
  • Validate paths
  • Handle permissions errors

Interactive UI

  • Check fzf installation
  • Create fzf selection interfaces
  • Handle user input prompts
  • Display progress indicators
  • Show error messages

Configuration 🔧

  • Support WORKTREE_BASE_DIR environment variable
  • Default to ~/projects/worktrees
  • Validate configuration values
  • Handle missing configuration gracefully
  • XDG-compliant config file support (TOML)
  • Global config at ~/.config/wt/config.toml
  • Local project config at .wt.toml
  • Config merging (local overrides/extends global)
  • Configurable worktrees location
  • Copy files to new worktrees (copy_files config)
  • Support glob patterns in copy_files

Error Handling 🛡️

  • Validate all dependencies on startup
  • Provide clear error messages
  • Handle edge cases gracefully
  • Add recovery suggestions
  • Log errors appropriately

Testing 🧪

  • Unit tests for Git operations
  • Unit tests for worktree management
  • Integration tests for commands
  • Test tmux integration
  • Test editor integration
  • Test error scenarios

Documentation 📚

  • Write README with installation instructions
  • Document all commands with examples
  • Create man page
  • Add inline help text
  • Document configuration options

Build & Release 🚀

  • Set up build scripts
  • Create Makefile
  • Configure CI/CD pipeline
  • Create release binaries for multiple platforms
  • Set up versioning strategy
  • Create installation script

Future Enhancements 💡

  • Shell completions (bash, zsh, fish)
  • Worktree status command
  • Sync command for updating worktrees
  • Config file support (TOML) - Completed
  • Parallel worktree operations
  • Cleanup command for orphaned worktrees
  • Integration hooks for IDEs
  • Worktree templates