gx-git 1.1.1

Git Productivity Toolkit

gx

Git Productivity Toolkit

• All destructive commands require confirmation and support --dry-run

Install

Recommended (isolated environment via pipx):

pipx install gx-git

Alternative (via pip):

pip install gx-git

Requires Python 3.9+.

Commands

Everyday:

Command	Description
gx undo	Smart undo — figures out what to undo
gx redo	Redo the last undo
gx oops	Quick-fix the last commit
gx switch	Branch switcher with search
gx context	Repo status at a glance
gx sweep	Clean up merged branches and stale refs
gx shelf	Visual stash manager

Insight:

Command	Description
gx who	Who knows this code best
gx recap	What did I (or my team) do recently
gx drift	How far you've diverged from the HEAD branch
gx conflicts	Preview merge conflicts before merging

Stacking:

Command	Description
gx stack	Create a stacked branch with tracked parent
gx sync	Rebase and push a chain of stacked branches
gx retarget	Rebase a branch onto a new base
gx graph	Visualize the branch stack tree

Utility:

Command	Description
gx nuke	Delete branches with confidence
gx update	Update gx to the latest version

---

gx undo

Smart undo — detects the last git action and reverses it by walking the reflog. Works regardless of whether the action was performed via gx or raw git commands.

gx undo              # Undo the last thing
gx redo              # Redo (undo the undo)
gx undo --dry-run    # See what it would do without doing it
gx undo --history    # See your undo/redo history

Detects and reverses, in priority order:

State	Undo Action
Active merge conflict	git merge --abort
Rebase in progress	git rebase --abort
Staged files	git reset HEAD (unstages all)
Amended commit	git reset --soft HEAD@{1}
Merge commit	git reset --hard HEAD~1
Regular commit	git reset --soft HEAD~1 (keeps changes staged)

$ gx undo

Detected: commit "Add search endpoint" (a1b2c3d, 2 minutes ago)

  Action:  Soft reset to previous commit — your changes will be preserved in staging.
  Command: git reset --soft HEAD~1

? Proceed with undo? [y/N] y

✓ Undone. Your changes from that commit are now staged.
  Run `gx redo` to reverse this.

Undo/redo state is tracked via reflog entries and a supplemental history file, so it survives app restarts and works even if you run raw git commands in between.

---

gx who

Show who knows a file, directory, or repo best based on git blame and log data.

gx who                    # Top contributors to the entire repo
gx who src/index.js       # Who knows this file best
gx who src/               # Who knows this directory best
gx who -n 10              # Show top 10 contributors
gx who --since 6months    # Only consider recent contributions

$ gx who src/auth/login.ts

Ownership of src/auth/login.ts (142 lines):

  #   Author              Lines    %      Last Edit
  1   Kim Choi          68       47.9%  3 days ago
  2   You                 42       29.6%  1 hour ago
  3   James Wilson        32       22.5%  2 weeks ago

Flag	Default	Description
-n, --number	5	Number of contributors to show
--since	—	Only consider commits after this date
--email	false	Show email addresses
--no-limit	false	Remove the 200-file cap for directory analysis

Directory-level analysis runs blame concurrently across files. Capped at 200 files by default to keep things fast.

---

gx nuke

Delete branches (local, remote, and tracking refs).

gx nuke feature/old-thing          # Delete local + remote + tracking
gx nuke feature/old-thing --local  # Delete local only
gx nuke feature/old-thing --dry-run  # See what would be deleted
gx nuke "feature/*"                # Glob pattern support

$ gx nuke feature/old-auth

Branch: feature/old-auth

  ✗ Local branch          (last commit: 3 weeks ago, "Fix token refresh")
  ✗ Remote tracking ref   (origin/feature/old-auth)
  ✗ Remote branch         (origin)

  This branch is NOT merged into main.
  ⚠ You may lose 4 commits.

? Proceed with deletion? [y/N] y

✓ Deleted local branch feature/old-auth
✓ Deleted remote tracking ref origin/feature/old-auth
✓ Deleted remote branch origin/feature/old-auth

Flag	Default	Description
--local	false	Only delete local branch
--dry-run	false	Show what would be deleted
-y, --yes	false	Skip confirmation (still blocked for unmerged + HEAD branch)
--orphans	false	Delete all orphaned branches from the stack graph

Safety: Cannot nuke the current branch or the HEAD branch (main/master). Unmerged branches get a prominent warning with commit count. Warns if the branch has dependents in the stack.

---

gx recap

Show what you (or someone else) did recently.

gx recap                 # Your commits in the last 24 hours
gx recap @kim          # Kim's commits in the last 24 hours
gx recap --all           # Whole team's activity in the last 24 hours
gx recap -d 7            # Last 7 days

$ gx recap

Your activity in the last 24 hours (my-project):

  Today:
    a1b2c3d  14:32  Add search endpoint
    d4e5f6g  11:15  Add search index util
    h7i8j9k  09:03  Scaffold search module

  Yesterday:
    m1n2o3p  17:45  Fix pagination bug

  4 commits across 2 days
  8 files changed, +142 -38

