Global Flags

Command-line flags and options for GWTree commands

Overview

GWTree supports global flags that modify command behavior. Flags can be used with specific commands to override configuration settings or change execution flow.

Global Flags

Help and Version

These flags work with any command:

-h, --help · flag

Display help information for the command.

gwt --help
gwt list --help
gwt merge --help

-v, --version · flag

Output the current version number.

gwt --version
# Output: 2.0.0

gwt -v
# Output: 2.0.0

Create Command Flags

These flags modify the behavior of the default create command:

-y, —yes

-y, --yes · flag

Use saved defaults and skip all interactive prompts.

Skips prompts for:

• Uncommitted changes handling
• Branch switching
• Pull from remote
• Worktree/branch naming (requires name argument)

Still uses:

• Configured editor
• Configured dependency installation
• Detected package manager

Usage:

# Quick create with defaults
gwt feature-auth -y

# Batch create with defaults
gwt feat-a feat-b feat-c -y

Behavior with -y:

Prompt	Without -y	With -y
Uncommitted changes	Asks to stash	Auto-stashes
Not on main	Asks to switch	Auto-switches
Pull from remote	Asks to pull	Auto-pulls
Worktree name	Prompts	Uses argument

Example output:

gwt feature-login -y

┌  Create Git Worktree
│
│  ◆  Stash  git stash
│  └  saves uncommitted changes
│
│  ◆  Switch  git checkout main
│  └  switches to base branch
│
│  ◆  Pull  git pull --rebase origin main
│  └  fetches latest changes
│
│  Creating myapp-feature-login branch feature-login from main
│
│  ◆  Create  git worktree add -b "feature-login" .../myapp-feature-login "main"
│  └  /Users/john/projects/myapp-feature-login
│
└  Done  cd ../myapp-feature-login

Notice: No interactive prompts!

-x, —no-editor

-x, --no-editor · flag

Skip opening the editor after worktree creation.

Overrides the editor configuration setting for this command only.

Usage:

# Create without opening editor
gwt feature-api -x

# Combine with -y for fully automated creation
gwt feature-ui -y -x

# Batch create without editors
gwt task-1 task-2 task-3 -x

Use cases:

• Scripts: Automated worktree creation
• CI/CD: Non-interactive environments
• Batch operations: Create multiple worktrees without opening many editor windows
• Manual navigation: Open editor yourself later

Example:

gwt hotfix-123 -y -x
cd ../myapp-hotfix-123
code .

Clean Command Flags

-a, —all

-a, --all · flag

Remove all worktrees, not just merged ones.

This removes ALL worktrees including:

• Worktrees with uncommitted changes
• Worktrees with unmerged commits
• Active development branches

Use with caution!

Usage:

# Remove only merged worktrees
gwt clean

# Remove ALL worktrees
gwt clean --all

# Short form
gwt clean -a
gwt c -a

Comparison:

# Check status first
gwt status

Output:

┌  Status for myapp
│
│  ◆  feature-merged
│  └  ✓ merged
│
│  ◆  feature-active  +42 -8
│  └  3 changed, 5 ahead
│
└  1 ready to merge, 1 in progress

Without -a (default):

gwt clean

Removes only feature-merged.

With -a:

gwt clean -a

Removes both feature-merged AND feature-active (losing uncommitted work!).

Flag Combinations

Flags can be combined in various ways:

Create with Multiple Flags

# Fast mode, no editor
gwt feature-name -y -x

# Order doesn't matter
gwt feature-name -x -y

# Works with batch mode
gwt feat-a feat-b -y -x

Aliases with Flags

# Clean all using alias
gwt c -a

# Help for specific command
gwt st --help
gwt m --help

Flag Syntax

GWTree supports both short and long flag formats:

Short	Long	Command
-y	--yes	create
-x	--no-editor	create
-a	--all	clean
-h	--help	all
-v	--version	all

Examples:

# Both are equivalent
gwt feature -y
gwt feature --yes

# Both are equivalent
gwt clean -a
gwt clean --all

Flag Positioning

Flags can appear before or after arguments:

# All valid
gwt -y feature-name
gwt feature-name -y
gwt -y -x feature-name
gwt feature-name -y -x

For multiple names:

# All valid
gwt -y feat-a feat-b
gwt feat-a feat-b -y
gwt feat-a -y feat-b  # Also works

Examples by Use Case

Fast Development

Quick worktree creation with zero interaction:

gwt feature-name -y -x

Scripting

Automated worktree creation:

#!/bin/bash
# Create worktrees for sprint tasks
for task in TASK-{1..5}; do
  gwt "$task" -y -x
done

Manual Control

Create but handle editor yourself:

gwt feature-api -x
cd ../myapp-feature-api
cursor .

Cleanup

Aggressive cleanup of all worktrees:

gwt status
gwt clean -a

Help

Get help for specific commands:

gwt merge --help
gwt --help
gwt status -h

Banner Suppression

The GWTree banner is automatically hidden when:

• Using -v or --version flag
• Using -h or --help flag
• Using -y flag with a name argument (fast mode)
• Running gwt version command
• Running gwt help command

Banner shown:

gwt feature-name

╔═╗╦ ╦╔╦╗
║ ╦║║║ ║
╚═╝╚╩╝ ╩

┌  Create Git Worktree
...

Banner hidden:

gwt feature-name -y

┌  Create Git Worktree
...

Configuration vs. Flags

Flags override configuration settings:

Config file:

{
  "editor": "code",
  "installDeps": true
}

With flag:

gwt feature-name -x
# Editor: none (flag overrides config)
# InstallDeps: true (uses config)

Precedence:

1. Command-line flags (highest)
2. Configuration file
3. Defaults (lowest)

Related Documentation

• gwt (create) - Create command that uses -y and -x flags
• gwt clean - Clean command that uses -a flag
• gwt config - Configure default behavior