#setup

rs setup 命令用于在当前 Git 仓库中安装项目级 Git hooks。

#用法

rs setup [options]

项目 hook 脚本默认存放在 .rstack/hooks。如果当前目录不属于 Git 仓库，命令会跳过安装。

在根目录 package.json 的 prepare 脚本中添加 rs setup，即可在安装依赖时自动生成 hook 文件：

{
  "scripts": {
    "prepare": "rs setup"
  }
}

执行一次该脚本，生成 hook 文件：

npm run prepare

yarn run prepare

pnpm run prepare

bun run prepare

例如，创建一个 pre-commit hook，并在其中运行 rs staged：

rs staged

#选项

#--hooks-dir

设置项目 hook 脚本的存放目录，路径相对于命令的当前目录。

rs setup --hooks-dir config/git-hooks

# 路径包含空格时需要使用引号
rs setup --hooks-dir "config/git hooks"

使用自定义目录时，请将完整命令写入根目录 package.json 的 prepare 脚本：

{
  "scripts": {
    "prepare": "rs setup --hooks-dir config/git-hooks"
  }
}

#--help

--help（或 -h）用于显示命令的用法和选项。

rs setup --help

#Hook 文件

默认目录结构如下：

.rstack/
└── hooks/
    ├── pre-commit        # 项目 hook 脚本：编辑并提交
    └── _/                # 由 rs setup 生成；默认被 Git 忽略
        ├── .gitignore
        ├── runner
        ├── pre-commit
        ├── commit-msg
        └── ...

与 _ 同级的文件是项目 hook 脚本。_ 目录包含生成文件，并由 Git 忽略。rs setup 会将 core.hooksPath 指向 .rstack/hooks/_；克隆仓库后或生成文件缺失时，请重新运行该命令。

#支持的 hooks

Rstack 支持以下客户端 Git hooks：

• pre-commit
• pre-merge-commit
• prepare-commit-msg
• commit-msg
• post-commit
• applypatch-msg
• pre-applypatch
• post-applypatch
• pre-rebase
• post-rewrite
• post-checkout
• post-merge
• pre-push
• pre-auto-gc

在与 _ 同级的位置创建对应的同名文件即可。

#Hook 运行时

Rstack 使用 POSIX sh -e 运行 hook 脚本，并转发 Git 提供的参数和标准输入，同时返回 hook 的退出码。运行时还会将 node_modules/.bin 添加到 PATH 开头。

#禁用与调试

将 RSTACK_HOOKS 设为 0，可以跳过安装或 hook 执行：

RSTACK_HOOKS=0 git commit -m "Skip hooks"

将 RSTACK_HOOKS 设为 2，可以跟踪 Rstack hook 运行时，包括调用 hook 脚本和处理退出码等步骤；如需跟踪 hook 脚本内部的命令，请在脚本中添加 set -x：

RSTACK_HOOKS=2 git commit -m "Trace hooks"

#配置 hook 运行环境

运行 hook 脚本前，Rstack 会加载以下可选的 POSIX shell 文件：

${XDG_CONFIG_HOME:-$HOME/.config}/rstack/hooks-init.sh

可以在其中初始化 Node.js 版本管理器、更新 PATH，或为当前用户设置 RSTACK_HOOKS=0。

#Monorepo

在 monorepo 中，项目可能位于 Git 仓库的子目录，例如 frontend/。从该目录运行 rs setup 时，hooks 目录会相对于项目创建，core.hooksPath 也会包含项目路径：

frontend/.rstack/hooks/
frontend/.rstack/hooks/_/
core.hooksPath=frontend/.rstack/hooks/_

Git 会从仓库根目录运行 hook。如果项目位于子目录，请在 hook 脚本中先切换到该目录，再执行项目命令：

cd frontend
pnpm test

一个 Git 仓库只有一个 core.hooksPath，因此应选择仓库根目录或其中一个子项目统一管理 hooks。

#移除 hooks

如需移除由 Rstack 管理的 hooks：

1. 从 prepare 脚本中移除 rs setup。

2. 删除仓库的 hooks 路径配置：

   git config --local --unset core.hooksPath

3. 删除 .rstack/hooks/ 或通过 --hooks-dir 指定的目录。

#故障排查

#Hook 未运行

• 确认 hook 脚本使用支持的名称，并与 _ 目录同级。
• 运行 git config --local --get core.hooksPath，检查配置的路径。
• 重新运行 rs setup，恢复生成文件及其可执行权限。
• 检查环境变量或初始化文件中是否设置了 RSTACK_HOOKS=0。

hook 脚本不需要可执行权限，因为 Rstack 会使用 sh 运行它。

#找不到命令

退出码为 127 时，Rstack 会打印实际生效的 PATH。如果 GUI Git 客户端找不到 Node.js 或包管理器，请在 hooks-init.sh 中初始化相关环境。

#Windows 与 Yarn

在 Windows 上，hooks 会通过 Git for Windows 自带的 POSIX shell 运行。请在 hook 中使用 LF 换行符和 / 路径分隔符。

Yarn PnP 不提供 node_modules/.bin。请通过 Yarn 脚本运行工具，例如 yarn run test；必要时可通过 hooks-init.sh 配置 Node.js 和 Yarn。