Flag	Default	Description
@<name>	current git user	Filter by author (substring match)
-d, --days	1	Number of days to look back
--all	false	Show all contributors
--limit	100	Max commits to display

---

gx sweep

Clean up merged branches, prune stale remote tracking refs, and tidy up in one command.

gx sweep              # Interactive cleanup
gx sweep --dry-run    # See what would be cleaned
gx sweep -y           # Auto-confirm

$ gx sweep

Scanning for cleanup opportunities...

Merged branches (safe to delete):
  feature/auth-v1         merged 2 weeks ago
  fix/typo-readme         merged 3 days ago

Likely squash-merged branches:
  feature/onboarding      last commit 3 weeks ago (all patches found on main)

Stale remote tracking refs:
  origin/feature/deleted-branch

Summary: 2 merged, 1 likely squash-merged, 1 stale refs

? Delete merged branches? [y/N] y
? Delete likely squash-merged branches? [y/N] y
? Prune stale remote tracking refs? [y/N] y

✓ Cleanup complete.

Detects squash-merged branches using git cherry — branches where all patches already exist on the HEAD branch are flagged as "likely squash-merged" and confirmed separately.

Flag	Default	Description
--dry-run	false	Show what would be cleaned
-y, --yes	false	Skip confirmation prompts

Safety: Never deletes the current branch or HEAD branch. Squash-merged branches are confirmed separately with lower-confidence framing.

---

gx oops

Quick-fix the last commit — amend the message, add forgotten files, or both.

gx oops                           # Opens editor to amend message
gx oops -m "Better message"       # Amend with new message inline
gx oops --add src/forgot.ts       # Add a forgotten file to last commit
gx oops --add src/forgot.ts -m "Updated message"  # Both at once
gx oops --dry-run                 # See what would change

$ gx oops --add src/auth/refresh.ts -m "Fix auth token refresh — include refresh util"

Last commit: "Fix auth token refresh" (a1b2c3d, 5 min ago)

  Adding to last commit:
    + src/auth/refresh.ts (modified, 12 lines changed)

  Amending message:
    Before: "Fix auth token refresh"
    After:  "Fix auth token refresh — include refresh util"

? Proceed? [y/N] y

✓ File added and commit message amended.

Flag	Default	Description
-m, --message	—	New commit message (skips editor)
--add	—	File(s) to add to the last commit
--dry-run	false	Show what would change
--force	false	Allow amending even if already pushed

Safety: Refuses to amend if the last commit has been pushed to remote (override with --force).

---

gx context

Enhanced repo status at a glance — everything you need to know about your current state.

gx context     # Full context summary
gx ctx         # Alias

$ gx context

Branch:       feature/search
Tracking:     origin/feature/search (up to date)
vs main:      3 ahead, 2 behind

Last commit:  a1b2c3d "Add search endpoint" (2 hours ago)

Working tree:
  Modified:   3 files
  Staged:     1 file
  Untracked:  2 files

Stash:        2 entries

⚠ Rebase in progress (2/5 commits applied)

Shows: current branch, tracking status, ahead/behind HEAD branch, last commit, working tree status, stash count, and active operations (merge/rebase/cherry-pick).

---

gx drift

Show how far your branch has diverged from the HEAD branch, with commit details and file stats.

gx drift              # Compare against HEAD branch
gx drift develop      # Compare against a specific branch
gx drift --full       # Show all commits (no truncation)

$ gx drift

feature/search is 3 ahead, 2 behind main

Commits on your branch (not on main):
  a1b2c3d  2h ago   Add search endpoint
  d4e5f6g  5h ago   Add search index util
  h7i8j9k  1d ago   Scaffold search module

Commits on main (not on your branch):
  x1y2z3a  3h ago   Fix auth token refresh (kim)
  b4c5d6e  1d ago   Update CI pipeline (james)

Files diverged: 8 modified, 2 added

Flag	Default	Description
--full	false	Show all commits (no truncation at 20)

---

gx switch

Branch switcher with search.

gx switch       # Interactive branch picker
gx switch -     # Switch to previous branch

Lists all local branches sorted by recent activity. Enter a number to switch, type text to filter the list, q to cancel.

$ gx switch

    1  feature/payments                          2h ago          kim
    2  fix/login-bug                             5h ago          you
    3  feature/auth-v2                           3d ago          james
    4  feature/search                            1d ago          you

Enter a number to switch, text to filter, q to cancel
> auth

    1  feature/auth-v2                           3d ago          james

Enter a number to switch, text to filter, q to cancel
> 1

✓ Switched to feature/auth-v2

---

gx conflicts

Preview merge conflicts before actually merging, without touching the working tree.

gx conflicts              # Check against HEAD branch
gx conflicts develop      # Check against a specific branch

$ gx conflicts

Checking feature/search against main...

