Virtual Branches

Virtual branches are one of ProGit’s most powerful features. They let you work on multiple features simultaneously without the friction of constantly switching git branches.

The Problem

Traditional git workflow:

# Working on feature A
git checkout -b feature-a
# ... write code ...

# Emergency bugfix needed
git stash
git checkout -b hotfix
# ... fix bug ...
git checkout feature-a
git stash pop
# Hope the stash applies cleanly...

Problems:

Context switching is slow
Stashes can conflict
Hard to see work-in-progress across branches
Easy to forget about stashed work

The Solution: Virtual Branches

Virtual branches exist only in ProGit’s tracking layer, not in git itself:

Git Branches:
  main ──────────────────────────────

Virtual Branches (ProGit):
  ├─ feature-auth     [WIP: 3 files]
  ├─ feature-ui       [WIP: 1 file]
  └─ hotfix-memory    [WIP: 2 files]

Creating Virtual Branches

# Create a new virtual branch
progit branch virtual feature-auth

# Or from the TUI (press 'b', then 'v')

How It Works

File-Level Tracking

ProGit tracks which files belong to which virtual branch:

Working Directory:
├── src/
│   ├── auth.rs      ← feature-auth
│   ├── login.rs     ← feature-auth
│   ├── ui.rs        ← feature-ui
│   └── widget.rs    ← feature-ui
├── fix/
│   └── memory.rs    ← hotfix-memory
└── Cargo.toml       ← shared

Switching Between Work

# Switch to feature-auth work
progit branch switch feature-auth

# Now only feature-auth files are "visible"
$ ls src/
auth.rs  login.rs

# Edit, commit, etc.
vim src/auth.rs
git add src/auth.rs
git commit -m "Add OAuth support"

# Switch to different work
progit branch switch feature-ui

# Now feature-ui files are visible
$ ls src/
ui.rs  widget.rs

Visual Representation

In the ProGit TUI (press b for branches):

┌─ Virtual Branches ─────────────────────┐
│                                        │
│  ▶ feature-auth         3 files, 2 commits│
│    feature-ui           1 file, 0 commits │
│    hotfix-memory        2 files, 1 commit │
│                                        │
│  [a]ctive  [c]reate  [d]elete  [m]erge  │
│                                        │
└────────────────────────────────────────┘

Committing Virtual Branch Work

When you’re ready to commit a virtual branch:

# Option 1: Commit as new git branch
progit branch commit feature-auth --as-branch
# Creates git branch 'feature-auth' with your changes

# Option 2: Commit to existing git branch
progit branch commit feature-auth --to-branch=main
# Squashes and commits to main

# Option 3: Create a PR/MR
progit branch commit feature-auth --mr
# Creates merge request on GitLab

Conflict Detection

Virtual branches can touch the same files:

# feature-auth modifies src/main.rs
# feature-ui also modifies src/main.rs

$ progit branch switch feature-ui
⚠ Conflict detected with feature-auth

  File: src/main.rs
  feature-auth: lines 42-50 modified
  feature-ui:   lines 45-55 modified

  [v]iew conflict  [s]tash changes  [a]bort

Best Practices

1. Keep Virtual Branches Small

# Good: Focused virtual branches
progit branch virtual feature-login-page
progit branch virtual feature-oauth-backend
progit branch virtual fix-typo

# Avoid: Monolithic virtual branches
progit branch virtual everything

2. Commit Regularly

# Commit virtual branch work to git branches often
progit branch commit feature-auth --as-branch
git push origin feature-auth

# This backs up your work

3. Use Descriptive Names

# Good
progit branch virtual feature/user-auth
progit branch virtual hotfix/memory-leak

# Avoid
progit branch virtual temp
progit branch virtual wip

4. Clean Up Completed Work

# Delete virtual branch after merging
progit branch delete feature-auth

Integration with Issues

Link virtual branches to issues:

# Create virtual branch from issue
progit issue branch 42 --virtual
# Creates virtual branch linked to issue #42

# See related work in TUI
progit tui
# Issue panel shows linked virtual branch

Configuration

[git.virtual_branches]
# Enable virtual branches
enabled = true

# Maximum concurrent virtual branches
max_concurrent = 5

# Auto-commit when switching away
auto_commit = false

# Show conflict warnings
conflict_warnings = true

# Default git branch for commits
default_target = "main"

Comparison with Git Worktrees

Feature	Virtual Branches	Git Worktrees
Multiple checkouts	✅ Yes	✅ Yes
Disk usage	Lightweight (metadata only)	Heavy (full copy)
Switching speed	Instant	Fast
IDE support	Native	Requires setup
Visual overview	Built-in TUI	Manual
Conflict handling	Automatic detection	Manual

Example Workflow

# Morning: Start three tasks
progit branch virtual feature-api
progit branch virtual feature-ui
progit branch virtual refactor-tests

# Work on API
progit branch switch feature-api
vim src/api.rs
git add src/api.rs
git commit -m "Add endpoint"

# Quick context switch to UI
progit branch switch feature-ui
vim src/ui.rs

# Emergency bugfix
progit branch switch main
git checkout -b hotfix
vim src/fix.rs
git commit -m "Hotfix"

# Back to API work
progit branch switch feature-api
# Your API changes are still there!

# End of day: Commit virtual branches
progit branch commit feature-api --as-branch
git push origin feature-api