Configuration Guide

This guide explains how to configure Phantom using the phantom.config.json file to customize behavior and automate workflows.

Table of Contents

• Overview
• Configuration File Location
• Configuration Options
  • worktreesDirectory
  • postCreate.copyFiles
  • postCreate.commands
  • preDelete.commands
• Examples
• Best Practices
• Troubleshooting

Overview

Phantom supports project-specific configuration through a phantom.config.json file. This allows you to:

• Customize where worktrees are created
• Automatically copy files to new worktrees
• Run commands after creating worktrees
• Standardize team workflows

Configuration File Location

The phantom.config.json file should be placed in your repository root:

your-project/
├── .git/
├── phantom.config.json   # Configuration file here
├── package.json
└── src/

Configuration Options

Complete Configuration Schema

{
  "worktreesDirectory": "string (optional)",
  "postCreate": {
    "copyFiles": ["array", "of", "file", "paths"],
    "commands": ["array", "of", "shell", "commands"]
  },
  "preDelete": {
    "commands": ["array", "of", "shell", "commands"]
  }
}

worktreesDirectory

Specifies a custom directory where phantom worktrees will be created.

Type: string (optional)

Default: .git/phantom/worktrees

Description: By default, Phantom creates all worktrees inside the Git directory. You can use this option to store worktrees in a different location.

Relative Path Example

{
  "worktreesDirectory": "../phantom-worktrees"
}

This creates the following structure:

parent-directory/
├── your-project/
│   ├── .git/
│   └── phantom.config.json
└── phantom-worktrees/
    ├── feature-1/
    ├── feature-2/
    └── bugfix-login/

Absolute Path Example

{
  "worktreesDirectory": "/home/user/phantom-worktrees"
}

Use Cases:

• Keep worktrees outside the main repository
• Use a faster SSD for worktrees
• Share worktree location across projects
• Organize worktrees in a custom structure

postCreate.copyFiles

Automatically copy files from the current worktree to newly created phantoms.

Type: string[] (optional)

Default: []

Description: Lists files that should be copied when creating a new phantom. This is useful for environment files, local configurations, and other files that are not committed to Git.

Example

{
  "postCreate": {
    "copyFiles": [
      ".env",
      ".env.local",
      "config/local.json",
      "certificates/dev.pem"
    ]
  }
}

Common Use Cases:

• Environment variables (.env files)
• Local development settings
• API keys and secrets
• SSL certificates
• Database configuration
• IDE settings

Notes:

• Paths are relative to repository root
• Files that don't exist are silently skipped
• Directories are not supported (only files)
• Overrides command-line --copy-file options

postCreate.commands

Run shell commands automatically after creating a phantom.

Type: string[] (optional)

Default: []

Description: Lists commands to execute in the new phantom directory after it's created. Commands run in order and stop on the first failure.

Example

{
  "postCreate": {
    "commands": [
      "pnpm install",
      "pnpm build",
      "pnpm db:migrate",
      "echo 'Phantom ready!'"
    ]
  }
}

Common Use Cases:

• Install dependencies
• Build the project
• Run database migrations
• Generate configuration files
• Set up development environment
• Start background services

Notes:

• Commands run in the phantom's directory
• Output is displayed in real-time
• Execution stops on first error
• Use && to chain dependent commands

preDelete.commands

Run shell commands automatically before deleting a phantom.

Type: string[] (optional)

Default: []

Description: Lists commands to execute in the phantom directory before it's deleted. This is useful for cleanup operations like stopping services, removing temporary files, or saving state.

Example

{
  "preDelete": {
    "commands": [
      "docker-compose down",
      "rm -rf temp",
      "echo 'Cleaning up phantom...'"
    ]
  }
}

Common Use Cases:

• Stop Docker containers
• Clean up temporary files
• Save logs or state
• Terminate background processes
• Remove generated files
• Backup local data

Notes:

• Commands run in the phantom's directory
• Execution continues even if commands fail
• Runs before both manual deletion and forced deletion
• Output is displayed in real-time

Examples

Web Development Project

{
  "worktreesDirectory": "../phantoms",
  "postCreate": {
    "copyFiles": [
      ".env.local",
      ".env.development"
    ],
    "commands": [
      "npm install",
      "npm run build",
      "npm run db:setup"
    ]
  }
}

Monorepo Project

{
  "postCreate": {
    "copyFiles": [
      ".env",
      "packages/api/.env.local",
      "packages/web/.env.local"
    ],
    "commands": [
      "pnpm install",
      "pnpm -r build",
      "pnpm --filter api db:migrate"
    ]
  }
}

Machine Learning Project

