🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
@selfagency/git-mcp
Advanced tools
@selfagency/git-mcp - npm Package Compare versions
| { | ||
| "skill_name": "git-mcp-workflow", | ||
| "evals": [ | ||
| { | ||
| "id": 1, | ||
| "prompt": "I accidentally committed directly on main and have not pushed yet. Help me move that work onto a feature branch safely without losing anything.", | ||
| "expected_output": "A safe recovery workflow that inspects repository state first, avoids shell git, and uses git-mcp operations to preserve work before moving it off main.", | ||
| "assertions": [ | ||
| "The workflow starts by inspecting repository state before mutation", | ||
| "The response uses git-mcp tools instead of raw shell git commands", | ||
| "The suggested recovery path is safe for unpublished local history", | ||
| "The response avoids destructive actions unless they are justified" | ||
| ] | ||
| }, | ||
| { | ||
| "id": 2, | ||
| "prompt": "My bugfix branch is ready for review. I want to sync it with the latest upstream, clean up the history if it is safe, and push it for PR prep.", | ||
| "expected_output": "A review-preparation workflow that fetches and inspects state, chooses a safe rebase or equivalent cleanup path, and pushes using git-mcp with appropriate safeguards.", | ||
| "assertions": [ | ||
| "The workflow includes fetch or equivalent remote inspection before history cleanup", | ||
| "The response distinguishes safe local cleanup from risky published-history rewrite", | ||
| "The response uses git-mcp tools for rebase or push behavior", | ||
| "The response mentions force-with-lease only when it is actually warranted" | ||
| ] | ||
| }, | ||
| { | ||
| "id": 3, | ||
| "prompt": "Explain when I should use revert instead of reset on a shared branch, and explain it in terms of the git-mcp tools I would use.", | ||
| "expected_output": "A clear explanation of shared-history-safe undo versus local history rewrite, mapped to the corresponding git-mcp tools and risks.", | ||
| "assertions": [ | ||
| "The explanation distinguishes shared branch safety from local-only rewrite", | ||
| "The explanation maps the concepts to specific git-mcp tools", | ||
| "The explanation warns against rewriting published history casually" | ||
| ] | ||
| } | ||
| ] | ||
| } |
| [ | ||
| { | ||
| "query": "I need to undo my last local commit safely and keep the changes so I can recommit them properly.", | ||
| "should_trigger": true | ||
| }, | ||
| { | ||
| "query": "Can you help me inspect the repo state and tell me whether a rebase is already in progress?", | ||
| "should_trigger": true | ||
| }, | ||
| { | ||
| "query": "I want to create a release branch from develop using git flow and publish it.", | ||
| "should_trigger": true | ||
| }, | ||
| { | ||
| "query": "my branch is messy — fetch upstream, check if it's safe to rebase, then prep it for review", | ||
| "should_trigger": true | ||
| }, | ||
| { | ||
| "query": "Can you walk me through recovering from a detached HEAD using the MCP git tools?", | ||
| "should_trigger": true | ||
| }, | ||
| { | ||
| "query": "Open a GitHub pull request for my current branch and request review from the backend team.", | ||
| "should_trigger": false | ||
| }, | ||
| { | ||
| "query": "Review this TypeScript diff for correctness and point out any race conditions.", | ||
| "should_trigger": false | ||
| }, | ||
| { | ||
| "query": "Write a shell script that parses git log output and generates a markdown changelog.", | ||
| "should_trigger": false | ||
| }, | ||
| { | ||
| "query": "Summarize the latest release notes from this repository for a non-technical audience.", | ||
| "should_trigger": false | ||
| }, | ||
| { | ||
| "query": "Create a GitHub issue to track flaky tests in CI and add a reproduction checklist.", | ||
| "should_trigger": false | ||
| } | ||
| ] |
| [ | ||
| { | ||
| "query": "Please stash my local changes, switch to another branch, and bring me back later without losing anything.", | ||
| "should_trigger": true | ||
| }, | ||
| { | ||
| "query": "I need to inspect reflog history and figure out how to recover a branch tip I moved by mistake.", | ||
| "should_trigger": true | ||
| }, | ||
| { | ||
| "query": "Set up a worktree for a hotfix branch while keeping my current feature branch untouched.", | ||
| "should_trigger": true | ||
| }, | ||
| { | ||
| "query": "Draft a CONTRIBUTING.md section that explains our pull request etiquette.", | ||
| "should_trigger": false | ||
| }, | ||
| { | ||
| "query": "Write a tutorial explaining the history of Git and why Linus Torvalds created it.", | ||
| "should_trigger": false | ||
| }, | ||
| { | ||
| "query": "Build a dashboard that charts commit frequency by author over time.", | ||
| "should_trigger": false | ||
| } | ||
| ] |
| # Explaining Git concepts with `git-mcp` | ||
| Use this reference when the user wants an explanation rather than an action. | ||
| ## Core concepts | ||
| - **Working tree, index, and committed history**: explain what is changed now, what is staged, and what is already recorded. | ||
| - **Branches as movable refs**: a branch name points to a commit and moves when new commits are added. | ||
| - **`HEAD`**: the current checkout target. | ||
| - **Fast-forward versus merge commit**: whether history stays linear or records an explicit merge. | ||
| - **Local rewrite versus shared-history preservation**: rebase and reset rewrite local history; revert preserves shared history. | ||
| - **Reflog**: the recovery ledger for recent ref movements. | ||
| ## Tool mapping for explanations | ||
| - staging and working tree: `git_status action=status`, `git_status action=diff`, `git_commits action=add`, `git_commits action=restore` | ||
| - commit history and refs: `git_history action=log`, `git_history action=show`, `git_branches action=list`, `git_history action=reflog` | ||
| - merge and rebase state: `git_context action=summary`, `git_workspace action=rebase`, `git_workspace action=cherry_pick` | ||
| ## Explanation pattern | ||
| 1. Name the concept in plain language. | ||
| 2. Point to the `git-mcp` tool that reveals it. | ||
| 3. Connect it to the user's task or risk. | ||
| 4. If the task affects published history, call that out explicitly. |
| # Shell safety for Git operations | ||
| Do not run `git` directly in a shell when a `git-mcp` tool exists. | ||
| ## Why this matters | ||
| Shell Git commands are a poor fit for agent execution because commit messages, branch names, refs, and file paths often contain spaces, quotes, newlines, or characters that shells interpret specially. | ||
| Common failure modes: | ||
| - commit messages truncated at the first space or quote | ||
| - arguments interpreted as flags | ||
| - multiline messages collapsed or silently dropped | ||
| - word-splitting breaking file paths with spaces | ||
| - quote nesting errors that leave the shell waiting for input | ||
| - accidental command substitution from `$` or backticks | ||
| These failures are often silent: the command may appear to work while producing the wrong result. | ||
| ## Safe default | ||
| Use `git-mcp` tools instead. Their inputs are typed, validated, and passed as structured argument arrays without shell interpolation. | ||
| ## Narrow exceptions | ||
| Only consider shell Git as a last resort when no MCP tool covers the operation, such as: | ||
| - interactive patch staging | ||
| - interactive rebase editing | ||
| - deep history surgery with tools outside the MCP surface | ||
| - repo-local hook installation commands | ||
| Even in those cases, exhaust the MCP tool surface first and explain the risk before proceeding. |
+1
-1
| { | ||
| "name": "@selfagency/git-mcp", | ||
| "version": "0.2.1", | ||
| "version": "0.2.2", | ||
| "description": "A Git MCP server that doesn't suck", | ||
@@ -5,0 +5,0 @@ "keywords": [ |
| --- | ||
| name: git-mcp-workflow | ||
| description: 'Use for repositories managed through the git-mcp server when an agent needs to inspect repository state, create commits, manage branches and remotes, rebase, cherry-pick, stash, bisect, work with worktrees, handle Git Flow or git-flow-next-style workflows, manage tags, recover from mistakes, or explain Git concepts using MCP tools instead of raw git CLI commands. Especially relevant for prompts about git_status, git_commit, git_push, git_rebase, git_cherry_pick, git_worktree, git_stash, git_reflog, git_flow, git_lfs, submodules, PR preparation, release tagging, and Git recovery. IMPORTANT: Never use shell/terminal to run git commands directly; always use git-mcp MCP tools instead.' | ||
| description: Use this skill for repositories managed through the git-mcp server when the task involves Git inspection, staging or committing, branches, remotes, rebase, cherry-pick, stash, bisect, worktrees, Git Flow, LFS, release tagging, PR preparation, or recovery. Prefer git-mcp tools over shell git commands, including when the user asks in raw Git terms such as git_status, git_commit, git_push, git_rebase, git_reflog, git_flow, submodules, or “undo this safely”. | ||
| --- | ||
@@ -10,35 +10,13 @@ | ||
| This skill adapts common Git guidance for a world where the preferred interface is the server's tool catalog, not ad-hoc shell commands. It covers both everyday Git work and the spicier recovery and history-editing cases. | ||
| Use it to translate everyday Git tasks and recovery tasks into the server's safe tool surface instead of ad-hoc shell commands. | ||
| ## Why LLMs Must Not Use the Git CLI | ||
| ## Core rule | ||
| **Using `git` directly via the shell is highly error-prone for LLMs and should be considered forbidden except as a narrow last resort.** | ||
| - Always use `git-mcp` MCP tools for Git operations. | ||
| - Never invoke `git` via shell unless the operation truly is not covered by any `git-mcp` tool. | ||
| - Inspect repository state before mutating it. | ||
| - Prefer the most reversible safe operation that satisfies the user's intent. | ||
| The root cause is structural: Git commands frequently require commit messages, branch names, file paths, and other string arguments that contain spaces, quotes, special characters, or newlines. Shell interpreters handle quoting through multiple layers (single quotes, double quotes, `$'...'` escapes, heredocs) and the rules differ between `sh`, `bash`, and `zsh`. LLMs routinely produce subtly malformed quoting that causes: | ||
| If you need the rationale behind the shell restriction, read `references/shell-safety.md`. | ||
| - Commit messages truncated at the first space or quote character | ||
| - Arguments interpreted as flags (a message starting with `-` becomes a flag) | ||
| - Multi-line messages collapsed to one line or silently dropped | ||
| - Shell word-splitting breaking file paths that contain spaces | ||
| - Quote nesting errors causing the command to hang waiting for a closing delimiter | ||
| - `$` or backtick characters in messages accidentally triggering command substitution | ||
| These errors are often **silent**: the command appears to succeed, but the result is wrong (e.g., a commit message of `"fix"` instead of `"fix: resolve null pointer in auth handler"`). LLMs typically cannot observe the actual error because the shell may not surface it clearly in the tool output. | ||
| **The `git-mcp` server solves all of this.** Every tool parameter is a typed, validated field that the server passes directly to `simple-git` as an argument array, bypassing shell interpretation entirely. There are no quoting problems, no interpolation hazards, and no silent truncation. | ||
| **Rule: Always use `git-mcp` MCP tools for git operations. Never invoke `git` via shell unless the specific operation is genuinely not available through any `git-mcp` tool.** | ||
| ## When to Use This Skill | ||
| Use this skill when you need to: | ||
| - Inspect repository state before making changes | ||
| - Stage, commit, branch, fetch, pull, and push via MCP tools | ||
| - Rebase, cherry-pick, stash, bisect, tag, or use worktrees | ||
| - Recover from resets, detached HEAD, or other Git mishaps | ||
| - Choose between GitHub Flow, classic Git Flow, git-flow-next-style presets, trunk-based, or release workflows | ||
| - Prepare a branch for review or release while preserving safety | ||
| - Explain Git concepts in terms of the `git-mcp` tool surface | ||
| ## Core Operating Rules | ||
@@ -123,22 +101,13 @@ | ||
| ## Registered Tool Surface | ||
| ## Common tool families | ||
| The server exposes these tools (and only these). | ||
| - `git_context`, `git_status`, `git_history` for inspection | ||
| - `git_commits`, `git_branches`, `git_remotes` for everyday changes | ||
| - `git_workspace` for stash, rebase, cherry-pick, merge, bisect, tag, worktree, and submodule flows | ||
| - `git_flow` for git-flow-next-style lifecycle operations | ||
| - `git_lfs` for large-file workflows | ||
| - `git_docs` when the user needs authoritative Git usage help | ||
| | Tool | Actions | | ||
| | --------------- | ------------------------------------------------------------------------------------------------------- | | ||
| | `git_context` | `summary` (default), `search`, `get_config`, `set_config`, `aliases` | | ||
| | `git_status` | `status` (default), `diff`, `diff_main` | | ||
| | `git_history` | `log` (default), `show`, `reflog`, `blame`, `lg`, `who` | | ||
| | `git_commits` | `add`, `restore`, `commit`, `reset`, `revert`, `undo`, `nuke`, `wip`, `unstage`, `amend` | | ||
| | `git_branches` | `list` (default), `create`, `delete`, `rename`, `checkout`, `set_upstream`, `recent` | | ||
| | `git_remotes` | `list` (default), `manage`, `fetch`, `pull`, `push` | | ||
| | `git_workspace` | `stash`, `stash_all`, `rebase`, `cherry_pick`, `merge`, `bisect`, `tag`, `worktree`, `submodule` | | ||
| | `git_flow` | `operation=init/overview/config/topic/control` | | ||
| | `git_lfs` | `track`, `untrack`, `ls-files`, `status`, `pull`, `push`, `install`, `migrate-import`, `migrate-export` | | ||
| | `git_docs` | `search`, `man` | | ||
| | `git_ping` | _(health check)_ | | ||
| See `references/tooling-map.md` for the full tool and action catalog. | ||
| See `references/tooling-map.md` for full parameter details. | ||
| ## Recommended Workflow | ||
@@ -169,6 +138,14 @@ | ||
| ## Tool Selection | ||
| ## Validation checklist | ||
| Read `references/tooling-map.md` for the MCP-first command mapping. | ||
| Before you finish, confirm all of the following: | ||
| - Git operations used `git-mcp` tools, not shell `git` | ||
| - Repository context was inspected before any mutation | ||
| - The chosen action matches the branch safety level: local-only rewrite versus shared-history-safe revert | ||
| - Any forceful action was explicitly requested and gated by the relevant server setting | ||
| - Hook or CI failures were treated as real failures rather than bypassed casually | ||
| For multi-step or risky work, keep a short checklist in your scratchpad and update it as you go. | ||
| ## Playbooks | ||
@@ -185,19 +162,4 @@ | ||
| ## Git Concepts to Explain Clearly | ||
| If the user wants conceptual Git explanations, read `references/git-concepts.md`. | ||
| When the user needs explanation rather than action, anchor your answer in these concepts: | ||
| - working tree, index, and committed history | ||
| - branches as movable refs | ||
| - `HEAD` as the current pointer | ||
| - fast-forward versus merge commit history | ||
| - local-only history rewriting versus shared history preservation | ||
| - reflog as the recovery ledger | ||
| Explain the concept using the MCP tool that reveals it: | ||
| - status and staging area: `git_status action=status`, `git_status action=diff`, `git_commits action=add`, `git_commits action=restore` | ||
| - refs and branch movement: `git_history action=log`, `git_history action=show`, `git_branches action=list`, `git_history action=reflog` | ||
| - merge and rebase state: `git_context action=summary`, `git_workspace action=rebase`, `git_workspace action=cherry_pick` | ||
| ## Repository-Specific Notes for `git-mcp` | ||
@@ -220,4 +182,7 @@ | ||
| - `references/workflow-playbooks.md` | ||
| - `references/git-flow-next.md` | ||
| - `references/shell-safety.md` | ||
| - `references/git-concepts.md` | ||
| - `docs/tools/index.md` | ||
| - `docs/guide/safety.md` | ||
| - `docs/development/contributing.md` |
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is too big to display
No alert changes
Improved metrics
- Total package byte prevSize
629438
15.93%- Number of package files
14
55.56%- Lines of code
5691
20.16%No dependency changes