scrolls-hide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hiding docs/scrolls/

隐藏docs/scrolls/

Some projects run their scrolls folder visible (

scrolls

, e.g. via

/scrolls-setup --unhide

or a prior

/scrolls-unhide

) and later want it back to the dotfile-hidden default. This skill renames

scrolls

→

.scrolls

and fixes every reference to the old path that it can find with confidence, without guessing at edits to files outside its scope. It's the mirror image of

/scrolls-unhide

— same mechanics, opposite direction.

Everything operates relative to the current working directory unless

-t

--reporoot

says otherwise — not relative to this skill's own location.

部分项目会将scrolls文件夹设置为可见状态（

scrolls

，例如通过

/scrolls-setup --unhide

或之前的

/scrolls-unhide

操作），之后又希望恢复为默认的点文件隐藏状态。本技能会将

scrolls

重命名为

.scrolls

，并修复所有能确定找到的旧路径引用，不会随意修改其范围外的文件。它是

/scrolls-unhide

的镜像操作——机制相同，方向相反。

所有操作均相对于当前工作目录，除非使用

-t

--reporoot

参数指定其他目录——而非相对于本技能自身的位置。

Cross-platform

跨平台支持

The bundled script ships in two forms:

hide.sh

(bash — macOS, Linux, or Windows with Git Bash/WSL) and

hide.ps1

(PowerShell 7+ — Windows, or macOS/Linux with

pwsh

installed). Both accept the exact same flags in the exact same forms (

-p

--path

-t

--reporoot

-l

--local

-r

--recurse

) and produce the same output — only the launcher differs. Pick by what's actually available: try

bash --version

; if that succeeds, use

.sh

; otherwise use

.ps1

via

pwsh

(preferred — install from https://aka.ms/powershell if missing) or, only if

pwsh

genuinely isn't available, the built-in Windows PowerShell

powershell.exe

(untested against that older version;

pwsh

is what this was written and verified against).

附带的脚本提供两种形式：

hide.sh

（bash脚本——适用于macOS、Linux，或安装了Git Bash/WSL的Windows系统）和

hide.ps1

（PowerShell 7+脚本——适用于Windows，或安装了

pwsh

的macOS/Linux系统）。两者接受完全相同的参数格式（

-p

--path

、

-t

--reporoot

、

-l

--local

、

-r

--recurse

），输出结果也一致——仅启动方式不同。根据实际可用环境选择：先尝试

bash --version

；若成功运行，则使用

.sh

脚本；否则使用

pwsh

运行

.ps1

powershell.exe

（未针对该旧版本测试；本脚本基于

pwsh

编写并验证）。

Options

参数选项

Read the invocation text for these, in any order — there's no real argv parser here, so pull them out of the plain text yourself:

-p <path>
/
--path=<path>
/
--path <path>
— a base directory to operate on, instead of the current directory. Repeatable, to target several locations in one run (e.g.
```
-p packages/api -p packages/web
```
in a monorepo).
-t
/
--reporoot
— use the git repository's top level (
```
$(git rev-parse --show-toplevel)
```
) as the base directory, regardless of which subdirectory you actually invoked this from. Fails with a clear message if the current directory isn't inside a git repository.
-l
/
--local
— use the current working directory as the base directory explicitly. This is what happens by default anyway when none of
```
-p
```
/
```
-t
```
/
```
-l
```
are given — the flag exists to say so on purpose.
-r
/
--recurse
— search recursively under the base directory for scrolls folders, instead of checking only its exact
```
docs/scrolls
```
. Matches the usual meaning of
```
-r
```
on tools like
```
grep
```
/
```
cp
```
/
```
rm
```
: off by default, opt in to widen the blast radius. Combine with any of the above (or with none, recursing from cwd).

-p

-t

, and

-l

are three different ways to pick a base directory —

-t

and

-l

each resolve to a single one and can't be combined with

-p

or with each other; pass

-p

(repeatably) for anything more specific.

-r

is independent and stacks with any of them. If no base directory is given, the bundled script defaults to the

DEFAULT_SCROLLS_RELPATH

environment variable if the user has it set, otherwise the current directory — and if that default isn't recursive and differs from the repo's top level (in a git repo), the script prints a note about

-t

-r

as alternatives, since a scrolls folder living elsewhere in the repo would otherwise go unnoticed rather than erroring.

Because a directory literally named

scrolls

(no dot) is a more generic name than

.scrolls

, false positives are more plausible here than in

/scrolls-unhide

— the

STARTER.md

-presence guard described below is what keeps recursion safe regardless.

以下是参数说明，可按任意顺序传入——此处未使用真正的argv解析器，需自行从文本中提取：

