scrolls-unhide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Unhiding docs/.scrolls/

取消 docs/.scrolls/ 的隐藏状态

/scrolls-setup

defaults to a dotfile-hidden

.scrolls

folder. Some projects would rather have it visible in a normal directory listing — this skill renames

.scrolls

→

scrolls

on an existing setup 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-hide

Everything operates relative to the current working directory unless

-t

--reporoot

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

/scrolls-setup

默认会创建一个点文件隐藏的

.scrolls

文件夹。部分项目希望该文件夹在常规目录列表中可见——本工具会在已有的配置中将

.scrolls

重命名为

scrolls

，并修复所有可确定的旧路径引用，不会对其范围外的文件进行猜测性编辑。它是

/scrolls-hide

的镜像操作。

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

-t

--reporoot

指定其他路径——而非相对于本工具自身的位置。

Cross-platform

跨平台支持

The bundled script ships in two forms:

unhide.sh

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

unhide.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).

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

unhide.sh

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

unhide.ps1

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

pwsh

的 macOS/Linux）。两者接受完全相同的选项和格式（

-p

--path

-t

--reporoot

-l

--local

-r

--recurse

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

bash --version

；如果成功，使用

.sh

脚本；否则通过

pwsh

使用

.ps1

脚本（推荐——若未安装可从 https://aka.ms/powershell 获取），只有当

pwsh

确实不可用时，才使用 Windows 内置的旧版 PowerShell

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.

以下选项可按任意顺序传入——此处没有真正的参数解析器，需从文本中自行识别：

-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 文件夹会被忽略而非报错。

Steps

操作步骤

1. Run the bundled script

1. 运行附带脚本

bash <skill-dir>/scripts/unhide.sh [-p BASE ...] [-t] [-l] [-r]
pwsh <skill-dir>/scripts/unhide.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/unhide.sh [-p BASE ...] [-t] [-l] [-r]
pwsh <skill-dir>/scripts/unhide.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 unhidden (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/unhide.sh

scripts/unhide.ps1

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

/scrolls-unhide

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

tests/

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

scripts/unhide.sh

scripts/unhide.ps1

本身——在响应用户的

/scrolls-unhide

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