docs: document rs setup --force (#404)

Author: chenjiahan

website/docs/en/guide/cli/setup.mdx

@@ -41,12 +41,26 @@ rs staged
 
 :::warning Existing Git hook managers
 
-`rs setup` updates the repository's [`core.hooksPath`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-corehooksPath). It skips installation when another hooks path or existing Git hook is detected. Migrate the required hooks and remove the existing hooks configuration before running the command.
+`rs setup` updates the repository's [`core.hooksPath`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-corehooksPath). It skips installation when another hooks path or existing Git hook is detected. Run `rs setup --force` to install Rstack hooks anyway.
 
 :::
 
 ## Options
 
+### `--force`
+
+`--force` (or `-f`) installs Rstack hooks even when an existing Git hooks setup is detected:
+
+```bash
+rs setup --force
+```
+
+Rstack preserves the existing hook files and sets `core.hooksPath` to its generated hooks directory. While this setting is active, Git no longer runs hooks from the previous location.
+
+:::tip
+Run `rs setup --force` only once. Use `rs setup` without `--force` in the `prepare` script.
+:::
+
 ### `--hooks-dir`
 
 Sets the directory for hook scripts, relative to the Git repository root.
@@ -171,23 +185,37 @@ To change the owner, remove `rs setup` from the previous project's `prepare` scr
 To remove hooks managed by Rstack CLI:
 
 1. Remove `rs setup` from the `prepare` script.
-2. Unset the repository's hooks path:
+2. Check which Git configuration scope defines the active hooks path:
+
+   ```bash
+   git config --show-scope --get core.hooksPath
+   ```
+
+3. Unset the hooks path in the reported scope. For `local`, run:
 
    ```bash
    git config --local --unset core.hooksPath
    ```
 
-3. Delete `.rstack/hooks/`, or the directory passed to `--hooks-dir`.
+   For `worktree`, run:
+
+   ```bash
+   git config --worktree --unset core.hooksPath
+   ```
+
+   If `--force` previously preserved hooks under `.git/hooks`, unsetting the path reactivates those files. Delete any obsolete files first if you do not want them to run.
+
+4. Delete `.rstack/hooks/`, or the directory passed to `--hooks-dir`.
 
 ## Troubleshooting
 
 ### Hook does not run
 
 - Check that the hook script has a [supported name](#supported-hooks) and is next to the `_` directory.
-- Run `git config --local --get core.hooksPath` and verify the configured path.
+- Run `git config --show-scope --get core.hooksPath` and verify the effective scope and path.
 - Rerun `rs setup` to restore generated files and executable permissions.
 - Check that `RSTACK_HOOKS` is not set to `0` in the environment or initialization file.
-- If another hooks setup is reported, migrate or remove the conflicting setup before rerunning the command.
+- If another hooks setup is reported, run `rs setup --force`.
 - If another project is reported as the hooks owner, follow the ownership transfer steps in [Monorepo](#monorepo).
 
 Hook scripts do not need to be executable because Rstack CLI runs them with `sh`.

website/docs/en/guide/git-hooks.mdx

@@ -36,14 +36,14 @@ Run the script once to install the hooks:
 `rs setup` sets the repository's `core.hooksPath` to `.rstack/hooks/_`. Verify the installation with:
 
 ```bash
-git config --local --get core.hooksPath
+git config --get core.hooksPath
 # .rstack/hooks/_
 ```
 
 :::tip
 
 - The `_` directory is generated dynamically and ignored by Git by default.
-- If `rs setup` detects another hooks path or existing Git hooks, it skips installation. Migrate any hooks you want to keep, remove the existing configuration, and then try again. See the [`rs setup` guide](./cli/setup#hook-files) for details.
+- If `rs setup` detects another hooks path or existing Git hooks, it skips installation. Run `rs setup --force` to install Rstack hooks anyway. See the [`rs setup` guide](./cli/setup) for details.
 
 :::
 

website/docs/zh/guide/cli/setup.mdx

@@ -41,12 +41,26 @@ rs staged
 
 :::warning 已有 Git hook 管理工具
 
-`rs setup` 会更新仓库的 [`core.hooksPath`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-corehooksPath)。检测到其他 hooks 路径或已有 Git hook 时，命令会跳过安装。请先迁移所需的 hooks 并移除已有 hooks 配置，再运行该命令。
+`rs setup` 会更新仓库的 [`core.hooksPath`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-corehooksPath)。检测到其他 hooks 路径或已有 Git hook 时，命令会跳过安装。可运行 `rs setup --force` 强制安装 Rstack hooks。
 
 :::
 
 ## 选项 \{#options}
 
+### `--force`
+
+检测到已有 Git hooks 配置时，可使用 `--force`（或 `-f`）强制安装 Rstack hooks：
+
+```bash
+rs setup --force
+```
+
+Rstack 会保留原有 hook 文件，并将 `core.hooksPath` 指向 Rstack 生成的 hooks 目录。该配置生效期间，Git 不再执行原路径下的 hooks。
+
+:::tip
+`rs setup --force` 只需运行一次。`prepare` 脚本中应使用不带 `--force` 的 `rs setup`。
+:::
+
 ### `--hooks-dir`
 
 设置 hook 脚本的存放目录，路径相对于 Git 仓库根目录。
@@ -171,23 +185,37 @@ rs staged
 如需移除由 Rstack CLI 管理的 hooks：
 
 1. 从 `prepare` 脚本中移除 `rs setup`。
-2. 删除仓库的 hooks 路径配置：
+2. 检查当前生效的 hooks 路径来自哪个 Git 配置作用域：
+
+   ```bash
+   git config --show-scope --get core.hooksPath
+   ```
+
+3. 根据输出，在对应作用域中取消 hooks 路径配置。作用域为 `local` 时运行：
 
    ```bash
    git config --local --unset core.hooksPath
    ```
 
-3. 删除 `.rstack/hooks/` 或通过 `--hooks-dir` 指定的目录。
+   作用域为 `worktree` 时运行：
+
+   ```bash
+   git config --worktree --unset core.hooksPath
+   ```
+
+   如果之前通过 `--force` 保留了 `.git/hooks` 下的 hooks，取消路径配置会重新启用这些文件。如果不希望它们运行，请先删除不再需要的文件。
+
+4. 删除 `.rstack/hooks/` 或通过 `--hooks-dir` 指定的目录。
 
 ## 故障排查 \{#troubleshooting}
 
 ### Hook 未运行 \{#hook-does-not-run}
 
 - 确认 hook 脚本使用[支持的名称](#supported-hooks)，并与 `_` 目录同级。
-- 运行 `git config --local --get core.hooksPath`，检查配置的路径。
+- 运行 `git config --show-scope --get core.hooksPath`，检查当前生效的配置作用域和路径。
 - 重新运行 `rs setup`，恢复生成文件及其可执行权限。
 - 检查环境变量或初始化文件中是否设置了 `RSTACK_HOOKS=0`。
-- 如果命令提示存在其他 hooks 配置，请先迁移或移除冲突配置，再重新运行该命令。
+- 如果命令提示存在其他 hooks 配置，请运行 `rs setup --force`。
 - 如果命令提示其他项目是 hooks owner，请按照 [Monorepo](#monorepo) 中的步骤转移 owner。
 
 hook 脚本不需要可执行权限，因为 Rstack CLI 会使用 `sh` 运行它。

website/docs/zh/guide/git-hooks.mdx

@@ -36,14 +36,14 @@ import { PackageManagerTabs } from '@rspress/core/theme';
 `rs setup` 会将仓库的 `core.hooksPath` 设为 `.rstack/hooks/_`，可以通过以下命令确认是否安装成功：
 
 ```bash
-git config --local --get core.hooksPath
+git config --get core.hooksPath
 # .rstack/hooks/_
 ```
 
 :::tip
 
 - `_` 目录由命令动态生成，且默认被 Git 忽略。
-- 如果检测到其他 hooks 路径或已有 Git hooks，`rs setup` 会跳过安装。请先迁移需要保留的 hooks，移除原有配置，然后重试。详细说明请参考 [`rs setup` 指南](./cli/setup#hook-files)。
+- 如果检测到其他 hooks 路径或已有 Git hooks，`rs setup` 会跳过安装。可运行 `rs setup --force` 强制安装 Rstack hooks。详细说明请参考 [`rs setup` 指南](./cli/setup)。
 
 :::