-p <path>
/
--path=<path>
/
--path <path>
— 指定操作的基准目录，替代当前目录。可重复使用，以便一次性处理多个位置（例如在单仓库中使用
```
-p packages/api -p packages/web
```
）。
-t
/
--reporoot
— 将Git仓库的顶层目录（
```
$(git rev-parse --show-toplevel)
```
）作为基准目录，无论实际从哪个子目录调用本脚本。若当前目录不在Git仓库内，会输出清晰的错误信息。
-l
/
--local
— 明确将当前工作目录作为基准目录。当未指定
```
-p
```
/
```
-t
```
/
```
-l
```
时，默认就是此行为——该参数用于明确指定此操作。
-r
/
--recurse
— 在基准目录下递归搜索scrolls文件夹，而非仅检查其下的
```
docs/scrolls
```
。与
```
grep
```
/
```
cp
```
/
```
rm
```
等工具中
```
-r
```
的常规含义一致：默认关闭，开启后扩大搜索范围。可与上述任意参数组合使用（或不组合，从当前工作目录开始递归）。

-p

、

-t

和

-l

是三种选择基准目录的方式——

-t

和

-l

各自仅能指定一个目录，且不能与

-p

或彼此组合；如需更具体的目标，可重复使用

-p

参数。

-r

是独立参数，可与上述任意参数组合。若未指定基准目录，附带的脚本会优先使用用户设置的

DEFAULT_SCROLLS_RELPATH

环境变量，否则使用当前目录——若默认设置非递归且与仓库顶层目录不同（在Git仓库中），脚本会输出关于

-t

-r

作为替代方案的提示，否则仓库中其他位置的scrolls文件夹会被忽略而非报错。

由于字面名为

scrolls

（无点前缀）的目录比

.scrolls

更通用，因此相比

/scrolls-unhide

，此处更可能出现误判——下文所述的

STARTER.md

存在性检查机制可确保递归操作的安全性。

Steps

操作步骤

1. Run the bundled script

1. 运行附带的脚本

bash <skill-dir>/scripts/hide.sh [-p BASE ...] [-t] [-l] [-r]
pwsh <skill-dir>/scripts/hide.ps1 [-p BASE ...] [-t] [-l] [-r]

Pass through whatever flags the user gave, in the same forms, to whichever of the two matches the environment (see "Cross-platform" above). Omit them entirely to use the default. The script, for each resolved base directory:

Without
-r
(default): checks exactly one spot — the base directory itself if it already is a scrolls folder (has
```
STARTER.md
```
), otherwise
```
<base>/docs/scrolls
```
. Fast, and matches the location
```
/scrolls-setup
```
/
```
/scrolls-update
```
use by default, so a bare invocation targets the obvious place first.
With
-r
/
--recurse
: searches a bounded number of levels deep under the base directory for directories literally named
```
scrolls
```
containing a
```
STARTER.md
```
— that guard is what makes recursing from a broad base (even the whole repo) safe: coincidentally-named directories without a
```
STARTER.md
```
are ignored, and common heavy/vendor directories (
```
node_modules
```
,
```
.git
```
,
```
vendor
```
,
```
dist
```
,
```
build
```
,
```
.venv
```
,
```
venv
```
,
```
__pycache__
```
,
```
target
```
,
```
.next
```
,
```
.cache
```
) are pruned rather than descended into.

For each match found (either way):

Skips it (reporting why) if a
```
.scrolls
```
folder already sits alongside it; otherwise renames it with
```
git mv
```
when the repo and file are git-tracked (preserving history), falling back to a plain
```
mv
```
otherwise.
Rewrites the reference to the old path inside the moved folder's own files (this catches
```
STARTER.md
```
, which references its own path throughout) and, if present, in the one
```
CLAUDE.md
```
file that's an exact sibling of
```
docs
```
for that folder — never a broader search for
```
CLAUDE.md
```
.
```
/scrolls-setup
```
writes a short, portable reference (
```
docs/scrolls
```
) relative to wherever
```
CLAUDE.md
```
itself lives, so in a multi-location sweep two different scrolls folders can legitimately share that exact same short string; a "helpfully" broader search for matching
```
CLAUDE.md
```
files would risk rewriting an unrelated sibling package's file. (The rewrite also tries the full path as discovered, for scrolls folders set up with a custom
```
--path
```
under the older convention.)
Prints any other files nearby that still mention the old path — these are reported, not edited, and are excluded from inside other scrolls folders (a common source of false positives under the shared short-form convention) but can still include a false-positive sibling
```
CLAUDE.md
```
occasionally — that's expected, see step 2 below. The script deliberately doesn't touch files outside the scrolls folder and its own
```
CLAUDE.md
```
, since rewriting arbitrary prose (READMEs, CI configs, other docs) without reading it first risks corrupting unrelated content.

Exits with an error if a given base directory has no matching folder — without

-r

, that's the signal to check the path, try

-t

if you expected the repo root, or add

-r

if it might be nested deeper; otherwise point the user at

/scrolls-setup

