npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

git-safety-guard

v0.1.1

Published

Backup-then-allow guard for discarding git commands. Auto-backs up diff + untracked + stash before checkout/restore/reset --hard/clean/stash drop, then lets the command run. pi extension + PreToolUse hook CLI.

Readme

git-safety-guard

备份后放行的 git 安全守卫 — 丢弃型 git 命令执行前自动备份 diff + untracked + stash,然后放行。可能该丢、但绝不无声丢。

同类工具分两派:阻断型(dcg、codex-safeguard 等,PreToolUse 拒绝危险命令)和快照型(cowback、git-rewind,每回合全量快照)。本工具走第三条路——让命令照跑,事前留底,可恢复。

安装与启用

1. pi(原生扩展)

pi install npm:git-safety-guard

包内 package.json 通过 pi.extensions 自动声明,启用后立即生效,无需额外配置。

npm 未解封前的过渡安装(等效,从 GitHub 源拉取):

pi install git:github.com/FnSGit/[email protected]

或从 Releases 下载 tarball:

pi install https://github.com/FnSGit/git-safety-guard/releases/download/v0.1.0/git-safety-guard-0.1.0.tgz

2. Claude Code(PreToolUse hook)

在 ~/.claude/settings.json(项目级则 .claude/settings.json)的 hooks.PreToolUse 加入:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "git-safety-guard hook"
          }
        ]
      }
    ]
  }
}

3. Codex(hooks.json)

在 .codex/hooks.json 加入类似配置(事件名与字段名以 Codex 当前文档为准——本工具消费 PreToolUse 的 tool_input.command 或 input.command,可识别 turn_id 字段以判定 Codex 来源):

{
  "hooks": [
    {
      "event": "PreToolUse",
      "command": "git-safety-guard hook"
    }
  ]
}

未知来源 payload 一律 fail-open:stdout 留空、stderr 写一行提示、exit 0。

覆盖的丢弃命令

| 命令 | 说明 | |---|---| | git checkout <path> / git checkout HEAD -- <path> / git checkout -- <path> / git checkout <sha> -- <path> / git checkout <ref> <path> / git checkout . | 还原路径(含带 -- 与不带 -- 两种形式) | | git checkout <branch-or-sha> / git checkout -f <branch-or-sha> | 切分支(含 force) | | git restore <path> / git restore . | 丢弃 working tree | | git switch -f / git switch --discard-changes | 强制切换 | | git reset --hard [<commit>] | 硬重置 | | git clean -f / git clean -fd / git clean -fdx / git clean --force / git clean --force -d | 删除未跟踪文件(短选项 -f* 与长选项 --force) | | git stash drop [stash@{N}] / git stash clear | 破坏 stash |

复合命令按 && / || / ; / 换行切段后匹配(cd /tmp && git reset --hard 会命中)。

cd 前缀解析:命中段之前的 cd <dir> 决定备份目录(取最后一个 cd 段);cd -、裸 cd、解析失败 → 回退会话 cwd;命中段之后的 cd 被忽略(已晚)。这保证 cd <other-repo> && git reset --hard 备份落点正确。

显式排除:git restore --staged、git checkout -b、git stash pop / apply / branch、git reset(软/mixed)、git branch -D(不在 v0.1 范围)。

恢复与列表

git-safety-guard list                  # 列出所有备份(时间戳 / cwd / 改动量摘要)
git-safety-guard restore latest        # 恢复最近一次备份
git-safety-guard restore 2026-09-13T20-30-00-123Z
git-safety-guard restore latest --dry-run
git-safety-guard restore latest --force   # untracked 回填时覆盖已存在文件

