zsh guide shell

Zsh 使用指南

这套 Shell 配置采用“Zsh 为壳，Bun 为核”的结构：Zsh 负责 cd、export 和 TTY 交互，Bun/TypeScript 负责 fzf 面板、列表生成与复杂数据处理

配置入口

~/.zshrc 只负责加载 ~/.zsh/zshrc，后者按以下顺序初始化：

1. env.zsh
2. 可选的 secret.zsh
3. 非交互 Shell 到此返回
4. tmux 交互入口
5. options.zsh
6. plugins.zsh
7. completions.zsh
8. tools.zsh
9. aliases.zsh
10. functions/index.zsh
11. keybindings.zsh
12. notify.zsh

只有环境变量和私密配置会进入非交互 Shell，插件、快捷键、提示符等只在交互式 Shell 中加载

启动与日常行为

• 多终端共享 ~/.zsh_history，命令立即写入并自动去重
• 补全不区分大小写，并支持 _、.、- 边界匹配
• 上下方向键按当前输入前缀搜索历史，Ctrl-l 清屏
• starship、zoxide、mise、fzf 与 Homebrew 初始化结果会被缓存
• 修改工具配置后可执行 zsh-cache-flush，重新打开 Shell 时自动重建缓存
• 检测到 tmux 时可按 a 附加现有 session、按 n 新建，按 Enter 或其他键跳过
• VS Code、JetBrains 内嵌终端和已有 tmux 会话不会触发 tmux 入口

常用别名

命令	功能
.. / ... / ....	返回一至三级父目录
mkdir	等价于 mkdir -p
v	打开 Neovim
cc / oc / cx	启动 Claude Code、OpenCode、Codex
ls	使用 lsd 显示隐藏文件、图标并让目录优先
ll	lsd 详细列表与总大小
llg	额外计算 Git 状态，大仓库可能较慢
dps	格式化显示全部 Docker 容器
dis	显示 Docker 镜像

v、lsd、Docker、btop、safe-rm 等别名会按对应命令是否存在而决定是否注册

常用函数

文件与目录

命令	功能
mkcd <dir>	创建目录并进入
lt [depth] [path...]	树形显示目录，默认深度为 2
rmr <root> <pattern...>	按模式递归删除
rme <keep...>	删除当前目录中除指定名称外的内容
open [path]	在系统文件管理器中打开路径
y	打开 Yazi，退出后跟随其最终目录

Git 与项目开发

命令	功能
grepo	用 fzf 选择仓库并进入目录
gdiff	交互查看、暂存或丢弃变更
glog	交互浏览提交历史
d	运行项目开发命令
b	构建项目
i	安装项目依赖或指定包
t	运行测试

开发命令会读取真实项目文件识别 Node、Go、Rust、Python、Maven 和 Flutter。Node 项目根据 lock 文件选择 pnpm、Bun、Yarn 或 npm

搜索、进程与系统

命令	功能
ff [dir]	搜索文件和目录
fs [dir]	搜索文件内容
fx	文件与内容的组合搜索面板
fp	fzf 进程管理
killByName / killByPort	按名称或端口结束进程
ports [port] [--all]	查看监听端口，并可多选结束进程
cb	管道/参数复制到剪贴板，无参数时读取剪贴板
sysinfo	显示系统、CPU、内存、磁盘和 uptime
ins / uns / update / pkgs	跨平台包管理

fzf 通用按键

以下是默认键位，命令键和选项键前缀可以通过环境变量调整：

快捷键	功能
Ctrl-n / Ctrl-p	向下或向上移动
Ctrl-e / Ctrl-y	预览向下或向上滚动 5 行
Tab	切换选中并下移
Ctrl-o	使用 VS Code 打开
Alt-o	使用 Neovim 打开
Alt-c	复制绝对路径
Alt-f / Alt-d / Alt-a	在 ff 中只看文件、只看目录或显示全部

SSH 文件传输

cscp

cscp [本地基准目录]

不传参数时使用当前目录。Host 列表读取 ~/.ssh/config 中不含 * 的明确 Host 条目

上传流程：

1. 选择 Upload
2. 多选本地文件或目录
3. 选择 SSH Host
4. 输入远端目标目录
5. 只有普通文件时使用 scp
6. 只要包含目录，就把全部选择合成一个 tar 流，通过 SSH 传输并在远端解包

下载文件使用 scp；下载目录由远端创建 tar 流并在本地解包，同时保留远端目录名。tar 只负责打包，没有启用 gzip 或 zstd 压缩

路径输入中的 ~ 和 ~/foo 指向远端用户 HOME。目录传输要求两端都能执行 tar，本地还需要 ssh 客户端

常见问题：

• Host 为空：确认 ~/.ssh/config 包含 Host <alias> 形式的非通配符条目
• 远端路径不存在：先执行 ssh <Host>，确认当前用户和 HOME
• 目录传输失败：分别检查两端的 tar，以及 SSH 是否可用
• macOS 扩展属性警告：当前本地 tar 已禁用 xattr，不应再发送 LIBARCHIVE.xattr 元数据
• 取消 fzf 或路径输入会直接结束，不属于传输错误

配置位置

内容	路径
主入口	~/.zsh/zshrc
别名	~/.zsh/aliases.zsh
快捷键	~/.zsh/keybindings.zsh
Zsh 函数	~/.zsh/functions/*.zsh
Bun 核心	~/.zsh/functions/bun/src/*.ts
fzf 回调	~/.zsh/functions/_preview/、_actions/