git-guardrails

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Guardrails

Git防护栏

Sets up a PreToolUse hook that intercepts and blocks dangerous git commands before Claude Code executes them.

配置PreToolUse钩子，在Claude Code执行危险git命令之前对其进行拦截和阻止。

When to Use This Skill

何时使用该技能

Activate when the user:

Wants to prevent destructive git operations from being run by the AI agent
Asks to add git safety hooks to Claude Code
Wants to block
```
git push
```
,
```
git reset --hard
```
, or other dangerous commands
Is setting up a new project and wants guardrails on git operations

当用户出现以下需求时激活：

希望阻止AI Agent执行破坏性git操作
要求为Claude Code添加git安全钩子
希望阻止
```
git push
```
、
```
git reset --hard
```
或其他危险命令
正在搭建新项目，希望为git操作添加防护措施

What Gets Blocked

会被拦截的内容

The following commands are intercepted and blocked before execution:

Pattern	Description
`git push`	All push variants (prevents unreviewed pushes)
`git push --force`	Force push (rewrites remote history)
`git push --force-with-lease`	Force push variant
`git reset --hard`	Discards all uncommitted changes
`git clean -f` / `git clean -fd`	Deletes untracked files permanently
`git branch -D`	Force-deletes a branch without merge check
`git checkout .`	Discards all working tree changes
`git restore .`	Discards all working tree changes
`git rebase` on main/master	Prevents rebase of protected branches

When blocked, Claude sees a message telling it that it does not have authority to run these commands. The user must run them manually if needed.

以下命令会在执行前被拦截：

匹配规则	描述
`git push`	所有push变体（阻止未审核的代码推送）
`git push --force`	强制推送（会改写远程仓库历史）
`git push --force-with-lease`	强制推送变体
`git reset --hard`	丢弃所有未提交的修改
`git clean -f` / `git clean -fd`	永久删除未追踪文件
`git branch -D`	不经过合并检查强制删除分支
`git checkout .`	丢弃工作区所有修改
`git restore .`	丢弃工作区所有修改
基于main/master分支执行 `git rebase`	阻止对受保护分支执行变基操作

命令被拦截时，Claude会收到提示，告知它没有权限执行这些命令。如果需要执行，用户必须手动运行。

Setup Steps

安装步骤

Step 1: Ask Scope

步骤1：确认生效范围

Ask the user: install for this project only (

.claude/settings.json

) or all projects (

~/.claude/settings.json

询问用户：是仅当前项目生效（

.claude/settings.json

）还是所有项目生效（

~/.claude/settings.json

）？

Step 2: Copy the Hook Script

步骤2：复制钩子脚本

The bundled script is at: reference/block-dangerous-git.sh

Copy it to the target location based on scope:

Project:
```
.claude/hooks/block-dangerous-git.sh
```
Global:
```
~/.claude/hooks/block-dangerous-git.sh
```

Make it executable:

bash

chmod +x <path-to-script>

附带的脚本路径为：reference/block-dangerous-git.sh

根据生效范围将脚本复制到目标位置：

项目级：
```
.claude/hooks/block-dangerous-git.sh
```
全局：
```
~/.claude/hooks/block-dangerous-git.sh
```

为脚本添加可执行权限：

bash

chmod +x <path-to-script>

Step 3: Add Hook to Settings

步骤3：将钩子添加到配置文件

Add to the appropriate settings file.

Project scope (

.claude/settings.json

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
          }
        ]
      }
    ]
  }
}

Global scope (

~/.claude/settings.json

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/block-dangerous-git.sh"
          }
        ]
      }
    ]
  }
}

If the settings file already exists, merge the hook into the existing

hooks.PreToolUse

array. Do not overwrite other settings.

添加到对应的配置文件中。

项目级生效（

.claude/settings.json

）：

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
          }
        ]
      }
    ]
  }
}

全局生效（

~/.claude/settings.json

）：

json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/block-dangerous-git.sh"
          }
        ]
      }
    ]
  }
}

如果配置文件已存在，请将钩子合并到现有

hooks.PreToolUse

数组中，不要覆盖其他配置。

Step 4: Ask About Customization

步骤4：确认是否需要自定义

Ask if the user wants to add or remove any patterns from the blocked list. Edit the copied script accordingly.

Common additions users may want:

Block
```
git stash drop
```
(prevents accidental stash loss)
Block
```
git tag -d
```
(prevents tag deletion)
Allow
```
git push
```
but only block
```
--force
```
variants

询问用户是否需要在拦截列表中添加或移除匹配规则，根据需求编辑复制的脚本即可。

用户可能需要添加的常见拦截规则：

拦截
```
git stash drop
```
（防止意外丢失暂存内容）
拦截
```
git tag -d
```
（防止标签被删除）
允许
```
git push
```
仅拦截带
```
--force
```
的变体

Step 5: Verify Installation

步骤5：验证安装

Run a quick test to confirm the hook works:

bash

echo '{"tool_input":{"command":"git push origin main"}}' | <path-to-script>

Expected result: exits with code 2 and prints a

BLOCKED

message to stderr.

Run a second test with a safe command:

bash

echo '{"tool_input":{"command":"git status"}}' | <path-to-script>

Expected result: exits with code 0 (allowed).

运行快速测试确认钩子正常工作：

bash

echo '{"tool_input":{"command":"git push origin main"}}' | <path-to-script>

预期结果：退出码为2，且向标准错误输出

BLOCKED

信息。

使用安全命令运行第二次测试：

bash

echo '{"tool_input":{"command":"git status"}}' | <path-to-script>

预期结果：退出码为0（命令被允许执行）。

How It Works

工作原理

Claude Code supports PreToolUse hooks that run before any tool invocation. The hook:

Receives the tool input as JSON on stdin
Extracts the
```
command
```
field using
```
jq
```
Checks the command against a list of dangerous patterns
If a match is found, exits with code 2 (which tells Claude the command is blocked)
If no match, exits with code 0 (which allows normal execution)

Claude Code支持PreToolUse钩子，会在任何工具调用前运行。该钩子的运行逻辑：

从标准输入接收JSON格式的工具输入
使用
```
jq
```
提取
```
command
```
字段
将命令与危险规则列表进行匹配
如果匹配到规则，以退出码2退出（告知Claude该命令被拦截）
如果未匹配到规则，以退出码0退出（允许正常执行）

Important Notes

注意事项

The hook only blocks commands run by the AI agent. The user can still run any git command manually in their terminal.
The blocked patterns use regex matching, so
```
git push
```
also catches
```
git push origin main --force
```
.
If
```
jq
```
is not installed, the script will fail open (allow all commands). Ensure
```
jq
```
is available.
The hook does not modify any git configuration; it only intercepts Claude Code tool calls.

该钩子仅拦截AI Agent运行的命令，用户仍然可以在终端手动运行任何git命令
拦截规则使用正则匹配，因此
```
git push
```
也会命中
```
git push origin main --force
```
这类命令
如果未安装
```
jq
```
，脚本会默认放行所有命令，请确保环境中已安装
```
jq
```
该钩子不会修改任何git配置，仅会拦截Claude Code的工具调用