{
  "worktreesDirectory": "/mnt/fast-ssd/ml-phantoms",
  "postCreate": {
    "copyFiles": [
      "config/local.yaml",
      "credentials/gcp-key.json"
    ],
    "commands": [
      "python -m venv venv",
      "source venv/bin/activate && pip install -r requirements.txt",
      "source venv/bin/activate && python setup.py develop"
    ]
  }
}

Docker-based Project

{
  "postCreate": {
    "copyFiles": [
      ".env",
      "docker-compose.override.yml"
    ],
    "commands": [
      "docker-compose pull",
      "docker-compose build",
      "docker-compose run --rm app bundle install",
      "docker-compose run --rm app rails db:setup"
    ]
  },
  "preDelete": {
    "commands": [
      "docker-compose down -v",
      "docker system prune -f"
    ]
  }
}

Complete Example with All Options

{
  "worktreesDirectory": "../phantoms",
  "postCreate": {
    "copyFiles": [
      ".env",
      ".env.local",
      "config/secrets.json"
    ],
    "commands": [
      "pnpm install",
      "pnpm build",
      "docker-compose up -d"
    ]
  },
  "preDelete": {
    "commands": [
      "docker-compose down",
      "rm -rf node_modules/.cache",
      "rm -rf tmp/*"
    ]
  }
}

Best Practices

1. Version Control

Do: Commit phantom.config.json to version control

git add phantom.config.json
git commit -m "Add phantom configuration"

Don't: Include sensitive data in configuration

{
  "postCreate": {
    "commands": [
      "export API_KEY=secret123"  // Don't do this!
    ]
  }
}

2. Team Standardization

Create a configuration that works for all team members:

{
  "postCreate": {
    "copyFiles": [
      ".env.example"  // Rename to .env after copying
    ],
    "commands": [
      "cp .env.example .env",
      "npm install",
      "npm run setup"
    ]
  }
}

3. Performance Optimization

Place worktrees on fast storage:

{
  "worktreesDirectory": "/mnt/nvme/phantoms"
}

4. Cross-Platform Compatibility

Use cross-platform commands:

{
  "postCreate": {
    "commands": [
      "npm install",         // Works everywhere
      "npm run build"        // Let npm handle platform differences
    ]
  }
}

5. Error Handling

Add error checking to commands:

{
  "postCreate": {
    "commands": [
      "test -f .env || cp .env.example .env",
      "npm install || echo 'Install failed, continuing...'",
      "npm run build"
    ]
  }
}

Troubleshooting

Configuration Not Loading

1. Check file location (must be in repository root)
2. Verify JSON syntax:

   cat phantom.config.json | jq .
   

3. Check for typos in property names

Commands Failing

1. Test commands manually first:

   phantom create test-phantom
   cd $(phantom where test-phantom)
   # Run your commands here
   

2. Add debugging output:

   {
     "postCreate": {
       "commands": [
         "echo 'Current directory:' && pwd",
         "echo 'Node version:' && node --version",
         "npm install"
       ]
     }
   }
   

File Copy Issues

1. Check file paths are relative to repository root
2. Verify files exist in source worktree
3. Check file permissions

Performance Issues

If post-create commands are slow:

1. Move heavy operations to background:

   {
     "postCreate": {
       "commands": [
         "npm install",
         "nohup npm run build &"
       ]
     }
   }
   

2. Use faster package managers:

   {
     "postCreate": {
       "commands": [
         "pnpm install"  // Faster than npm
       ]
     }
   }
   

Advanced Patterns

Conditional Setup

{
  "postCreate": {
    "commands": [
      "[ -f package-lock.json ] && npm ci || npm install",
      "[ -f Gemfile.lock ] && bundle install || echo 'No Gemfile'",
      "[ -d .git/hooks ] && npm run setup:hooks || true"
    ]
  }
}

Environment-Specific Configuration

While phantom.config.json doesn't support environment variables directly, you can use commands:

{
  "postCreate": {
    "commands": [
      "[ \"$NODE_ENV\" = 'production' ] && npm run build:prod || npm run build:dev"
    ]
  }
}

Integration with CI/CD

{
  "worktreesDirectory": "../ci-phantoms",
  "postCreate": {
    "commands": [
      "npm ci",
      "npm run lint",
      "npm test"
    ]
  }
}

Summary

The phantom.config.json file provides powerful automation capabilities:

• worktreesDirectory: Control where phantoms are created
• postCreate.copyFiles: Automate environment setup
• postCreate.commands: Run setup commands automatically

This configuration system helps teams maintain consistent development environments and reduces manual setup time when creating new phantoms.