Worktree Workflow

Nanx provides powerful git worktree support, allowing you to work on multiple branches simultaneously without stashing or switching. Each branch gets its own directory, and nanx handles all the complexity automatically.

What is Worktree Mode?

Git worktrees allow you to have multiple working directories attached to the same repository. Instead of switching branches and losing your current work state, you can:

• Have main, feature/auth, and bugfix/login open simultaneously
• Keep your IDE open in one branch while testing another
• Run tests in one worktree while developing in another
• Never lose work due to branch switching

Directory Structure

When you clone with worktree mode, nanx creates this structure:

~/projects/
  my-project.repo/          # Bare repository (git data only)
  main.my-project/          # Worktree for main branch
  feature-auth.my-project/  # Worktree for feature/auth branch
  bugfix-login.my-project/  # Worktree for bugfix/login branch

Getting Started

Clone with Worktree Mode

Clone a repository with worktree support enabled:

# Clone with worktree mode (recommended)
nanx r clone https://github.com/org/repo.git

# Clone to specific directory
nanx r clone https://github.com/org/repo.git ~/projects/my-project

Nanx automatically detects if you want worktree mode and creates:

1. A bare repository (my-project.repo/)
2. A worktree for the default branch (main.my-project/)
3. Registers the repository in your global repos list

Initialize Existing Repository

Convert an existing repository to worktree mode:

# In your existing repository
nanx r init --worktree

Branch Switching

When in worktree mode, switching branches automatically creates worktrees instead of changing your current directory's state:

Create New Branch

# Create and switch to new branch (creates worktree)
nanx r switch -c feature/new-feature

# With a base branch
nanx r switch -c feature/new-feature origin/develop

Switch to Existing Branch

# Switch to existing branch (creates worktree if needed)
nanx r switch develop

# List all worktrees
nanx r worktree list

Branch Name Formatting

Worktree directories use a readable format with the branch name reversed for better organization. The most specific part comes first:

Setup File Copying

When creating a new worktree, nanx can automatically copy setup files like .env from an existing worktree. This saves you from manually copying configuration files every time you start a new branch.

Configure Copy Files

In your .repo.yml (shared with team):

# .repo.yml
worktree:
  copy_files:
    - ".env"
    - ".env.local"
    - "apps/server/.env"
    - ".vscode/settings.json"

Or in ~/.nanx/repos.yml (personal settings):

# ~/.nanx/repos.yml
repositories:
  - slug: my-project
    worktree:
      copy_files:
        - ".env"
        - ".env.local"
        - "secrets/local.json"

Source Priority

When copying files, nanx looks for a source worktree in this order:

1. --copy-from flag: Explicitly specified branch
2. Current worktree: The worktree you're switching from
3. Default branch: main or master worktree

# Copy .env from develop branch specifically
nanx r switch -c feature/new --copy-from develop

# Let nanx auto-detect source (current or main)
nanx r switch -c feature/new

Copy Behavior

• Files are only copied if they exist in the source worktree
• Existing files in the target are never overwritten
• Configs from .repo.yml and repos.yml are merged

Actions on Switch

Nanx can automatically perform actions when switching to a worktree. The behavior adapts to your environment (SSH, desktop, terminal).

Action Types

Command Line Flags

# Force open in editor
nanx r switch -c feature/new --editor
nanx r switch -c feature/new -e

# No action, just create worktree
nanx r switch -c feature/new --no-action

# Legacy: prevent auto-cd (same as --no-action)
nanx r switch -c feature/new --no-cd

Configure Default Action

Set your preferred action in ~/.nanx/repos.yml:

# ~/.nanx/repos.yml
settings:
  on_switch_action: auto  # auto | editor | cd | none
  editor: cursor          # Editor to use for 'editor' action

Environment Detection

When using auto action, nanx detects your environment to choose the best action:

• SSH session: Uses cd (opens subshell)
• Desktop with GUI editor: Uses editor
• Terminal-only: Uses cd
• Non-interactive: Uses none (prints path)

Configuration

Repository Config (.repo.yml)

Shared with your team, stored in the repository:

# .repo.yml
worktree:
  copy_files:
    - ".env.example"
    - "docker-compose.override.yml"

Global Config (~/.nanx/repos.yml)

Personal settings, stored in your home directory:

# ~/.nanx/repos.yml
settings:
  on_switch_action: auto
  editor: cursor

repositories:
  - slug: my-project
    worktree:
      copy_files:
        - ".env"
        - ".env.local"

Edit Configuration

# Edit global repos config (personal)
nanx config repos --global

# Edit local .repo.yml (shared)
nanx config repos --local

# Show config file paths
nanx config repos --path

# Create config if not exists
nanx config repos --create

Common Workflows

Feature Development

# Start new feature from main
nanx r switch -c feature/user-auth

# Work on feature...
# Worktree auto-opens in editor with .env copied

# Switch to another task without losing state
nanx r switch -c bugfix/login-fix

# Go back to feature (worktree already exists)
nanx r switch feature/user-auth

Code Review

# Review a PR while keeping your work
nanx r switch pr-123-feature

# Run tests in the PR branch
npm test

# Switch back to your work
nanx r switch feature/my-work

Hotfix Workflow

# Quick hotfix from main
nanx r switch -c hotfix/urgent-fix --copy-from main

# Fix the issue
nanx r acgm "fix critical bug"
nanx r push

# Return to feature work
nanx r switch feature/my-work

Worktree Commands

Troubleshooting

Worktree Already Exists

If you get an error about a worktree already existing:

# List all worktrees
nanx r worktree list

# Remove stale worktree
nanx r worktree remove /path/to/worktree

# Or prune all stale worktrees
nanx r worktree prune

Files Not Being Copied

Check your configuration:

# Show config paths
nanx config repos --path

# Verify copy_files is configured
cat ~/.nanx/repos.yml
cat .repo.yml

Editor Not Opening

# Check configured editor
nanx config get editor::default

# Set editor
nanx config set editor::default cursor --global

# Or use environment variable
export NANX_EDITOR=code

Not in Worktree Mode

If commands don't create worktrees, you may not be in worktree mode:

# Check if in worktree mode (look for bare repo)
git rev-parse --is-bare-repository

# Initialize worktree mode
nanx r init --worktree

Best Practices

1. Use Descriptive Branch Names

Branch names become directory names, so use clear, organized naming:

# Good - creates organized directories
feature/user-auth
bugfix/issue-123-login
release/v2.0

# Less ideal - creates flat directories
user-auth
fix-login

2. Configure Setup Files

Add commonly-needed files to copy_files:

worktree:
  copy_files:
    - ".env"
    - ".env.local"
    - ".vscode/settings.json"
    - "docker-compose.override.yml"

3. Clean Up Old Worktrees

Periodically prune worktrees for merged branches:

# List worktrees
nanx r worktree list

# Remove old ones
nanx r worktree remove /path/to/old-feature
nanx r worktree prune

4. Use Auto Action

The auto action adapts to your environment, making it the best choice for most users.

Next Steps

• Git Workflow Guide
• Repository Configuration
• Config Commands
• Repository Commands