gdx (Git Developer Experience)

The git CLI wrapper that treats you like a human, not a compiler.

Warning

⚠️ ALPHA WARNING: This project is currently in a "trial phase" (i.e., I'm dogfooding it daily). Expect breaking changes, missing features, and the occasional hiccup.

---

What is gdx?

gdx is a drop-in wrapper for the Git CLI. It doesn't replace Git; it just makes it less... unpleasant.

It wraps standard git commands with intelligent shorthands and adds powerful new capabilities that Git is missing like safety rails for destructive actions (undoable reset --hard), introduces new workflows for parallel editing and local analytics.

Why gdx?

• 👍 Convenience: Type less, do more. git status? how about gdx s?, git reset HEAD~3? why not gdx res ~3?
• 🛡️ Safety: gdx clear wipes your directory but saves a backup patch. No more "oops" moments.
• 🧠 Logic: Handles the things Git makes hard, like dropping a range of stashes (drop 2..6).
• 📊 Local-First Stats: Beautiful TrueColor graphs and stats generated from your local history.
• 🤖 AI Integration: Generate commit messages and roast your history with local or cloud LLMs.

Installation

With NPM

Default (Recommended)

Uses the bundled JS version. Works everywhere Node.js 18+ is installed. This is the easiest way to get started and ensures maximum compatibility.

npm i -g gdx

Prebuilt Binary

Downloads a precompiled native binary. No runtime dependency on Node/Bun for execution.

GDX_USE_PREBUILT=1 npm i -g gdx # bash / zsh
# or
$env:GDX_USE_PREBUILT='1'; npm i -g gdx # powershell / fish

Build Locally

Compiles a native binary on your machine during install. Requires Bun to be installed.

GDX_BUILD_NATIVE=1 npm i -g gdx # bash / zsh
# or
$env:GDX_BUILD_NATIVE='1'; npm i -g gdx # powershell / fish

[!NOTE] If your environment sets ignore-scripts=true, the installation will succeed but default to the Node.js fallback. Run gdx doctor to verify your installation status.

Download Manually

Prebuilt stand-alone binaries are available on the Releases page.

Build it yourself

Requires Bun to be installed.

git clone https://github.com/Type-Delta/gdx.git --depth 1
cd gdx
bun install
bun run build

Your compiled binary will be in ./dist/ folder.

Optional: Shell Integration

To enable features like gdx parallel switch (auto-cd into worktrees) and tab completion, you need to add shell integration.

Shell integration provides:

• Auto-cd support: Allows gdx parallel switch to change directories
• Tab completion: Intelligent completion for gdx commands, shorthands, and git subcommands
• Git fallback: Falls back to native git completion when gdx has no suggestions (git fallback requires you to install git's completion scripts separately)

To add shell integration, add the following line to the End of your shell profile (~/.bashrc, ~/.zshrc, etc.):

For bash and zsh:

eval "$(gdx --init bash)"  # for bash
eval "$(gdx --init zsh)"   # for zsh

For fish:

gdx --init fish | source

For PowerShell:

To find your profile path, run $PROFILE in PowerShell.

Invoke-Expression (& { (gdx --init pwsh | Out-String) })

Tip

You can add --cmd to the gdx --init command to create custom aliases. For example, gdx --init zsh --cmd g will create g as an alias for gdx.

Core Features

1. Intelligent Shorthands

gdx isn't just a list of static aliases. It understands partial commands and expands them smartly.

gdx s             # -> git status
gdx lg            # -> git log --oneline --graph --all --decorate
gdx lg export     # -> Exports git log to a markdown file
gdx pl -au        # -> git pull --allow-unrelated-histories
gdx ps -fl        # -> git push --force-with-lease
gdx reset ~2      # -> git reset HEAD~2

Note

This wrapper forwards unrecognized commands directly to git, so you can use it as a full git replacement.

If GDX still gets in your way, just run gdx --bypass <git-commands> to skip gdx intervention altogether.

2. Smart Linting

Catch issues before they reach the remote. gdx lint checks for:

• Spelling errors in commit messages
• Conflict markers left in code
• Sensitive content (keys, tokens)
• Large files

You can configure gdx to run this automatically before every push.

3. The Safety Net: clear vs reset

We've all accidentally reset files we meant to keep. gdx clear is the solution.

• gdx clear: Creates a timestamped patch backup in a temp folder, then effectively runs reset --hard & clean -fd.
• gdx clear pardon: "Wait, I didn't mean to do that." Applies the backup patch and restores your changes.

4. Parallel Worktrees (Experimental)

Need to work on the same branch in multiple isolated environments without checking out new branches?

# Manage forked worktrees for the current branch
gdx parallel fork    # Create a new temp-backed fork
gdx parallel list    # See where your forks are
gdx parallel switch  # Switch between forks (requires shell integration)
gdx parallel open    # Open any fork in your default editor
gdx parallel join    # Merge changes from a fork back to main

Additionally, gdx parallel fork can auto-initialize submodules and install dependencies using detected package managers (currently supports npm, pnpm, bun, and uv) if configured (see parallel.init config for options), getting the fork ready for work in no time.

5. Git Output for Human (Experimental)

Admit it, Git's default output isn't exactly designed for readability. gdx enhances the output of some commands with better formatting to make it more enjoyable and less "git" to read.

Currently, we only support enhanced formatting for gdx diff and gdx show, but more commands will be added in the future. (feel free to request what commands you'd like to see enhanced!)

Example: gdx diff

Note

The enhanced output is only enabled when the output is TTY (i.e., in the terminal) plus other conditions based on the command (e.g., diff must be run without --name-only). If you pipe the output to a file or another command, it will fall back to the standard Git output.

If you want to disable the enhanced output altogether, you can set enhancedOutput to false in the config.

6. Advanced Stash Management

Git stash is great until you need to clean it up.

gdx sta l           # git stash list
gdx sta drop 2..6   # Drops stashes 2 through 6.
                    # (Drops high->low to prevent index shifting)
gdx stash d pardon  # Restores the last dropped stash.

7. Commits Message Generation

Struggling to come up with a commit message? Let gdx do it for you.

gdx commit auto   # Generates a commit message based on staged changes, then commits them.
# or
# Generates a commit message based on staged changes, but does not commit them.
# `--copy` also copies the message to clipboard.
gdx cmi auto --no-commit --copy
# You can also configure which LLM to use with `gdx-config`

8. Fun & Analytics

Tools to help you feel productive without leaving the terminal.

• gdx stats: Shows fun contribution statistics and metrics for your current repo.
• gdx graph: Renders a GitHub-style contribution heatmap in your terminal using TrueColor.
• gdx nocap: Uses AI to roast your latest commit message.

Example: gdx stats

Command Reference

Command	Expansion / Function
s, stat	git status (use -r recursively run "status" on all submodules)
lg, lo	git log --oneline --graph --all --decorate
sw, swit	git switch
br, bra	git branch
cmi, com	git commit (Try gdx cmi auto for AI messages!)
res	git reset (supports res ~3, res -h expansion)
dif	git diff (supports dif ~3, dif origin ~2 expansion)
sho	git show (supports sho ~3, sho origin ~2 expansion)
sta, st	git stash
lint	Run pre-push checks (spelling, secrets, etc.)
gdx-config	Manage gdx configuration

Run gdx ghelp to see the full list of expansions.

Development

This project uses Bun for development because it's fast and the developer experience is great.

1. Clone the repo

2. Prepare the development environment:

   bun run prepare-dev

3. Run in dev mode:

   bun start -- # your gdx commands here
   
   # for example:
   bun start -- s # runs `gdx s` (git status)

Roadmap

Since this is currently a solo "scratch your own itch" project, the roadmap is fluid, but here is what is on the horizon:

• Configurability: Allow users to define their own shorthands in a .gdxrc.toml file (default: ~/.gdx/.gdxrc.toml).
• Shell Integration: Auto-completion scripts for Zsh/Bash/Fish/Powershell with git fallback.
• Quick linting before push: gdx lint to run following checks before pushing:
  • commit message spelling
  • env or sensitive content scanning
  • conflict markers
  • abnormal file sizes with an option to automatically run lint before every push (bypass with gdx push --no-lint)
• Undoable stash drop
• Parallel worktree switching gdx parallel switch Jump between forks (auto-cd) (requires shell integration with gdx --init)
• Seamless Integration with fzf and cloc automatically detect and use fzf and/or cloc if installed for:
  • Interactive fuzzy search for branches, commits, stash, log and files instead of less
  • Code line statistics in gdx stats using cloc
• gdx clear Untracked files support: gdx clear now automatically backs up untracked files in the patch.
• gdx migrate: move dirty changes to another branch/worktree without committing.
• Recursive status for submodules with gdx status --recursive or gdx s -r

License

MIT © Type-Delta