gdx 0.4.2 → 0.4.4

package/README.md

@@ -13,13 +13,14 @@
 
 `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.
+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`), new workflows for parallel editing and local analytics, git output enhancements, and AI-powered commit message generation.
 
 **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`).
+- **✨ Enhanced Output:** Git's output is... functional. `gdx` makes it beautiful and easier for _humans_ to digest.
+- **🧠 Logic:** Handles the things Git makes hard, like dropping a range of stashes, working with worktrees, or submodules.
 - **📊 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.
 
@@ -130,8 +131,9 @@ Invoke-Expression (& { (gdx --init pwsh | Out-String) })
 
 ```bash
 gdx s             # -> git status
+gdx sta           # -> git stash
+gdx statu         # -> 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
@@ -162,7 +164,9 @@ We've all accidentally reset files we meant to keep. `gdx clear` is the solution
 
 ### 4. Parallel Worktrees (Experimental)
 
-Need to work on the **same branch** in multiple isolated environments without checking out new branches?
+A wrapper for `git worktree` that reduces the friction of managing multiple worktrees, it handles the setup, switching, syncing changes, and cleanup of parallel worktrees so you can focus on coding instead of git logistics.
+
+It also works great with detached worktrees, allowing you to quickly spin up a fork without worrying about getting a branch locked to it.
 
 ```bash
 # Manage forked worktrees for the current branch
@@ -176,9 +180,9 @@ gdx parallel pick    # Cherry-pick a commit from between forks
 gdx parallel remove  # Remove a fork when you're done
 ```
 
-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),
+Additionally, `gdx parallel fork` can **auto-initialize submodules**, **install dependencies**
+using detected package managers (see `parallel.init` config for options), and **copy
+ignored env files** if configured (see `parallel.envPaths` config for options),
 getting the fork ready for work in no time.
 
 ### 5. Git Output for Human (Experimental)
@@ -199,6 +203,9 @@ but more commands will be added in the future. (feel free to request what comman
 >
 > If you want to disable the enhanced output altogether, you can set `enhancedOutput` to `false` in the config.
 
+> [!TIP]
+> Enhanced `gdx show` allows you to navigate between commits in the pager with ←→ keys. This is especially useful when viewing a file's history.
+
 ### 6. Advanced Stash Management
 
 Git stash is great until you need to clean it up.
@@ -223,6 +230,10 @@ gdx cmi auto --no-commit --copy
 # You can also configure which LLM to use with `gdx-config`
 ```
 
+Unlike most AI commit message generators, by default `gdx` creates messages generation guidelines and instructions based on your repo's history and conventions.
+This ensures the generated messages fit your project's style and tone.
+Said guidelines are updated every month to reflect your evolving commit style.
+
 ### 8. Fun & Analytics
 
 Tools to help you feel productive without leaving the terminal.
@@ -237,28 +248,47 @@ Tools to help you feel productive without leaving the terminal.
 
 ## 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                                           |
-| `reword`, `rew`   | Rewrite commit messages                                            |
-| `parallel`, `par` | Manage parallel worktrees for the current branch                   |
-| `stats`           | Show contribution statistics and metrics for the current repo      |
-| `graph`           | Render a GitHub-style contribution heatmap in the terminal         |
-| `nocap`           | Roast your latest commit message with AI                           |
-| `clear`           | Wipe changes in the working directory with a backup patch          |
-| `cache`           | Manage gdx cache                                                   |
-
-_Run `gdx ghelp` to see the full list of expansions._
+### Expansions & Custom Commands
+
+| 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`                                                                                 |
+| `ps`              | `git push` with option expansion `-fl`=`--force-with-lease`                                  |
+| `pu`, `pl`        | `git pull`                                                                                   |
+| `sub`             | `git submodule`                                                                              |
+| `sta`             | `git stash`                                                                                  |
+| `cmi`, `com`      | `git commit` (Try `gdx cmi auto` for AI messages!)                                           |
+| `res`             | `git reset` with option expansion `-h`=`--hard`, `-s`=`--soft` (supports `res ~3` 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                                                                     |
+| `reword`, `rew`   | Rewrite commit messages                                                                      |
+| `parallel`, `par` | Manage parallel worktrees for the current branch                                             |
+| `stats`           | Show contribution statistics and metrics for the current repo                                |
+| `graph`           | Render a GitHub-style contribution heatmap in the terminal                                   |
+| `nocap`           | Roast your latest commit message with AI                                                     |
+| `clear`           | Wipe changes in the working directory with a backup patch                                    |
+| `cache`           | Manage gdx cache                                                                             |
+| `macro`           | Create custom gdx command macros to run multiple commands with a single macro                |
+
+_Run `gdx ghelp` to see the full list of expansions/commands._
+
+### Command Extensions
+
+| Command                           | Expansion / Function                                                                                 |
+| :-------------------------------- | :--------------------------------------------------------------------------------------------------- |
+| `tag mv`, `tag move`              | Move a tag to a new commit (supports ref expansion)                                                  |
+| `lg export`                       | Export git log to a markdown file with enhanced formatting                                           |
+| `commit auto`                     | Generate commit messages with AI based on staged changes (supports `--no-commit` and `--copy` flags) |
+| `stash drop`                      | Drop stashes with advanced options (e.g., `drop 2..6`)                                               |
+| `stash drop pardon`               | Restore the last dropped stash                                                                       |
+| `submodule switch`                | Jump into a submodule's directory from the parent repo (requires shell integration)                  |
+| `status --recursive`, `status -r` | Show status for the main repo and all submodules recursively                                         |
 
 ## Development
 
@@ -299,10 +329,9 @@ Since this is currently a solo "scratch your own itch" project, the roadmap is f
 - [x] **gdx clear Untracked files support**: `gdx clear` now automatically backs up untracked files in the patch.
 - [x] **Recursive status for submodules** with `gdx status --recursive` or `gdx s -r`
 - [x] **Submodule dir switching**: extension of `git submodule`, `gdx submodule switch` to jump into a submodule's directory from the parent repo (requires shell integration)
-- [ ] **Snapshot**: `gdx snap` to create snapshot of current state of your working directory (including uncommitted changes, untracked files) that can be easily switched back to later (similar to a lightweight, temporary branch that doesn't clutter your branch list)
+- [x] **Snapshot**: `gdx snap` to create snapshot of current state of your working directory (including uncommitted changes, untracked files) that can be easily switched back to later (similar to a lightweight, temporary branch that doesn't clutter your branch list)
 - [ ] **Enhanced output for more commands**: Extend the "Git Output for Humans"
 - [ ] **Undo and Redo**: `gdx undo` and `gdx redo` to step backward and forward through git actions (reset, commit, stash, etc.) with safety nets.
-- [ ] **Edit commit history**: `gdx hist` for an intuitive interface to amend, reorder, squash commits without needing to remember complex rebase commands.
 - [x] **Edit commit messages**: `gdx reword` to quickly reword the last commit message or a specific commit without needing to do an interactive rebase.
 
 ## License