gdx 0.2.0 → 0.4.0

package/README.md

@@ -100,14 +100,14 @@ To add shell integration, add the following line to the **End** of your shell pr
 #### For bash and zsh:
 
 ```bash
-eval "$(gdx --init --shell bash)"  # for bash
-eval "$(gdx --init --shell zsh)"   # for zsh
+eval "$(gdx --init bash)"  # for bash
+eval "$(gdx --init zsh)"   # for zsh
 ```
 
 #### For fish:
 
 ```fish
-gdx --init --shell fish | source
+gdx --init fish | source
 ```
 
 #### For PowerShell:
@@ -115,12 +115,12 @@ gdx --init --shell fish | source
 To find your profile path, run `$PROFILE` in PowerShell.
 
 ```powershell
-Invoke-Expression (& { (gdx --init --shell pwsh | Out-String) })
+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 --shell zsh --cmd g` will create `g` as an alias for `gdx`.
+> For example, `gdx --init zsh --cmd g` will create `g` as an alias for `gdx`.
 
 ## Core Features
 
@@ -139,6 +139,8 @@ 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
 
@@ -171,18 +173,41 @@ gdx parallel open    # Open any fork in your default editor
 gdx parallel join    # Merge changes from a fork back to main
 ```
 
-### 5. Advanced Stash Management
+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`
+
+![diff example](https://github.com/Type-Delta/gdx/raw/main/resources/images/gdx-diff-enhance.png)
+
+> [!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.
 
 ```bash
 gdx sta l           # git stash list
-gdx sta d 2..6      # Drops stashes 2 through 6.
+gdx sta drop 2..6   # Drops stashes 2 through 6.
                     # (Drops high->low to prevent index shifting)
-gdx sta d pardon    # Restores the last dropped stash.
+gdx stash d pardon  # Restores the last dropped stash.
 ```
 
-### 6. AI-Powered Commits
+### 7. Commits Message Generation
 
 Struggling to come up with a commit message? Let `gdx` do it for you.
 
@@ -191,11 +216,11 @@ gdx commit auto   # Generates a commit message based on staged changes, then com
 # or
 # Generates a commit message based on staged changes, but does not commit them.
 # `--copy` also copies the message to clipboard.
-gdx commit auto --no-commit --copy
+gdx cmi auto --no-commit --copy
 # You can also configure which LLM to use with `gdx-config`
 ```
 
-### 7. Fun & Analytics
+### 8. Fun & Analytics
 
 Tools to help you feel productive without leaving the terminal.
 
@@ -203,19 +228,25 @@ Tools to help you feel productive without leaving the terminal.
 - **`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`
+
+![stats example](https://github.com/Type-Delta/gdx/raw/main/resources/images/gdx-stats.png)
+
 ## Command Reference
 
-| Command      | Expansion / Function                                |
-| :----------- | :-------------------------------------------------- |
-| `s`, `stat`  | `git status`                                        |
-| `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) |
-| `sta`, `st`  | `git stash`                                         |
-| `lint`       | Run pre-push checks (spelling, secrets, etc.)       |
-| `gdx-config` | Manage gdx configuration                            |
+| 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._
 
@@ -241,10 +272,8 @@ This project uses **Bun** for development because it's fast and the developer ex
 
 Since this is currently a solo "scratch your own itch" project, the roadmap is fluid, but here is what is on the horizon:
 
-- [x] **Configurability:** Allow users to define their own shorthands in a `.gdxrc.toml` file.
+- [x] **Configurability:** Allow users to define their own shorthands in a `.gdxrc.toml` file (default: `~/.gdx/.gdxrc.toml`).
 - [x] **Shell Integration:** Auto-completion scripts for Zsh/Bash/Fish/Powershell with git fallback.
-- [ ] **Commit with specified editor:** like, `gdx commit --vim` to open Vim for commit messages.
-- [ ] **Quick commit:** `add`, `commit`, and `push` in one command like `gdx qc -pa` (`git add . && gdx commit auto && git push`)
 - [x] **Quick linting before push:** `gdx lint` to run following checks before pushing:
    - commit message spelling
    - env or sensitive content scanning
@@ -252,13 +281,14 @@ Since this is currently a solo "scratch your own itch" project, the roadmap is f
    - abnormal file sizes
      with an option to automatically run lint before every push (bypass with `gdx push --no-lint`)
 - [x] **Undoable stash drop**
-- [x] **Parallel worktree switching** `gdx parallel switch` Jump between forks (auto-cd) (requires shell integration with `gdx --init --shell`)
+- [x] **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`
 - [x] **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.
+- [x] **Recursive status for submodules** with `gdx status --recursive` or `gdx s -r`
 
 ## License