Git CLI Assistance 🚀

Educational, safety-first, context-aware Git CLI companion for Visual Studio Code.

🌟 Why Git CLI Assistance?

Mastering Git from the command line is challenging: commands are cryptically named, mental models are invisible, mistakes can cause irreversible data loss, and error messages often lack actionable remedies.

Git CLI Assistance bridges this gap. It works alongside you directly in your terminal and editor with:

• ⚡ Real-Time Ghost-Text Auto-Suggestions: Terminal predictions (<1ms latency) with dynamic branch and modified file autocomplete.
• 🛠️ Terminal Quick-Fix on Command Failure: Proactively catches failed Git commands and offers 1-click remedies.
• 🧠 4-Layer Mental Models & State Diffs: Visualizes exactly how every command affects the Working Tree, Staging Area, Local Repository, and Remote.
• 🛡️ 4-Level Danger Gradient: Clear color badges and safety confirmation prompts before running destructive commands.
• ↩️ Undo Companion: Step-by-step escape hatches and recovery instructions for every command.
• 🖥️ Interactive Activity Bar Dashboard & Sidebar Views: Live repository metrics, situation detection, branch health, and stash awareness.
• 🔍 Fuzzy & Alias-Aware Problem Search: Search by what you want to achieve ("undo commit", "squash") or terminal shorthand ("co", "st").

✨ Features at a Glance

⚡ 1. Real-Time Terminal Ghost-Text Auto-Suggestions

Type naturally in your integrated terminal. Git CLI Assistance predicts your next move in real-time using ghost text, powered by a sub-millisecond (<1ms) non-blocking Git context cache:

• Context-Aware Predictions: Suggests git commit when files are staged, git add when files are modified, git push when commits are unpushed, or git merge --continue during conflicts.
• Dynamic File Autocomplete: Typing git add <tab> or git restore dynamically autocompletes your modified or untracked files.
• Dynamic Branch Autocomplete: Typing git checkout , git switch , or git merge dynamically autocompletes your local branch names.
• Non-Blocking Cache: Never lags your keystrokes or freezes the command line.

⌨️ Terminal Keybindings

Setup: The extension automatically activates suggestions in your VS Code integrated terminal. You can also run Git CLI: Setup Realtime Terminal Auto-Suggestions in ~/.zshrc (gitcli.setupTerminalSuggestions) or toggle it anytime via Git CLI: Toggle Realtime Ghost-Text Auto-Suggestions (gitcli.toggleRealtimeSuggestions).

🛠️ 2. Terminal Shell Execution Watcher & 1-Click Quick-Fix

When a Git command in your terminal fails with a non-zero exit code:

1. The extension automatically inspects the command and error output.
2. An actionable notification appears with a concise diagnosis and the exact recommended fix command.
3. Click Fix to immediately insert or run the fix in your terminal, or click Open Assistant to view full recovery options.

🧠 3. Mental Models & 4-Layer State Diffs

Git operates across four distinct storage layers:

1. Working Tree (your local files on disk)
2. Staging Area / Index (prepared changes for the next commit)
3. Local Repository / HEAD (committed history and local branch refs)
4. Remote Repository (upstream tracking branches)

For every command, Git CLI Assistance renders an Explain-like-a-diff state table showing exactly what moves where:

[~] Working Tree  : Modified files staged
[+] Staging Area  : New changes registered
[∅] HEAD / Local  : Unchanged until commit
[∅] Remote        : Unchanged until push

🛡️ 4. 4-Level Danger Gradient & Safety Confirmation

Every command is classified into a 4-level safety gradient:

Safety Confirmation: When executing or inserting a Level 3 (Destructive) command, a modal confirmation prompt appears to prevent accidental data loss.

↩️ 5. Undo Companion (Never Fear Mistakes)

Every single command card includes a dedicated Undo Companion:

• Recovery Command: The exact command needed to roll back the action.
• Difficulty Rating: Simple, Moderate, or Advanced.
• Step-by-Step Instructions: Concrete sequence to restore your original repository state.
• Time Limits & Warnings: Identifies if an undo action must be performed before running other commands (e.g. before git gc or remote force push).

🖥️ 6. Activity Bar Dashboard & Dedicated Sidebar Views

