⚡ GitSnap

One-keystroke Git for VS Code — with AI if you want it, without it if you don't.

Draft commit messages, commit and push in one shortcut, manage branches and stashes visually, preview rebases, prepare pull requests and run Git in plain English — all inside VS Code.

Bring your own key (Groq · OpenAI · Anthropic) · Run AI locally (Ollama · Tabby) · Or switch AI off entirely — every core feature still works.

Contents

1. What is GitSnap?
2. Choose your mode: No-AI, Bring Your Own Key, or Local AI
3. Installation
4. Quick start (5 minutes)
5. Features in detail
6. Keyboard shortcuts
7. Settings reference
8. Safety guarantees
9. Privacy & security
10. Troubleshooting
11. FAQ
12. For developers
13. License

🔍 What is GitSnap?

GitSnap is a Visual Studio Code extension that removes the repetitive parts of working with Git:

GitSnap is AI-optional by design. AI only drafts text (commit messages, PR descriptions, short summaries) and translates plain-English requests. Everything else is ordinary, predictable Git — and when AI is switched off, each feature falls back to manual input or a built-in template.

🎛 Choose your mode

GitSnap works in three ways. You can switch at any time in GitSnap: Open Settings.

🚫 Option A — No-AI mode

Everything works without any AI: commit & push, the commit editor, branch dashboard, stashes, log explorer, cherry-pick, rebase preview, worktrees, PR drafts (from a template) and undo.

Turn it on:

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) → GitSnap: Open Settings.
2. Untick Enable AI features → Save Settings.

Or in settings.json:

{ "gitsnap.ai.enabled": false }

What changes:

No AI network requests are made while AI is disabled.

🔑 Option B — Bring Your Own Key (BYOK)

You use your own account with a cloud provider. GitSnap has no subscription and no server of its own: requests go straight from your VS Code to the provider.

Model names change over time. You can type any model id your provider accepts in the Settings panel — the list there is only a set of suggestions.

Set it up (example: Groq):

1. Sign in at console.groq.com, open API Keys, click Create API Key, and copy the gsk_… value.
2. In VS Code run GitSnap: Open Settings.
3. Make sure Enable AI features is ticked and choose Groq (cloud) as the provider.
4. Paste the key into API key and press Save Settings. A stored ✓ badge confirms it.

Faster alternative: run GitSnap: Set API Key and paste the key. It is saved for the currently selected provider.

Good to know:

• Each provider has its own key slot. Switching from Groq to OpenAI never sends your Groq key to OpenAI.
• Keys are stored in your operating system's keychain (VS Code SecretStorage) — never in settings.json, never in your repository, and never shown back in the UI.
• To remove a key: Remove stored key in Settings, or run GitSnap: Set API Key and submit an empty value.

🏠 Option C — Local AI (Ollama or Tabby)

AI runs on your own machine or server. Nothing is sent to the internet.

Ollama:

1. Install Ollama from ollama.com.
2. Download a model (in a terminal):

   ollama pull llama3.2
   

3. Make sure Ollama is running (it usually starts automatically; otherwise run ollama serve).
4. In GitSnap: Open Settings choose Ollama (local), type the model name (e.g. llama3.2, qwen2.5-coder) or leave it empty for the default, and press Save Settings. No key is needed.
5. If Ollama runs on another machine, set its address:

   { "gitsnap.ai.ollamaBaseUrl": "http://my-gpu-box:11434" }
   

Tabby: choose Tabby (self-hosted), set gitsnap.ai.tabbyBaseUrl if your server is not at http://localhost:8080, and paste your Tabby auth token as the API key if your server requires one.

Local models are slower on modest hardware. If drafts time out, raise gitsnap.ai.requestTimeoutSeconds (default 60).

📦 Installation

Requirements

• VS Code 1.134 or newer
• Git installed and available on your PATH (check with git --version)
• A folder that is (or is inside) a Git repository
• A trusted workspace — GitSnap is disabled in Restricted Mode (see Safety)

Install from a .vsix file

1. Build the package (see For developers) or obtain gitsnap-2.1.0.vsix.
2. Install it:
   • UI: Extensions view → … menu → Install from VSIX… → pick the file, or
   • Terminal:

     code --install-extension gitsnap-2.1.0.vsix
     

3. Reload VS Code. A ⚡ GitSnap item appears in the status bar.

Run from source

git clone https://github.com/rohith-decent/GitSnap.git
cd GitSnap
npm install
npm run build

