#setup

rs setup 命令用于安装仓库级 Git hooks，并在调用该命令的项目中运行 hooks。

#用法

rs setup [options]

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

在负责管理仓库 hooks 的项目 package.json 中添加 prepare 脚本：

{
  "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 脚本的存放目录，路径相对于 Git 仓库根目录。

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

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

使用自定义目录时，请将完整命令写入负责管理 hooks 的项目 package.json：

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

为避免通过父目录路径在仓库之外创建或覆盖 Git hook 文件，路径中不能包含 ..。

#--help

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

rs setup --help

#Hook 文件

默认目录结构如下：

.rstack/
└── hooks/
    ├── pre-commit        # 仓库 hook 脚本：编辑并提交
    └── _/                # 由 rs setup 生成；默认被 Git 忽略
        ├── .gitignore
        ├── .owner
        ├── 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 的退出码。运行 hook 前，Rstack 会切换到安装 hooks 的项目，并将该项目的 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 中，提供 Rstack 的项目可能位于 frontend/ 等子目录。从该目录运行 rs setup 时，hooks 仍会安装到 Git 仓库根目录：

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

Rstack 会将 frontend 记录为负责管理 hooks 的项目。hook 脚本仍位于仓库根目录，但会从 frontend 目录运行，因此可以直接使用其中的配置和依赖，无需显式执行 cd：

rs staged

一个 Git 仓库只能有一个 hooks owner。只有负责管理 hooks 的项目应在 prepare 脚本中调用 rs setup。其他项目调用时会收到警告并跳过。

如需更换 owner，请先从原项目的 prepare 脚本中移除 rs setup，删除生成的 _ 目录，再从新项目运行 rs setup。

#移除 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。
• 如果命令提示存在其他 hooks 配置，请先迁移或移除冲突配置，再重新运行该命令。
• 如果命令提示存在其他 Rstack owner，请按照 Monorepo 中的步骤转移 owner。

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。