708u Twig Twig Guide

twig CLI Guide

twig is a CLI tool that simplifies git worktree workflows by automating branch creation, symlinks, and change management in a single command.

Commands Overview

Typical Workflows

Start new feature work

Create a new worktree for a feature branch:

twig add feat/new-feature

This creates a worktree at the configured destination directory, creates a new branch if it doesn't exist, and sets up symlinks.

Move current changes to a new branch

When you realize current work should be on a different branch:

twig add feat/correct-branch --carry

The --carry flag moves uncommitted changes to the new worktree. The source worktree becomes clean.

Copy changes to a new branch

When you want changes in both the current and new worktree:

twig add feat/experiment --sync

The --sync flag copies uncommitted changes to both worktrees.

Carry only specific files

When you want to carry only certain files:

twig add feat/new --carry --file "*.go" --file "cmd/**"

Clean up after merging

Remove worktrees for branches that have been merged:

twig clean

This shows candidates and prompts for confirmation. Use --yes to skip the prompt.

Test a feature branch in another worktree

Temporarily apply another branch's file contents:

twig overlay feat/x --target main
# ... test in main worktree ...
twig overlay --restore --target main

Test uncommitted changes in another worktree

Include dirty (uncommitted) files from the source worktree:

twig overlay feat/x --target main --dirty
# ... test including uncommitted changes ...
twig overlay --restore --target main

This also works when source and target are at the same commit (only dirty files are applied).

Force remove a worktree

Remove a worktree even with uncommitted changes:

twig remove feat/abandoned -f

Use -ff to also remove locked worktrees.

Configuration

see ./references/configuration.md

Command Details

For detailed information on each command, refer to:

• ./references/commands/add.md - Create worktrees with sync/carry options
• ./references/commands/remove.md - Remove worktrees and branches
• ./references/commands/list.md - List worktrees
• ./references/commands/clean.md - Clean merged worktrees
• ./references/commands/sync.md - Sync symlinks and submodules
• ./references/commands/overlay.md - Overlay branch files temporarily
• ./references/commands/init.md - Initialize configuration
• ./references/configuration.md - Configuration file details

Converted and distributed by TomeVault — claim your Tome and manage your conversions.