Open the folder in VS Code and press F5. A new Extension Development Host window opens with GitSnap loaded — open any Git repository there to try it.

🚀 Quick start (5 minutes)

1. Open a Git repository in VS Code.
2. Pick your mode — No-AI, BYOK or Local AI (see above).
3. Change a file, then press Ctrl+Alt+Enter (Cmd+Alt+Enter on macOS). GitSnap stages your changes, drafts a message, commits and pushes. ✅
4. Press Ctrl+K G to open the GitSnap menu and explore the rest.

You can also reach every action from:

• the ⚡ GitSnap status-bar item (Fast Commit & Push),
• the Source Control view title bar (⚡ and ☰ buttons),
• the Command Palette — type GitSnap.

✨ Features in detail

1. ⚡ Fast AI Commit & Push — Ctrl+Alt+Enter

The one-keystroke workflow.

What happens:

1. Stage — if you have already staged specific files, GitSnap uses exactly those. If nothing is staged, it stages all changes (including new and deleted files) across the whole repository.
2. Draft — AI writes a Conventional Commit message such as feat(auth): add OAuth2 login flow. In No-AI mode, or if the AI fails, you are asked to type a message instead.
3. Commit — the message is used exactly as written.
4. Push — to the branch's upstream. If the branch has never been pushed, GitSnap pushes it to origin (or your only remote) and sets the upstream for you.

Details worth knowing:

• The AI step shows a progress notification with a Cancel button.
• Pressing the shortcut again while a commit is running does not start a second one.
• If the push fails (no remote, remote has newer commits, authentication), GitSnap tells you clearly that the commit was made locally — so you never commit twice.
• Very large diffs are trimmed before being sent to the AI, together with a list of every changed file, so the message still reflects the whole change.

2. 📝 Commit Editor — Ctrl+Alt+C

Review before you commit.

• Left: the staged diff with colour-coded additions, deletions and hunk headers.
• Right: your commit message.
• 💡 AI Suggest drafts a message from the staged diff (AI mode only). Always review it before committing.
• Live hints warn (without blocking) when the message is not in Conventional Commit format or the subject line is longer than 72 characters.
• Push after committing checkbox — untick it to commit locally only. It is disabled automatically when the repository has no remote.
• Ctrl+Enter / Cmd+Enter commits.
• ↻ Refresh re-reads the staged changes after you edit files.

If nothing was staged when you opened the editor, GitSnap stages everything and shows a notice saying so. Huge diffs are shortened for display only; the full change is still committed.

3. 🌿 Branch Dashboard — Ctrl+K B

A visual overview of every local branch.

Badges:

Actions:

• Checkout a branch (refused, with a clear message, if your uncommitted changes would be overwritten).
• + New Branch — choose a name and a start point (current branch or any other). If your team set a naming pattern, non-matching names get a warning.
• Delete asks for confirmation; Force Delete is offered only after Git reports the branch is not fully merged. The current branch can never be deleted.
• ⇣ Fetch All updates remote information; ↻ Refresh reloads the list.
• A filter box appears when you have more than 8 branches.

AI insights (AI mode): one-line tips such as "Rebase onto main before pushing" appear under branches that need attention. The list shows instantly — insights stream in afterwards and never slow it down.

4. 🧰 Advanced Toolkit — Ctrl+K T

Five tools in one panel.

📜 Log Explorer

