cnb-rs alias set

cnb-rs alias set <NAME> <EXPANSION> [--shell] [--clobber]

创建用户自定义命令别名。对齐 gh alias set。

NAME 是触发别名的单词（不能与内置子命令同名）；EXPANSION 是触发后实际执行的命令片段。

参数

• <NAME>: alias 名称（位置参数，必填）。校验规则：
  • 不能为空
  • 不能含空白字符
  • 不能与内置子命令冲突（如 auth / repo / issue / pr / build 等 29 个）
• <EXPANSION>: 展开后执行的命令字符串。传 - 从 stdin 读

选项

• --shell: expansion 以 shell 模式执行（走 sh -c，Windows cmd /C），等同 expansion 以 ! 开头
• --clobber: 已存在的同名 alias 覆盖（默认拒绝，避免误覆盖）

三种 EXPANSION 形态

1. 简单展开

$ cnb-rs alias set co 'pr checkout'
$ cnb-rs co 123       # = cnb-rs pr checkout 123

extras（123）自动 append 到 expansion 末尾。

2. 含位置 placeholder（$1 ~ $9）

$ cnb-rs alias set bug 'issue list --labels="$1"'
$ cnb-rs bug urgent   # = cnb-rs issue list --labels="urgent"

含 placeholder 时 extras 不再 append（placeholder 已经消化）。未填的 placeholder 替换为空字符串。

3. Shell 模式（! 前缀 或 --shell）

# 自动加 ! 前缀
$ cnb-rs alias set --shell ll 'ls -la'
$ cnb-rs ll /tmp     # 走 sh -c 'ls -la /tmp'

# 手动 ! 前缀
$ cnb-rs alias set ll '!ls -la'

# 组合管道
$ cnb-rs alias set --shell igrep 'cnb-rs issue list --labels="$1" | grep "$2"'
$ cnb-rs igrep bug critical

Shell 模式走 sh -c（Windows 走 cmd /C），支持管道 |、重定向 >、命令替换等所有 shell 语法。

从 stdin 读 EXPANSION

# 避免 PowerShell / bash 复杂 quoting
$ cnb-rs alias set co -
pr checkout
^D
✓ alias 已设置：co = "pr checkout"

错误场景

# NAME 与内置冲突
$ cnb-rs alias set repo 'pr view'
错误: alias name `repo` 与内置子命令冲突；请换一个名字（内置子命令优先级高，同名 alias 永远不会被触发）

# 已存在
$ cnb-rs alias set co 'pr view'
错误: alias `co` 已存在（当前 expansion: "pr checkout"）；加 --clobber 覆盖

# --clobber 覆盖
$ cnb-rs alias set co 'pr view' --clobber
✓ alias 已设置：co = "pr view"

# NAME 含空白
$ cnb-rs alias set 'issue mine' '...'
错误: alias name 不能含空白字符（如需多词请用引号包住整个 alias，或换用单词名）

# EXPANSION 为空
$ cnb-rs alias set co ''
错误: expansion 不能为空

为什么 cnb-rs 不支持多词 NAME（gh 支持）

gh 端允许 gh alias set 'issue mine' '...' 让 gh issue mine 触发。cnb-rs 端这种用法需要修改 args parsing 在多个 token 上 longest-prefix-match，复杂度高且很少有人用。当前选择牺牲该特性换实现简洁；如需类似效果用单词名（如 my-issues）。

另请参阅

• cnb-rs alias
• cnb-rs alias list
• cnb-rs alias delete
• cnb-rs alias import