恢复语义(diff.patch 任何失败整体中止,不部分修改;stash/untracked 跳过而非中止):

  1. 对当前状态再做一次自保备份(恢复动作本身也可能丢弃改动;即使 --dry-run 也会生成,落在 BACKUP_ROOT,不触碰仓库)
  2. git apply --check 校验 diff.patch,失败则中止并报告自保目录
  3. git apply 应用 diff.patch
  4. 对 stash/ 下每个 stash patch 依次 --check:git apply 回填到工作树(不重建 git stash list);冲突的 patch 跳过并在摘要中报告
  5. 把 untracked/ 下文件复制回仓库相对路径;已存在的同名文件默认跳过,--force 才覆盖

--dry-run:完全不动仓库文件(diff.patch / untracked / stash 全部不写);仍会做一次自保备份(守卫自身保护);输出预览"将恢复 / 将应用 / 将跳过"。

恢复不重建 stash 栈——stash/ 下的 patch 以 git apply 回填到工作树。

环境变量

| 变量 | 默认 | 说明 | |---|---|---| | GIT_SAFETY_GUARD_BACKUP_ROOT | ~/.git-safety-guard/backups/ | 备份根目录,pi 与 CLI 共用 | | GIT_SAFETY_GUARD_QUIET | 未设 | 设为 1 关闭提示输出(备份照做,可用 list 查询) | | GIT_SAFETY_GUARD_WORKER_DETECT | 未设 | 设为 1 开启并行 pi RPC worker 检测(仅 pi 入口,会话启动时 ctx.ui.notify 提示) |

备份产物

每次丢弃命令触发后,在 BACKUP_ROOT/<ISO 时间戳>/ 生成:

<ISO 时间戳>/
├─ diff.patch          # git diff + git diff --staged(untracked 不在其中)
├─ untracked/          # ls-files --others --exclude-standard 逐个复制
│  └─ <仓库相对路径原样>
├─ stash/              # 仅 stash drop / stash clear 触发
│  └─ stash-N.patch    # git stash show -p --include-untracked stash@{N}
└─ manifest.json       # {timestamp, cwd, repoRoot, triggerCommand, agent,
                       #  diffStat, untrackedFiles, untrackedTruncated,
                       #  stashRefs, stashList, versions}

untracked 超过 500 个文件时只备份清单不复制内容,manifest.untrackedTruncated: true;提示文本同步追加“未备份实体内容”说明以避免表面安全。备份目录无自动清理——list 暴露数量,可手动 rm -rf 旧条目。

局限

  • fail-open:备份失败 / 解析失败 / 任何异常一律放行原命令并 exit 0。本工具是备份器不是闸门,阻断失败后果比备份失败更重。如果你需要硬阻断,请搭配 dcg 等阻断型工具。
  • 不做 shell 解析:引号内文本可能误报(如 echo "git reset --hard")。误报成本仅为多做一次空备份,可接受。如需严格语义,请改造 src/core/detect.ts 的分段逻辑。
  • detect 变体覆盖边界(v0.1):
    • 覆盖:short options -f/-fd/-fdx(clean)、long --force(clean)、带 -- 的 checkout 路径、不带 -- 的 checkout <ref> <path>、reset --hard、switch -f/--discard-changes、复合命令分段、cd 前缀解析
    • 未覆盖(v0.2 候选):选项顺序变体如 git reset -q --hard、long --force 的 git switch --force <branch>、git clean 之外的 flag 组合、未在表格的 --force-style long options
  • 恢复不重建 stash 栈:stash/ 下的 patch 以 git apply 还原到工作树,不会恢复 git stash list 中的条目。如需重建栈,属 v0.2 范围。
  • 并行 pi worker 污染:默认关闭 worker 检测;开启后会话启动时 ctx.ui.notify 提示同 cwd 的 pi --mode rpc 进程,但需你自行确认 worker 已停止(ps 扫描依赖 BSD ps 字段格式,Linux 下需自行验证)。
  • 覆盖范围仅 git 丢弃类:本工具不管 rm -rf、非 git 命令、shell 注入等更广泛的风险面。

许可证

MIT — Copyright (c) 2026 FnSGit