文件命令
每个别名文件都自带一组保留命令,用来创建、修改和查看这个文件本身:
.. 是保留分隔符。以 @ / @@ 开头且含 .. 的形式不会再被当作别名,所以 byk @@ops..set 永远走文件命令,不会去找一个叫 @@ops..set 的别名。
寻址
- 文件名不能包含
.、@、/或空格;支持字母、数字、-、_与中文。 ..取第一个出现的位置;后面的命令名只允许字母、数字、-、_。- 改写类命令只写被寻址的这个文件;
clone、link、init --link的来源只读。 ..set与..remove拒绝改写链接文件(单元素数组);要改内容请直接编辑链接目标。..clear清空的是链接文件自身。- 需要文件存在的命令在目标缺失时,如果另一侧(当前目录 / 全局目录)有同名文件,会提示换用
@或@@;..path不要求文件存在。 - 修改类命令的提示写 stderr;
json、path、help的数据写 stdout,方便管道和$(...)。
命令一览
创建与删除
..init
- 内容固定为
{}加一个结尾换行;不会覆盖已存在的文件。 --link <source>创建链接文件(单元素数组),保存来源文件的规范化绝对路径。- 来源可以是
@name(当前目录)、@@name(全局目录)或路径(~展开,相对路径按当前目录解析)。来源必须是已存在的对象别名文件;指向链接文件时会被拒绝,链接只支持一层。 - 本地裸名先读字面文件,缺失时再补
.byk.json;.、..、结尾/与目录名读取目录里的.byk.json——与..clone的本地规则相同。 - 创建全局文件时,
~/.byk/alias/不存在会自动创建。
..destroy
- 删除被寻址的文件。交互确认要求输入文件名;非 TTY 环境必须带
--yes。 - 符号链接只删除链接本身,不碰目标;目录会被拒绝。
- 全局文件会连带删除它的依赖目录
~/.byk/deps/@@<文件名>。
..clear
- 把文件重置为
{}。已经为空时只提示Already empty,不写盘。 - 链接文件清空的是链接文件自身,目标内容不动。
- 拒绝清空符号链接,需要删除链接时用
..destroy。 - 与
..destroy一样,非 TTY 环境需要--yes。
编辑别名
..set
第一个不以 - 开头的参数是别名 key;带点号表示分组路径,不存在的中间分组会自动创建。
别名级选项:
文件根选项(不写 key):
- 给字符串别名加元数据时,会转成
{ "$cmd": ... }对象形式;删掉多余的元数据后会自动折叠回字符串。 --private可继承;--no-private在子级写入false,用来重新暴露 private 分组里的别名。详见 可见性。- key 不能以
$开头;元数据字段请用上面的选项,不要直接写进 key。
..remove
- 按点号路径删除别名或整个子树。
- 删除后只剩
$元数据的空分组会一并剪掉。 - key 不存在会报错,不会静默成功。
- 删除单个元数据字段用
..set <key> --unset <fields>。
查看
..json
- 默认只校验 JSON,输出精确的原始字节:不重排、不补换行。
--no-check连校验都跳过,非法 JSON 也原样输出。--expand展开内置变量和文件$var,删除$var后缩进输出;变量问题写 stderr。--expand与--no-check不能同时使用。- 链接文件输出数组本身,不跟随目标。
..path
输出绝对路径,不要求文件存在,也不接受参数。
..rename
- 在同一个作用域内改名(
@只改当前目录,@@只改全局目录)。 - 新名字遵循同样的文件名规则;目标已存在时拒绝。
- 链接文件改的是链接文件本身,目标不动。
- 全局文件的依赖目录
~/.byk/deps/@@<旧名>会同步改名为@@<新名>,别名里的${deps_dir}指向不变。
..help
未知命令会列出全部可用命令。
克隆与链接
..clone <source>
来源可以是:
仓库简写的格式:
@<ref>可省略,默认HEAD。<path>可省略:省略就是仓库根的.byk.json,所以user/repo与user/repo/等价。<path>指向目录时以/结尾,表示读取该目录的.byk.json。- 最后一段是文件名;
.byk.json后缀可写可不写。 - 「省略
<path>」这一层糖只对整条路径生效:user/repo/ss仍然读ss.byk.json,不会被猜成ss/目录。 - 别带主机名。
-gh github.com/user/repo会被当成user=github.com去下载,所以直接报错并提示写成user/repo。
本地路径的解析顺序:
-
裸名字字面优先:
./tool先读tool,不存在再回退tool.byk.json。这样tool与tool.byk.json同时存在时两个都可达——显式写./tool.byk.json永远能命中后者。 -
只有能构成合法别名文件名的裸名字才补后缀:
hello.txt、my tool这类保持字面,不会去找hello.txt.byk.json——它本来就不是合法的别名文件名。 -
裸名字最后落到一个目录时读该目录的
.byk.json,所以./tools、./tools/、.都能指向匿名文件。 -
..link与..init --link的来源解析与这里完全一致。 -
都找不到时错误会列出尝试过的候选:
Source not found: …与Also tried: …。 -
目标文件必须不存在,
..clone不会覆盖。 -
本地来源会先校验:必须是 JSON 对象;链接文件(数组)会被拒绝。
-
内容是独立副本,与来源不再有关系。想要实时引用请用
..link。 -
标了
$clone: false的别名和分组不会进入副本;分组里写$clone: true的子级仍会保留,标记本身不会出现在结果里。如果剔除后什么都不剩,clone 会在落盘前失败。含标记或发生过剔除的副本会重新序列化(键按字典序)。$private不影响 clone。 -
来源顺手把
$deps.base冻结成绝对地址并打印一行Recorded $deps.base = …。形态跟着来源走:远程写成绝对 http(s) 目录 URL,本地写成本机绝对目录路径。补的规则一致——没写就按源文件所在目录补上,写了相对形态(.、../、sub/dir)就相对源文件解析,写了绝对地址则原样保留,只补结尾的/。 -
$deps.base是程序写入的尽力锚点,不构成可移植性担保:克隆链路(a ← b ← c)每跳都会重新冻结,最初的来源语义可能丢失。不建议手写 base。 -
两条路互不越界:远程来源遇到本地路径形态的
base(/x、C:/x)直接失败,于是从网上拿到的别名文件读不了本机文件;本地来源遇到绝对 URL 则照搬,那份文档的资产仍然从网上取。 -
clone 时
base里出现变量会直接失败:那一刻没有变量表,${CDN}求不出值,猜一个写死只会把意图烧成假地址。补写会让整份文档重新序列化(键按字典序);既没有$deps也没有$clone的文件仍是字节级副本。 -
远程来源依赖
curl;缺少时会提示先安装。服务器返回 404 时报Remote source not found: <url>并提示检查仓库、ref 与路径——目录路径忘了以/结尾也归到这里。 -
选项可以写在来源前后,
-gh user/repo@v1/tool -d与-d -gh ...等价。
Tap 索引(--tap)
一个仓库可以发布多个别名文件,而不必都堆在根目录:--tap 读取仓库根目录的 byk.tap.json 作为路由表。
索引是一个扁平 JSON 对象;$ 开头的键保留给元数据,永远不参与匹配:
- Tap 来源形态:
<user>/<repo>[@<ref>]/<key>。<ref>默认HEAD;<key>只能是单个路径段,不能含/、不能是./..、不能以$开头。 --tap只支持 GitHub,本身就是一个来源形态:不能与-gh、-ge、-jd同时使用。- 完整写法本地索引优先。 spec 不带
@<ref>时,先读~/.byk/tap/<user>/<repo>/byk.tap.json。这个文件存在就是权威:解析失败、缺键、value 非 string、目标不存在都会直接报错;只有索引文件本身不存在才回退 GitHub。写了@<ref>则始终使用远程索引。 - 单 key 简写。 只写
--tap <key>(不含/)时,搜索所有合法的~/.byk/tap/<user>/<repo>/byk.tap.json,只查本地索引、不联网拉取索引。唯一命中就从该索引克隆(value 是 URL 时仍走远程 clone);多个仓库都有这个 key 时,列出user/repo/key完整写法让你自己选;一个都没有则直接失败,不回退远程。 - 简写只读两层:
tap/<user>/<repo>/byk.tap.json。目录名必须是合法的 GitHub 用户名 / 仓库名,非法目录和没有索引的目录跳过。读不了或解析失败的索引会打印警告并跳过,所以「唯一」只对可读索引成立。 - 简写不支持
@ref;要固定 ref 请用完整写法(走远程索引)。 ~/.byk/tap/是只读缓存:byk 不会创建、更新或删除它。需要自己准备,例如git clone https://github.com/user/repo ~/.byk/tap/user/repo。- value 是精确指针:不会补
.byk.json,也不会把目录当成目录里的.byk.json。以@/@@开头的目标同样按字面文件名处理,绝不解释成别名引用。- 本地索引:相对值以索引文件所在目录为基准;绝对路径与
~按本地文件处理;http(s)URL 仍走远程 clone。 - 远程索引:相对值以仓库根为基准;只允许
http(s)URL 和仓库内相对路径,不能指向本地。
- 本地索引:相对值以索引文件所在目录为基准;绝对路径与
- 只路由一层。目标必须是别名文件,不能再是 tap 索引:最后一段是
byk.tap.json的目标会被直接拒绝,解析出来的文件也不会被当成第二条路由。 $deps.base锚在目标的位置上,而不是索引上。目标是本地文件时冻结成缓存里的本机绝对目录;目标是 URL 时保持 http(s) 目录 URL。- 索引缺失时报
Tap index not found: …并提示在仓库根目录补byk.tap.json;键缺失时列出可用键。 - byk 会在路由前打印这次用的是哪份索引:
Tap index: local <路径>或Tap index: remote <URL>,随后是Tap <key> -> <目标>。
克隆并安装依赖(-d)
- 克隆落盘后立刻读新文件的
$deps:有就按..deps i的同步语义装好(新建的 key 没有清单,等于首次安装);没有就跳过,不当成错误。 -d对局部文件同样有效:依赖落在当前目录的.byk/deps/@<文件名>/里,和..deps i一致。- 安装不二次确认,也不需要
--yes:从 clone 到资产就位是一条命令的事,适合脚本与非交互环境。 - 装依赖失败不回滚克隆:文件已经落盘且合法,按提示重跑
@@<file>..deps i即可,已就位的资产不会重复下载。
..link <target>
- 把被寻址的文件改写为单元素数组,指向目标文件的规范化绝对路径。
- 只能作用于空对象
{}或已经是链接的文件;有内容的普通别名文件会被拒绝。 - 目标必须是本地的对象别名文件;URL 会被拒绝并提示改用
..clone。本地名称遵循与..clone相同的规则:先读字面文件,再补.byk.json,目录名则读取目录里的.byk.json。 - 拒绝指向自己,也拒绝改写符号链接。
- 被寻址文件不存在时,会提示用
..init --link创建。 - 全局文件改指向时,如果它的依赖目录已存在,会提醒先
..deps uninstall,避免继续用旧目标的资产。 - 链接后的行为、路径基准与身份归属见 单链接。
..deps [install|uninstall|status]
子命令取 install / uninstall / status,也接受无歧义前缀;不带子命令等于 status。
install 是同步,不是追加。 $deps.files 是期望状态,安装让目录收敛到它:
文件条目都没变、也没有声明包时是空操作,不产生任何请求:
src写相对路径时靠$deps.base拼成绝对地址;两者缺一就报错,不会去猜。base 落盘后必须是绝对地址——URL 形态对应下载,本机路径形态对应复制(..clone按来源决定写哪种)。相对写法只在..clone时才有意义。base 由程序写入,是尽力锚点而非可移植性担保,不建议手写。- 本地条目按源文件 mtime 判新旧:源比装好的那份新就重装;源不在了就报
cannot read并给出路径,不安静跳过。 - 全局与局部都支持:全局落到
~/.byk/deps/@@<文件名>/,局部落到<文件所在目录>/.byk/deps/@<文件名>/并自带.gitignore(内容*)。 - 已安装清单存在
<专属目录>/.byk-deps.json,记录上次声明的快照与落点。删除它等于重新开始记账,安装会重新「接管」现有文件。 - 只删自己装过的路径:目录里多出来的文件永远不动,只提示一句。
- 安装不二次确认,也不需要
--yes;--force是唯一的选项,用于「文件资产被外部改坏」这类清单看不出的情况。 - 绝对地址交给系统
curl,本地路径直接fs::copy(同样先落临时文件再 rename);解压两条路都交给系统tar,缺失时报错并提示安装。汇总行两种来源都写Downloaded,其中来自本地复制的条数在括号里交代(Downloaded 3 files into … (1 local)),一条本地都没有时不出现括号——$deps.files只负责取文件;$deps.pip与$deps.npm交给 pip / npm 自己处理,不记账在文件清单里。 $deps.pip把 Python 包装进专属目录里的.venv:venv 缺失时用python3(Windows 为python)创建,然后执行pip install。venv 的bin/Scripts会前置到PATH;缺少 Python 时报错并提示安装。$deps.npm把 npm 包装进专属目录:缺失时写一个最小package.json(byk-deps、private),然后执行npm install。node_modules/.bin会前置到PATH;缺少 npm 时报错并提示安装。- 包每次安装都会执行,且不记进
.byk-deps.json——是否最新由 pip / npm 判断。--force只影响文件条目;从声明里删掉某个包不会卸载它,想清空整个目录用..deps uninstall。files可以省略,所以声明里可以只有包。 - 落点都圈在专属目录内(全局
~/.byk/deps/@@<文件名>/,局部<文件所在目录>/.byk/deps/@<文件名>/)。字段说明见 依赖。 - 带
extract的条目落点是目录,用(extract)标注;重装时整目录替换,旧归档里没有的文件不会留下。省略to表示解到专属目录根,这种条目必须单独存在(它会换掉整个目录):
- 中途失败不回滚已完成的条目,错误里列出这次已经落盘的路径;清单也会写成实际状态,重跑接着做。
- uninstall 删除整个依赖目录;目录不存在时报错。status 只读,文本写 stdout,适合管道:
unknown 表示 pip 的 URL / VCS 直接引用:本地拿不到包名,byk 如实标注而不去猜。这类条目既不算到位,也不算缺失。
--check 只校验声明本身:能不能解析、落点是否冲突、相对 src 有没有 base、包条目是否非空字符串,不碰装没装。缺哪条、旧没旧是运行时状态,用 ..deps status 看,或者在执行前跑一次 ..deps i。
补全
文件命令的补全覆盖:
@/@@后的文件名,输入..后补命令名;- 命令后的选项(如
..set --); ..help后面的命令名;..remove后面的已有 key 路径(读目标文件,链接文件不补);..clone、..link、..init --link的来源参数(以@开头的别名文件);..deps后面的子命令(install/uninstall/status)。