Search the last 100 commits by author, message text and branch (default: current branch). Text search is literal and case-insensitive, so characters like ( or * are safe to type. Press Enter in any field to search.

📦 Stash Manager

• + Stash Changes with an optional message; tick include untracked to also stash new, untracked files.
• For each stash: View Diff, AI Summary (AI mode), Apply (keeps the stash), Pop (applies and removes it) and Drop (asks for confirmation — this permanently deletes it).
• Stashes are tracked by their unique ID, so if the list changed in the meantime GitSnap refuses the action and asks you to refresh, instead of touching the wrong stash.
• If applying a stash causes conflicts, GitSnap tells you — and a popped stash is kept, so nothing is lost.

🍒 Cherry-Pick

Copy a single commit onto your current branch.

1. In Log, search for the commit (use the Branch filter to look at another branch).
2. Switch to Cherry-Pick, choose the commit, and click 🍒 Cherry-Pick.

Clear messages cover every outcome: conflicts (with the commands to continue or abort), merge commits (not supported), and commits that are already on your branch (nothing is left half-done).

🔄 Rebase Preview (read-only)

Enter a base branch (e.g. main or origin/main) and click Preview. You see exactly the commits that git rebase <base> would replay, oldest first — commits already on the base are skipped, just as Git would. Nothing in your repository is changed.

🌳 Worktrees

Work on two branches at the same time in separate folders, without stashing.

1. Enter a folder outside your repository, e.g. ../my-feature.
2. Enter a branch: an existing local branch, a remote branch (a tracking branch is created), or a new name (created from your current commit).
3. Click + Add Worktree, then Open in New Window in the notification.

Existing worktrees are listed with their branch, commit and locked status.

5. 🔀 PR Prep Assistant — Ctrl+Alt+P

Draft a pull-request title and description.

1. Open the panel. Head is your current branch; Base is pre-selected (main, master or develop, local or remote) — change it from the dropdown if needed.
2. Review the list of commits that are on your branch but not on the base.
3. Click Generate PR Description.
4. Edit the title and Markdown body, then use 📋 Copy to paste them into GitHub, GitLab or any other host.

With AI you get a written summary; without AI (or if the AI request fails) you get a clean template with commits grouped under Features, Bug Fixes, Refactoring and so on, plus a Testing checklist. GitSnap never submits anything for you.

6. ✨ Natural-Language Git — Ctrl+K N (AI mode)

Describe what you want in plain English:

• "switch to main and fetch latest"
• "create a branch called feature/login from develop"
• "stash my work as wip"
• "show the last 10 commits"
• "undo my last commit"
• "delete branch feature/old"

How it stays safe:

1. The AI's answer is converted into a fixed list of supported operations — switch, create or delete a branch, undo last commit, fetch, show log, stash. Anything else is discarded. Nothing is ever run as a raw shell command.
2. You see every planned step and can untick any of them.
3. Destructive steps (deleting a branch, undoing a commit) require an extra confirmation.
4. Steps run in order and stop at the first failure, telling you what had already succeeded.
5. Your last 20 requests are offered for one-click reuse in that workspace.

Log output is written to the GitSnap output channel — click Show Output in the notification.

7. ↩️ Undo Last Commit — Ctrl+Alt+Z

Removes the last commit but keeps all its changes staged, so you can fix the message or add a forgotten file and commit again.

• A confirmation shows the commit you are about to undo.
• If that commit is already pushed, you are warned that undoing it locally will make your branch diverge from the remote.
• Works even on the very first commit of a repository.
• Refused while a merge, rebase or cherry-pick is in progress.

8. ⚙️ Settings panel & API keys

• GitSnap: Open Settings — enable/disable AI, choose provider and model, and store or remove the key for each provider.
• GitSnap: Set API Key — a quick prompt that stores the key for the current provider.

⌨️ Keyboard shortcuts

"Ctrl+K then B" means: press Ctrl+K, release, then press B. Ctrl+Alt+Enter is inactive while VS Code's Find/Replace or Search box has focus, so Replace All keeps working. To change any shortcut: File → Preferences → Keyboard Shortcuts and search for "GitSnap".

🛠️ Settings reference

The model and API key are chosen per provider in the Settings panel and are not part of settings.json.

Team setup — commit a .vscode/settings.json to share conventions:

{
  "gitsnap.commitTemplate.scopes": ["auth", "core", "ui", "docs", "infra"],
  "gitsnap.branchNaming.pattern": "^(feature|bugfix|hotfix|chore)/.+"
}

Each teammate still uses their own provider and key (or No-AI mode).

🛡 Safety guarantees

GitSnap is built so that a mistake — yours, an AI's or the network's — cannot quietly damage your repository.

• Nothing destructive without confirmation: branch deletion, force delete, dropping a stash, undoing a commit and destructive natural-language steps all ask first.
• Your staging is respected: if you staged specific files, only those are committed.
• No shell, no injection: Git is run directly with validated arguments. Branch names, commit IDs and stash references are checked before use, so input like --force is rejected rather than treated as an option.
• No hangs: every Git and AI operation has a time limit, and Git is never allowed to wait for a hidden password prompt.
• No collisions: GitSnap actions that change the same repository run one at a time.
• Honest results: if a commit succeeds but the push fails, you are told the commit exists locally.
• Mid-operation awareness: actions that would be unsafe during a merge, rebase or cherry-pick are refused with an explanation.
• Restricted Mode: GitSnap does not run in untrusted workspaces, because Git can execute hooks and commands configured inside a downloaded repository.

🔒 Privacy & security

• API keys live only in your OS keychain via VS Code SecretStorage — one per provider. They never appear in settings.json, the panels, logs or error messages.
• What is sent to AI (only when AI is enabled and you use a drafting feature): the staged diff (trimmed if very large) for commit messages, commit subjects for PR descriptions, a stash diff for stash summaries, branch metadata for insights, and your sentence for natural-language commands.
• Nothing is stored: diffs are held in memory only for the request that needs them. GitSnap has no telemetry and no server of its own.
• Fully offline: with Ollama/Tabby or No-AI mode, nothing leaves your machine.
• Logs: details of failures are written to the GitSnap output channel (View → Output → GitSnap) on your machine only.

🧯 Troubleshooting

❓ FAQ

Do I need an AI provider to use GitSnap? No. Set gitsnap.ai.enabled to false and every feature except Natural-Language Git works.

Is my code sent anywhere? Only when AI is enabled with a cloud provider and you use a drafting feature — and then only to the provider you chose. With Ollama, Tabby or No-AI mode, nothing leaves your machine.

Does GitSnap ever force-push or rewrite pushed history? No. It never force-pushes. Undo Last Commit is local and warns you if the commit was already pushed.

Will Fast Commit & Push commit files I didn't want? If you staged specific files, only those are committed. If nothing is staged, everything is staged — use the Commit Editor if you want to review first.

Which model should I use? Start with the default for your provider. On Groq, openai/gpt-oss-20b and llama-3.1-8b-instant are fast; for local use, llama3.2 or qwen2.5-coder work well on most laptops.

Can my team share conventions? Yes — commit gitsnap.commitTemplate.scopes and gitsnap.branchNaming.pattern in .vscode/settings.json. Keys stay personal.

I used an older version — are my key and model kept? Yes. On first start, a previously saved key is moved to the provider you have selected, and invalid old model names are discarded so the default is used.

👩‍💻 For developers

Prerequisites

Node.js 20+, Git, VS Code 1.134+.

Commands

npm install          # install dependencies (regenerates package-lock.json)
npm run typecheck    # type-check extension and webviews
npm test             # unit tests + integration tests against real temporary Git repositories
npm run build        # build dist/extension.js and dist/webview/*
npm run watch        # rebuild on every change
npm run lint         # ESLint
npm run package      # create gitsnap-<version>.vsix

Press F5 to start an Extension Development Host. Run Developer: Reload Window in that window after rebuilding.

Architecture

src/
├── extension/                 Node.js — runs inside the VS Code extension host
│   ├── extension.ts           command registration, Fast Commit & Push, Undo, NL Git
│   ├── git/
│   │   ├── runner.ts          spawns git: timeouts, non-interactive env, per-repo write lock
│   │   ├── index.ts           all Git operations with friendly, typed errors
│   │   ├── parsers.ts         parsing of git's machine-readable output
│   │   ├── validate.ts        ref / SHA / stash-ref validation
│   │   ├── repo.ts            finds the repository to act on
│   │   └── nlExecutor.ts      runs validated natural-language operations
│   ├── ai/
│   │   ├── index.ts           retries, timeouts, error handling, feature functions
│   │   ├── providers/         Groq/OpenAI/Tabby (OpenAI-compatible), Anthropic, Ollama
│   │   ├── prompts.ts, nl.ts  prompts and natural-language plan validation
│   │   └── text.ts, json.ts   output cleaning, PR template, robust JSON extraction
│   ├── webview/               panel hosts (CSP, Vite manifest lookup, message routing)
│   ├── secrets.ts             per-provider keys (SecretStorage) and models
│   └── log.ts                 GitSnap output channel
├── webview/                   Svelte 5 user interfaces + shared theme.css
├── types/                     message contracts and data shapes shared by both sides
└── test/                      vscode mock and test helpers

The extension host and the webviews never share runtime state: they communicate only through the typed messages in src/types/webviewMessages.ts. The webviews never receive API keys.

Testing notes

• Git tests create real repositories (including a local "remote") in a temporary folder and are skipped automatically if Git is not installed.
• AI tests replace fetch, so they never touch the network.
• vscode is mapped to src/test/vscode.mock.ts in vitest.config.ts.

📄 License

Distributed under the MIT License. Created by RohithSGowda — github.com/rohith-decent/GitSnap.