GitHub - aureliensibiril/portal: Portal is a modern CLI tool for managing Git worktrees with automatic color coding and editor integration.

⛩️ Portal - Git Worktree Manager

Portal is a modern CLI tool for managing Git worktrees with automatic color coding and editor integration. Each worktree gets a deterministic color that syncs across your terminal, IDE, and CLI output, making it easy to identify which worktree you're working in.

Why Portal?

Managing multiple worktrees with raw git worktree commands means juggling paths, remembering branches, and manually setting up each environment from scratch. Portal automates all of this: create a worktree, and it automatically copies your .env, installs dependencies, assigns a unique color to your iTerm tab and IDE theme, and opens your editor — all with a single command and a one-time config file.

Features

• Deterministic color coding — each worktree gets a consistent color across iTerm tabs, VS Code/Cursor themes, and CLI output
• Powerful hook system — automate worktree setup with file copies, dependency installs, environment config, and more
• Interactive TUI — arrow-key navigation with color-highlighted worktree entries and action submenus
• Editor integration — open worktrees directly in Cursor or VS Code with matching color themes
• Terminal integration — open worktrees in new iTerm tabs with colored tab indicators
• Project-level config — drop a .portal.yml in any repo for project-specific automation
• Shell completions — tab completion for Bash and Zsh, plus a pw alias for quick switching

Installation

# With uv (recommended)
uv tool install git-portal[cli]

# With pipx
pipx install git-portal[cli]

# With Homebrew (macOS)
brew tap aureliensibiril/portal
brew install portal

git clone https://github.com/aureliensibiril/portal.git
cd portal
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[cli]"

Then install shell completions:

Quick Start

# Open the interactive menu
portal

# Create a new worktree (auto-sets up hooks, colors, and opens your editor)
portal new feature/awesome-feature

# Create from a specific base branch
portal new hotfix/urgent-fix --base release-v2.0

# Switch to an existing worktree
portal switch feature/auth

# Open a worktree in a new iTerm tab with its assigned color
portal terminal feature/payments

# Open a worktree in Cursor with a matching color theme
portal cursor feature/payments

# Delete a worktree (runs cleanup hooks)
portal delete feature/old --force

Hooks

Portal can automatically set up each new worktree using a .portal.yml file in your project root:

hooks:
  post_create:
    - type: copy
      config:
        from: ".env.example"
        to: ".env"

    - type: command
      config:
        command: "npm install"
      condition: "file_exists:package.json"

    - type: env_update
      config:
        file: ".env"
        updates:
          DATABASE_NAME: "{{project}}_{{worktree_name}}_dev"
          API_PORT: "auto"

Hooks support 8 operation types, conditional execution, variable substitution, and error handling. See the Hook System documentation for the full reference.

Documentation

• Command Reference — all commands and options
• Configuration Guide — YAML config and settings
• Hook System — automation, variables, conditions, and examples
• Tips & Tricks — aliases and hook recipes
• Troubleshooting — common issues and debugging

License

MIT License - see LICENSE for details.