✗ 3 conflicts found

  src/api/auth.ts          (you + kim)
  src/utils/helpers.ts     (you + james)
  package.json             (dependency versions)

  14 other files merge cleanly

$ gx conflicts

Checking feature/search against main...

✓ No conflicts — clean merge
  12 files would be modified

Uses git merge-tree to simulate the merge entirely in memory. Nothing is modified on disk.

---

gx shelf

Visual stash manager. Browse, preview diffs, and apply or drop stashes interactively.

gx shelf                      # Open interactive stash browser (TUI)
gx shelf push "message"       # Quick stash with a descriptive message
gx shelf push                 # Quick stash (auto-generates message)
gx shelf list                 # Non-interactive list
gx shelf clear                # Drop all stashes (requires confirmation)
gx shelf clear --dry-run      # Show what would be cleared

The interactive browser is a split-pane TUI (powered by Textual): stash list on the left, full diff preview on the right. Navigate with arrow keys, Enter to pop, Space to apply (keep stash), d to drop, / to search.

$ gx shelf list

3 stashes:

  #   Age           Branch              Message
  0   2 hours ago   feature/auth-v2     WIP on feature/auth-v2
  1   3 days ago    feature/search      Fix token refresh
  2   2 weeks ago   main                WIP on main

$ gx shelf push "Fix token refresh"

✓ Stashed working directory: "Fix token refresh"
  Run `gx shelf` to browse.

Safety: Pop/apply conflicts exit the TUI cleanly with resolution instructions. Drop requires confirmation.

---

gx stack

Create a new branch on top of a parent branch, with the relationship tracked in .git/gx/stack.json.

gx stack feature/auth-v2 feature/auth-v1   # Direct usage
gx stack                                    # Interactive prompt

$ gx stack feature/auth-v2 feature/auth-v1

✓ Created feature/auth-v2 on top of feature/auth-v1
  Relationship saved to stack config.

In interactive mode, shows a searchable branch list for parent selection, then prompts for the new branch name.

---

gx sync

Rebase and push a chain of stacked branches in sequence, keeping the entire stack up to date.

gx sync --stack                              # Auto-detect and sync full stack
gx sync main feature/auth-v1 feature/auth-v2 # Explicit chain
gx sync --dry-run --stack                    # Show what would happen

$ gx sync --stack

Auto-detected stack from config:
  main -> feature/auth-v1 -> feature/auth-v2

Syncing 2 branches...

  Rebasing stack onto main (using --update-refs)...
  ✓ Rebased feature/auth-v1
  ✓ Rebased feature/auth-v2

  Pushing updated branches...
  ✓ Pushed feature/auth-v1
  ✓ Pushed feature/auth-v2

✓ Stack sync complete. 2 branches updated.

Uses git rebase --update-refs on Git 2.38+ (single operation for the whole chain). Falls back to --onto iteration on older Git versions. Stops on first conflict with resolution instructions.

Flag	Default	Description
--stack	false	Auto-detect and sync the current branch's full stack
--dry-run	false	Show what would happen

Safety: Uses --force-with-lease for pushes. Stops on first conflict. Confirms for chains of 5+ branches. Returns to original branch after sync.

---

gx retarget

Rebase a branch onto a new base. Updates the stack config and attempts to auto-retarget the PR via gh CLI.

gx retarget feature/auth-v2 main        # Move feature/auth-v2 onto main
gx retarget feature/auth-v2 main --dry-run

$ gx retarget feature/auth-v2 main

Retargeting feature/auth-v2 onto main...

  Old parent: feature/auth-v1
  New parent: main

  Fetching latest from remote...
  Rebasing feature/auth-v2 onto origin/main (using --onto)...
  ✓ Rebased and pushed feature/auth-v2
  ✓ PR for feature/auth-v2 automatically retargeted to main

  Stack config updated: feature/auth-v2 -> main (was: feature/auth-v1)

Uses git rebase --onto to slice out only the branch's own commits, avoiding duplication of the old parent's commits. If gh CLI is installed and authenticated, auto-retargets the PR; otherwise shows a reminder.

Flag	Default	Description
--dry-run	false	Show what would happen

---

gx graph

Visualize the branch stack as a tree with health indicators.

gx graph

$ gx graph

Branch Stack:

|-- main
|   |-- feature/auth-v1       * HEAD  (+2/-0)
|   |   `-- feature/auth-v2            (+3/-1)
|   |-- feature/search                 + merged
|   `-- fix/login-bug                  (+1/-0)

Orphaned Branches:
`-- experiment/old-idea                ! orphaned

Legend: * current branch  + merged  (+ahead/-behind)  ! orphaned
Relationships stored in .git/gx/stack.json

The tree builder auto-discovers relationships for branches created outside of gx and saves them to the config, so the graph gets more accurate over time.

---

Tech Stack

• Typer — CLI framework
• Rich — Terminal formatting (colors, tables, spinners)
• Textual — TUI for interactive stash browser

License

MIT