git-workflow

A type-safe Git workflow CLI with worktree support and GitHub integration.

Features

• Type-safe branch protection - Prevents accidental deletion of protected branches (main, master, home)
• Git worktree aware - Automatically detects and works with git worktrees
• GitHub integration - Fetches PR information to make informed decisions about branch operations
• Smart state detection - Detects repository state and suggests next actions
• Minimal dependencies - Built with Rust for fast execution

Installation

From crates.io

cargo install git-workflow

From source

git clone https://github.com/zawakin/git-workflow.git
cd git-workflow
cargo install --path .

Quick Demo

$ gw status
ℹ Branch: main (home)
→ Next: start new work

$ gw new fix/typo
✓ Created fix/typo from origin/main

# ... make changes, commit ...

$ gw status
ℹ Branch: fix/typo (home: main)
! Unpushed: 1 commit
→ Next: push and create PR

# ... push, create PR, get merged ...

$ gw cleanup
✓ PR #42 [MERGED]
✓ Deleted fix/typo
✓ Back to main

Usage

The CLI is invoked using the gw command.

Commands

gw home

Switch to home branch and sync with origin/main (or origin/master).

gw home
# Main repo → switches to 'main'
# Worktree → switches to home branch

gw new <branch>

Create a new branch from origin/main.

gw new feature/add-login
gw new fix/memory-leak

gw status

Show current repository state including:

• Repository type (main repo or worktree)
• Current branch and sync status
• Working directory state
• Suggested next action

gw status
# ℹ Repository: worktree (home: feature-x)
# ✓ Branch: feature-x (home)
# ✓ Working directory: clean
# → Next: start new work

gw cleanup [branch]

Delete a merged branch and return to home. Uses GitHub CLI to verify PR merge status.

gw cleanup              # cleanup current branch
gw cleanup feature/old  # cleanup specific branch

gw pause [message]

Create a WIP commit with all changes and return to home branch.

gw pause
gw pause "waiting for API review"

gw abandon

Discard all changes and return to home branch.

gw abandon

gw undo

Undo the last commit (soft reset to HEAD~1).

gw undo

gw sync

After a base PR is merged, update the base to main and rebase.

gw sync

Global Options

• -v, --verbose - Show git commands being executed

gw -v status
gw --verbose cleanup

Prerequisites

• Git
• GitHub CLI (gh) - Required for cleanup and sync commands

Workflow Example

# Start new feature
gw new feature/user-auth

# ... work on feature ...

# Need to switch context? Pause work
gw pause "blocked on API changes"

# Switch to another task
gw new fix/urgent-bug

# ... fix the bug ...

# Clean up after PR is merged
gw cleanup

# Resume previous work
git checkout feature/user-auth

# Check status anytime
gw status

Git Worktree Support

gw is designed to work seamlessly with git worktrees, enabling parallel development on multiple features.

How it works

Each worktree has its own "home branch":

• Main repo: main (or master)
• Worktree: Currently uses the directory name

# Create a worktree
git worktree add ../feature-a feature-a
cd ../feature-a
gw status   # Home: feature-a

Example: Parallel Development

# Work on feature-a in one worktree
cd ~/projects/feature-a
gw pause "WIP: need input"

# Work on feature-b in another worktree
cd ~/projects/feature-b
gw status   # Home: feature-b

# Resume feature-a
cd ~/projects/feature-a
gw undo     # Undo WIP commit

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.