bash <skill-dir>/scripts/hide.sh [-p BASE ...] [-t] [-l] [-r]
pwsh <skill-dir>/scripts/hide.ps1 [-p BASE ...] [-t] [-l] [-r]

根据环境（参见上文“跨平台支持”），将用户提供的所有参数按原样传递给对应的脚本。若不传递参数则使用默认设置。对于每个解析后的基准目录：

未使用
-r
（默认）：仅检查一个位置——若基准目录本身就是scrolls文件夹（包含
```
STARTER.md
```
），则直接处理该目录；否则检查
```
<base>/docs/scrolls
```
。速度快，与
```
/scrolls-setup
```
/
```
/scrolls-update
```
默认使用的位置一致，因此无参数调用会首先处理最明显的位置。
使用
-r
/
--recurse
：在基准目录下有限深度内搜索字面名为
```
scrolls
```
且包含
```
STARTER.md
```
的目录——该检查机制确保从宽泛基准（甚至整个仓库）开始递归是安全的：无
```
STARTER.md
```
的同名目录会被忽略，常见的大型/供应商目录（
```
node_modules
```
、
```
.git
```
、
```
vendor
```
、
```
dist
```
、
```
build
```
、
```
.venv
```
、
```
venv
```
、
```
__pycache__
```
、
```
target
```
、
```
.next
```
、
```
.cache
```
）会被跳过而非深入遍历。

对于找到的每个匹配项（无论哪种方式）：

若旁边已存在
```
.scrolls
```
文件夹，则跳过该目录并说明原因；否则，若目录及文件受Git追踪，则使用
```
git mv
```
重命名（保留历史记录），否则使用普通
```
mv
```
命令。
修改已移动文件夹自身文件中的旧路径引用（这会处理
```
STARTER.md
```
，因为该文件中多处引用自身路径），若存在与该文件夹的
```
docs
```
同级的
```
CLAUDE.md
```
文件，也会修改其中的引用——绝不会全局搜索
```
CLAUDE.md
```
文件。
```
/scrolls-setup
```
会写入一个简短的可移植引用（
```
docs/scrolls
```
），该引用相对于
```
CLAUDE.md
```
自身所在位置，因此在多位置扫描时，两个不同的scrolls文件夹可能合法地共享完全相同的短字符串；若“贴心地”全局搜索匹配的
```
CLAUDE.md
```
文件，可能会修改无关的兄弟包文件。（重写操作也会尝试使用发现的完整路径，以适配旧约定下通过自定义
```
--path
```
设置的scrolls文件夹。）
打印附近仍提及旧路径的其他文件——这些文件仅会被报告，不会被编辑，且会排除其他scrolls文件夹内部的文件（在共享短格式约定下，这是常见的误判来源），但偶尔仍可能包含误判的兄弟
```
CLAUDE.md
```
文件——这是预期情况，参见下文步骤2。脚本故意不修改scrolls文件夹及其自身
```
CLAUDE.md
```
之外的文件，因为未经阅读就重写任意文本（README、CI配置、其他文档）可能会损坏无关内容。

若指定的基准目录下无匹配文件夹，脚本会报错退出——未使用

-r

时，这提示用户检查路径，若预期是仓库根目录则尝试

-t

参数，若文件夹可能嵌套更深则添加

-r

参数；否则引导用户使用

/scrolls-setup

。

2. Handle the leftover references it reports

2. 处理脚本报告的剩余引用

For each file the script lists under "Other references... left for manual review" — read it and update the reference yourself if it's a genuine stale path (a README, a CONTRIBUTING doc, a CI script), using normal editing judgment rather than blind find-and-replace. Skip anything that isn't actually about this project's scrolls folder (e.g. a coincidental string match).

对于脚本在“其他引用...需手动检查”下列出的每个文件——若确实是过时路径（如README、CONTRIBUTING文档、CI脚本），则手动阅读并更新引用，使用常规编辑判断而非盲目的查找替换。跳过与本项目scrolls文件夹无关的内容（例如巧合的字符串匹配）。

3. Report back

3. 反馈结果

List each folder that was hidden (old path → new path), what was auto-fixed for each (its own files,

CLAUDE.md

), any that were skipped and why (target already existed), and what you fixed manually in step 2, if anything.

列出每个被隐藏的文件夹（旧路径→新路径）、每个文件夹自动修复的内容（自身文件、

CLAUDE.md

）、被跳过的文件夹及原因（目标已存在），以及步骤2中手动修复的内容（若有）。

Development

开发说明

tests/

holds this script's Red/Green regression suite (bash + PowerShell), for maintaining

scripts/hide.sh

scripts/hide.ps1

themselves — it plays no part in carrying out a user's

/scrolls-hide

request. Don't read or run it while executing this skill.

tests/

目录包含本脚本的红/绿回归测试套件（bash + PowerShell），用于维护

scripts/hide.sh

scripts/hide.ps1

本身——在响应用户的

/scrolls-hide

请求时，无需读取或运行该测试套件。