Click the Git CLI Assistance icon on the Activity Bar to access:

1. Git CLI Assistant (gitcli.views.mainDashboard):
   • Live Repository Status: Current branch, tracking upstream, ahead/behind commit counters, and sync status.
   • 4-Layer State Diagram: Live counters for untracked, modified, staged, and unpushed files.
   • Active Situation & Alert Cards: Real-time detection of stuck states with 1-click remedies.
   • Instant Search Bar: Search commands, problems, aliases, or errors directly in the sidebar.
   • Ref Anatomy Breakdown: Interactive ref expression decomposer.
2. Active Situation & Alerts (gitcli.views.situations):
   • Automatically detects Merge Conflicts, Rebase Pauses, Detached HEAD, and Diverged Branches.
   • Click any alert to trigger actionable recovery options (gitcli.whatCanIDo).
3. Repository State (4-Layer Model) (gitcli.views.stateDiagram):
   • Tree representation of the 4 Git layers with live file counts.
4. Branch Health (gitcli.views.branchHealth):
   • Overview of all local branches, upstream associations, and sync metrics.
5. Stash Awareness (gitcli.views.stashes):
   • Real-time list of all stashes with index, message, and branch metadata.

🔍 7. Fuzzy, Alias-Aware & Error Search

Press Cmd+Shift+P (or Ctrl+Shift+P) and run Git CLI: Search Command, Problem, or Error (gitcli.search):

• Problem-Based Search: Search what you want to do: "undo last commit", "lost files", "squash commits", "change author", "rename branch".
• Alias Resolution: Understands built-in shortcuts (co, ci, st, br, lg) and parses your custom personal aliases from ~/.gitconfig and .git/config.
• Error Resolution Database: Paste cryptic Git errors (e.g. "refusing to merge unrelated histories", "src refspec does not match any", "detached HEAD") to receive instant explanations, root causes, and recommended solutions.

📖 8. Interactive Cheat Sheet & Command Comparison

• Interactive Cheat Sheet (gitcli.cheatSheet): Comprehensive, searchable, categorized Git reference (Getting Started, Daily Workflow, Branching & Merging, Undoing & History, Stashing & Inspection, Remote & Sync, Advanced). Each command features risk badges, 1-click terminal insertion, and copy buttons.
• Compare Confusing Commands (gitcli.compareCommands): Side-by-side comparison cards for commands developers frequently mix up:
  • git reset vs git revert vs git restore
  • git checkout vs git switch vs git restore
  • git merge vs git rebase
  • git fetch vs git pull
  • git rebase vs git cherry-pick

🔬 9. Ref Anatomy Decomposer (gitcli.explainRef)

Git ref expressions like HEAD~2, HEAD^, origin/main, @{upstream}, or stash@{0} can be confusing. Run Git CLI: Explain Git Ref Expression to:

• Decompose expressions into individual tokens with plain-English explanations.
• Automatically resolve the expression to its exact target commit SHA hash in the current repository.

🎯 10. Progressive Practice Challenges (gitcli.practice)

Sharpen your CLI muscle memory through interactive challenges:

• 3-Level Progressive Hint System:
  1. Nudge: High-level clue pointing you in the right direction.
  2. Detailed Hint: Specific flags, syntax hints, and considerations.
  3. Exact Solution: The complete command syntax with explanation.

💡 11. Contextual Editor Enhancements

• .gitconfig Hover Provider: Hover over any directive or key when editing .gitconfig or .git/config to see rich explanations, accepted values, and examples.
• Terminal Link Provider: Automatically detects Git commands and keywords in terminal output, making them clickable to open the corresponding documentation card.

⌨️ Command Palette Reference

All commands are available via Cmd+Shift+P / Ctrl+Shift+P:

⚙️ Extension Settings

Configure Git CLI Assistance via VS Code Settings (Cmd+, / Ctrl+,):

📦 Compatibility & Shell Support

• Platforms: macOS, Linux, Windows (WSL, Git Bash).
• Terminal Auto-Suggestions: Optimized for Zsh (macOS and Linux default).
• Core Extension: Compatible with VS Code 1.90.0 and newer, including Cursor, VSCodium, and Open VSX-compatible editors.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.