# dotfiles **Repository Path**: sineatos/dotfiles ## Basic Information - **Project Name**: dotfiles - **Description**: my dotfile managed with chezmoi - **Primary Language**: Shell - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-31 - **Last Updated**: 2026-11-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # dotfiles Chezmoi 源目录,用于管理个人 dotfiles。仓库同时作为 git repo 版本管理。 ## 快速开始 ```bash # 新机器安装 chezmoi curl -fsSL https://chezmoi.io/get | sh -s -- --bin /usr/local/bin # 初始化并拉取配置 chezmoi init https://gitee.com/sineatos/dotfiles.git # 注意:chezmoi 不会执行 .chezmoi/init.sh(它没有 init script 这个机制)。 # 下面的 apply 之后,run_ 钩子会接管:桥接块、环境默认值、mise bootstrap # 都会自动就位。 # 渲染所有配置到 ~ chezmoi apply # 安装工具(清单在 ~/.config/mise/config.toml) mise install # 可选:创建每机覆盖文件 dotfiles mise init # 检查改动 chezmoi diff ``` 新机器上手也可以手动跑一次 onboarding 脚本(chezmoi 不会自动跑它): `sh ~/.local/share/chezmoi/.chezmoi/init.sh` —— 它会检测 OS、创建 `.chezmoidata/private_data.toml`、按仓库 pin 刷新 mise bootstrap,并装上 bash 桥接块。 工具能否被调用取决于 shell 里有没有激活 mise:`~/.config/bash/bashrc` 会自动 `mise activate bash`,所以 bash 不用额外配置;zsh / fish 需要自己加一行 (见 `chezmoi init` 的输出,或 `mise activate zsh` / `mise activate fish`)。 用 `mise doctor` 可以确认:`activated: yes` 且 `shims_on_path: yes` 才算就绪。 ## 目录结构 ``` dotfiles/ ├── .chezmoi/ │ └── init.sh # 手动 onboarding(chezmoi 不会自动执行它) ├── .chezmoidata/ │ ├── data.toml # 全局变量(editor, shell, displayName 等) │ ├── env.toml # 环境变量(Vault 加密通道,值为空时不输出) │ └── private_data.toml.example # 机器专属数据模板(gitignored) ├── run_dotfiles-*.sh / .cmd # apply 之后运行的钩子(桥接块 / 环境默认值 / mise bootstrap) ├── dot_local/bin/dotfiles # → ~/.local/bin/dotfiles(bash CLI 工具) ├── dot_local/bin/dotfiles.cmd # → ~/.local/bin/dotfiles.cmd(Windows 启动器) ├── dot_config/dotfiles/env.conf.tmpl # → ~/.config/dotfiles/env.conf(Track A 模板) ├── dot_config/ │ ├── bash/bashrc # → ~/.config/bash/bashrc(主 bash 配置) │ ├── bash/bashrc.d/ │ │ ├── 10-aliases.sh # 别名(ls, git 等) │ │ ├── 20-functions.sh # 函数(mkcd, ff, port, killport, extract) │ │ └── 30-starship.sh # starship prompt 初始化 │ ├── starship/starship.toml.tmpl # → ~/.config/starship/starship.toml │ ├── nvim/ # → ~/.config/nvim/(LazyVim + inori) │ ├── wezterm/ # → ~/.config/wezterm/(cockpit 主题) │ ├── zellij/ # → ~/.config/zellij/ │ └── tmux/ # → ~/.config/tmux/ │ └── dotfiles/ │ ├── env.conf.tmpl # → ~/.config/dotfiles/env.conf(Track A 渲染产物) │ ├── env.example # → ~/.config/dotfiles/env.example(~/.env 模板) │ ├── env-defaults.toml # → ~/.config/dotfiles/env-defaults.toml(仓库默认值) │ ├── mise-bootstrap.sh # → ~/.config/dotfiles/mise-bootstrap.sh(mise bootstrap 刷新) │ └── local-files # → ~/.config/dotfiles/local-files(每机文件清单) └── openspec/ # OpenSpec 变更管理 ``` ## 路径映射规则 `chezmoi apply` 时文件名本身编码了目标路径: | 源文件模式 | 渲染到 | |---|---| | `dot_` | `~/.` | | `dot_.tmpl` | `~/.`(先渲染模板) | | `dot_config//...` | `~/.config//...` | | `dot_config/dotfiles/env.conf.tmpl` | `~/.config/dotfiles/env.conf`(渲染模板) | > ⚠️ **源文件里不能出现字面量 `.` 开头的名字。** chezmoi 会**静默跳过**所有以 `.` > 开头的源文件(只认 `dot_` 前缀),既不部署也不报错。所以 `.gitignore` 里 > 想放的东西也不能用字面点开头,必须写成 `dot_foo`。 > > ⚠️ **名字里的点不是目录分隔符。** 只有**首个**组件的 `dot_` 前缀会被展开成 `.`; > 中间的点保持字面量。`dot_config.a.b.c` 会生成文件 `~/.config.a.b.c`,**不是** > 目录 `~/.config/a/b/c`。嵌套目录必须写成真正的目录:`dot_config/dotfiles/env.conf.tmpl` > → `~/.config/dotfiles/env.conf`。 > > 加新文件后验证一下实际落点: > `chezmoi managed --source=. --destination=/tmp/x | grep <名字>` ## Shell 加载顺序 bash 启动时文件加载链: ``` ~/.bashrc ← 系统/用户所有;chezmoi 不写 │ 末尾桥接块由 dotfiles 工具维护 └─ [桥接块: # >>> dotfiles-bridge >>>] ← 来自 ~/.local/bin/dotfiles └─ source ~/.config/bash/bashrc ← 从 dot_config/bash/bashrc 渲染 │ ├─ source ~/.config/dotfiles/env.conf ← 从 env.conf.tmpl 渲染(Vault 通道) │ └─ .chezmoidata/env.toml 中非空的 key 生成 export 语句 │ ├─ source ~/.env ← 手动通道(不在 git 中) │ └─ source ~/.config/bash/bashrc.d/*.sh ← 按数字前缀排序加载 ├── 10-aliases.sh ├── 20-functions.sh └── 30-starship.sh ``` **桥接块由 `~/.local/bin/dotfiles` 维护**,不在 chezmoi source 中。chezmoi 自己不写 `~/.bashrc`: 它只在 apply 之后调一次工具,由工具去写带 marker 的那一段。手动跑 onboarding 脚本 (`sh ~/.local/share/chezmoi/.chezmoi/init.sh`)时它也会被装上; 之后的每次 `chezmoi apply`(含 `chezmoi update`)由仓库根的 `run_dotfiles-bash-bridge.sh` 钩子再调一次, 所以老机器更新仓库后也会自动补上桥接块(Windows 上是同名的 `.cmd` 钩子)。 ### 登录 shell:桥接块也在登录文件里 `~/.bashrc` **只被交互式、非登录 shell 读取**。登录 shell 读的是 `~/.bash_profile` → `~/.bash_login` → `~/.profile` 里的**第一个存在的文件**,而且**完全不读 `~/.bashrc`**。在 Windows 上从 PowerShell / cmd 里执行 `wsl`, WSL 起的就是登录 shell —— 所以只往 `~/.bashrc` 写桥接块是不够的,那条路径下 dotfiles 不会加载。 因此 `dotfiles bash install` 在**两个地方**维护同一段桥接块: | 位置 | 覆盖的 shell | |---|---| | `~/.bashrc` | 交互式、非登录(普通终端里直接跑 bash) | | 登录文件(`~/.bash_profile` / `~/.bash_login` / `~/.profile`,取第一个存在的) | 登录 shell(`wsl`、ssh 登录) | 工具挑选登录文件的方式和 bash 挑选的方式一致;三个文件都不存在时才会创建 `~/.profile` (它是兜底项,创建它不会遮蔽任何已有文件)。查看状态: ```sh dotfiles bash status # bashrc: attached (/home/you/.bashrc) # login: attached (/home/you/.profile) ``` > **桥接块是每次 apply 都会补齐的**:钩子调的是幂等的 `dotfiles bash install`, > 已经有的桥接块原样不动,缺的(尤其是登录文件里那段)会被补上。 > 钩子只在真正部署到 `$HOME` 时动手,`make test/*` 那种 apply 到临时目录的场景不会碰你的 `~/.bashrc`。 `dot_config/bash/bashrc` 顶部有一个"每 shell 只加载一次"的守卫:登录文件通常还会 source `~/.bashrc`, 两个桥接块就会把配置加载两遍。守卫让第二次访问直接返回。它是普通 shell 变量、不 export, 所以嵌套开的子 shell 仍会正常加载配置。 > 工作目录与此无关:bash 的启动文件不依赖当前目录。`wsl` 从 cmd 里启动时落在 `/mnt/c/...`, > `wsl ~` 落在 `~`,这只影响提示符,不影响加载哪些文件。 ## 常用别名 `~/.config/bash/bashrc.d/15-tool-aliases.sh` 定义工具别名。每个别名都先检查工具在不在 PATH 上, 不在就不定义,避免 `alias` 输出里堆一堆无效条目。 | 别名 | 展开为 | |---|---| | `m` / `mr` / `mt` | `mise` / `mise run` / `mise task` | | `oc` | `opencode` | | `h` / `hr` / `hl` / `ha` / `hm` | `herdr` 及其子命令(session / machine 视图) | | `zj` / `zjl` | `zellij` / `zellij --list-sessions` | ## 环境变量双通道 | 通道 | 文件 | 管理方式 | 优先级 | |---|---|---|---| | Vault(加密) | `.chezmoidata/env.toml` → `~/.config/dotfiles/env.conf` | 随仓库版本管理(可 age 加密) | 先加载 | | 手动 | `~/.env` | 不入库,本地手动填写;`dotfiles env init\|edit\|append\|defaults\|show\|path\|status` | 后加载(覆盖 Vault) | | 加密(每机器) | `~/.config/dotfiles/secrets[.age]` | `dotfiles secret` 管理,chezmoi vault (age) 或 base64 退化 | bashrc.d/05-secrets.sh 静默加载 | | 仓库默认(自动同步) | `dot_config/dotfiles/env-defaults.toml` → `~/.config/dotfiles/env-defaults.toml`,自动追加到 `~/.env` | 仓库根的 `run_dotfiles-env-defaults.sh`(Windows 用 `run_dotfiles-env-defaults.cmd`)在每次 `chezmoi apply`(含 `chezmoi update`)后触发;永不覆盖现有值 | 手动追加到 `~/.env` 末尾 | `env.toml` 中值为空(`""`)的 key 不会生成 export 语句。 加密轨道(每机器、独立): ```bash dotfiles secret init # 初始化(默认 chezmoi vault,可选 --fallback base64) dotfiles secret install # 生成 ~/.config/dotfiles/loader.sh dotfiles secret edit # $EDITOR 打开加密文件 dotfiles secret source # 输出可 eval 的 export(bashrc 自动调用) ``` `bashrc` 本身不引用 secret 逻辑;`dot_config/bash/bashrc.d/05-secrets.sh` 静默检查并 source `~/.config/dotfiles/loader.sh`。 ## mise 分层(base / dev / oci / read / task + 每机覆盖) mise 会合并它找到的**所有**配置文件,`mise install` 安装这些文件里工具的**并集**。仓库把清单拆成五类: | 类别 | 文件 | 入库 | 何时生效 | |---|---|---|---| | base | `dot_config/mise/config.toml` → `~/.config/mise/config.toml` | 是 | 总是 | | dev | `dot_config/mise/mise.dev.toml` → `~/.config/mise/mise.dev.toml` | 是 | 选中 `dev` 环境时 | | oci | `dot_config/mise/mise.oci.toml` → `~/.config/mise/mise.oci.toml` | 是 | 选中 `oci` 环境时 | | read | `dot_config/mise/mise.read.toml` → `~/.config/mise/mise.read.toml` | 是 | 选中 `read` 环境时 | | task | `dot_config/mise/mise.task.toml` → `~/.config/mise/mise.task.toml` | 是 | 选中 `task` 环境时 | | 每机覆盖 | `~/.config/mise/config.local.toml` | 否 | 总是,且覆盖上面几类 | | 类别选择 | `~/.config/mise/miserc.local.toml` | 否 | 本机用哪些类别 | | 示例(可发现) | `dot_config/mise/*.example.toml` | 是 | chezmoi | | 仓库内开发工具 | 仓库根 `.mise.toml` | 是 | git,只在仓库目录内生效 | 类别是**叠加**的,不是互斥:`MISE_ENV=dev` 装的是 base + dev。 base 清单里是 dotfiles 自己(chezmoi、mise)、运行时底座(node、python、pipx、uv、starship) 和日常终端工具(helix、**neovim**、herdr、opencode、glow、yazi)。dev 里是仓库工具和编译器 (gitleaks、go、zig),oci 里是镜像仓库工具(oras、grpcurl),read 里是终端阅读器 (nom、eilmeldung),task 里是人机共用的任务看板(tsk)。 **后端要写死**:mise 用裸工具名时会走 registry,优先级会随版本变;而且不同后端在装的时候 依赖的东西不一样 —— `vfox:*` 要从 github.com clone 一个插件,插件再拿 `api.github.com` 查 release(没 token 就是 **HTTP 403**,`mise install` 直接失败);`aqua:*` 的 registry 数据内置在二进制里,直接从 `github.com/.../releases/download/...` 下载,不碰 GitHub API。 所以 `mise` 写成 `"aqua:jdx/mise"`、`neovim` 写成 `"aqua:neovim/neovim"`。 **registry 里没有的工具要自己点名后端**:read 里的 `nom` 和 `eilmeldung` 既不在 mise 的 registry,也不在 aqua 的 registry,裸名字根本解析不出来,所以写死成 `"github:guyfedwards/nom"`、`"github:christo-auer/eilmeldung"`。不用 `go:`/`cargo:` 的原因: 那两个后端会在每台机器上从源码编译(nom 还带 cgo 的 go-sqlite3,要 C 编译器),而 release 里已经有 linux/darwin/windows × amd64/arm64 的预编译二进制。代价是 `github:` 后端要查 `api.github.com`,共用出口 IP 的机器可能撞到匿名限流,设 `GITHUB_TOKEN` 可以提高额度。 **mise bootstrap 会被自动刷新**:`~/.local/bin/mise` 是 shell 激活之前 `command -v mise` 找到的那个副本,它必须等于仓库 pin 的版本,否则 shell 会激活一个旧版 mise。 仓库根的 `run_dotfiles-mise-bootstrap.sh` 钩子(Windows 用 `run_dotfiles-mise-bootstrap.cmd`) 在每次 `chezmoi apply` 后比对一次:版本不一致就用 mise 自己装好的那个 pin 版本覆盖 (不需要联网),没有才走官方安装脚本。逻辑只有一份,在 `dot_config/dotfiles/mise-bootstrap.sh`(部署到 `~/.config/dotfiles/mise-bootstrap.sh`)。 ```bash dotfiles mise init # 从 example 创建 ~/.config/mise/config.local.toml dotfiles mise edit # 编辑本机覆盖 dotfiles usel jq@1.7.1 # 安装并记录到本机覆盖文件 dotfiles mise path # 打印路径 dotfiles mise status # 查看 example / 本机覆盖 / 已选类别 / mise 版本 ``` 选类别(每机一次,写在 `~/.config/mise/miserc.local.toml`): ```toml env = ["dev", "oci"] # base 永远加载 ``` 或者临时用 `MISE_ENV=dev mise install`(等价 `-E dev`)。也可以让 CLI 改: ```bash dotfiles mise env list # 看当前选了哪些 + 有哪些可选 dotfiles mise env menu # 交互式勾选(数字切换,a 全选,n 清空,q 退出) dotfiles mise env add dev oci # 加(幂等,不产生重复) dotfiles mise env remove dev # 删 dotfiles mise env set dev oci # 整体替换 dotfiles mise env clear # 清空(只剩 base) ``` 优先级:`-E` > `MISE_ENV` > 项目 `.miserc.local.toml` > 全局 `miserc.local.toml` > 全局 `miserc.toml`。多个 env 可同时选(`MISE_ENV=dev,oci`),**顺序有意义**:同名工具以靠后的为准。 覆盖写法:`jq = "latest"` 添加本机专属工具,`node = "22"` 覆盖 base 清单的版本,`zig = "none"` 让 `mise install` 跳过某个工具。 记录工具的写法(`mise install` **不写**任何配置文件,只负责下载安装): ```bash dotfiles usel jq@1.7.1 # 默认记到 config.local.toml mise use --path ~/.config/mise/config.local.toml jq@1.7.1 # 等价写法 mise use -g jq@1.7.1 # 记到 base 清单(chezmoi 会覆盖回去) mise use jq@1.7.1 # 记到当前目录的 mise.toml(别在仓库里跑) ``` `dotfiles usel` 只会写 `~/.config/mise/config.local.toml`,没有 `--global` / `--path` 变体 —— base 清单归 chezmoi 管,要改它就用 mise 自己的 `mise use`。 在仓库目录里跑裸 `mise use` 会生成仓库根的 `mise.toml` —— 那是 chezmoi 源文件,下次 `chezmoi apply` 会把它部署成 `~/mise.toml`(仓库根的 `.mise.toml` 带点号,chezmoi 会跳过,所以是安全的)。 每机文件双重屏蔽:源侧 `dot_config/mise/config.local.toml` / `miserc.local.toml` 在 `.gitignore`,目标侧 `.config/mise/config.local.toml` / `.config/mise/miserc.local.toml` 在 `.chezmoiignore` —— `chezmoi apply` 既不部署它们,也不会覆盖或删除。 版本策略:仓库清单(base / dev / oci / read / task)**全部钉死精确版本**(`latest` 是"装机当天取最新",会让各机器版本漂移,升级只能靠显式提交);每机覆盖 `config.local.toml` 可以用 `latest`。`tool = "none"` 只用于每机覆盖,表示"这台机器不要这个工具"(`mise install` 会跳过它);要全机器都不要,就从仓库清单里删掉那一行。 ⚠️ mise 版本要求:每机覆盖能覆盖仓库清单,需要 **mise ≥ 2026.9.0**;用 `miserc.local.toml` 选类别需要 **mise ≥ 2026.10.0**。旧版本上覆盖会**静默失效**(条目写了但永远不生效)。仓库的 base 清单因此把 `mise` 自己也钉住(`2026.11.0`),`dotfiles mise status` 会提示本机版本是否过旧。 ⚠️ python 安装路径需要 **mise ≥ 2026.10.11**(mise PR #14455):从这个版本起,mise 从自己的 versions host 取 python 版本列表和预编译包地址,不再 git clone pyenv。旧版本要 clone pyenv,在受限网络里会失败(症状是访问 `github.com/pyenv/pyenv.git` 时 DNS 报错)。解法是把 mise 升到仓库钉的版本,而不是换后端:mise 没有第二个 python 后端(`mise registry python` 只有 `core:python`)。 ## 模板变量 所有 `.tmpl` 文件可以访问以下变量: | 变量 | 来源 | 说明 | |---|---|---| | `.editor` | `.chezmoidata/data.toml` | 默认编辑器 | | `.shell` | `.chezmoidata/data.toml` | 默认 shell | | `.chezmoi.os` | 自动注入 | `linux` / `darwin` / `windows` | | `.env.` | `.chezmoidata/env.toml` | 环境变量值 | | `.private_data.` | `.chezmoidata/private_data.toml`(本机、gitignored) | 渲染时读本机覆盖值 | ### 每机覆盖(render-time) `~/.local/share/chezmoi/.chezmoidata/private_data.toml` 是**每机一份、从不入库**的数据文件, 模板在渲染时读它,缺失的键回落到仓库默认值: ```toml [private_data.helix] # theme = "dotfiles_mocha" # clipboardProvider = "termcode" # softWrap = true # trueColor = true ``` 当前只有 **helix** 用这个机制(`dot_config/helix/config.toml.tmpl` → `~/.config/helix/config.toml`)。 改动在下次 `chezmoi apply` 后生效;这个文件由 `dotfiles local`(菜单里的 private-data 一项) 或手动跑 onboarding 脚本时创建。 ### helix 的主题与光标颜色 仓库自带主题 `dot_config/helix/themes/dotfiles_mocha.toml` → `~/.config/helix/themes/dotfiles_mocha.toml`。 它 `inherits = "catppuccin_mocha"`(继承内置主题的调色板,不复刻),只额外钉死**各模式的光标颜色**: | 主题键 | 作用 | |---|---| | `ui.cursor.primary.normal` / `.insert` / `.select` | 主光标在 normal / insert / select 模式下的颜色 | | `ui.cursor.normal` / `.insert` / `.select` | 多选时其余光标的颜色(按模式) | **helix 的 `config.toml` 没有光标颜色选项**——颜色属于主题数据;`[editor.cursor-shape]` 只管形状。 而且 helix **只在光标形状是 `block` 时才画主光标**:`bar`/`underline` 时主光标交给终端画, 主题里的颜色根本不渲染。所以仓库的 `[editor.cursor-shape]` 三个模式都是 `block`——形状不配合,颜色就白钉了。 要换颜色,改 `dot_config/helix/themes/dotfiles_mocha.toml` 里对应那行;要换整套调色板, 在本机 `private_data.toml` 里写 `theme = "kanagawa"` 等内置主题名(本机覆盖优先)。 ## 常用命令 ```bash # 验证:所有测试一次性跑完 make test # 单独测试 make test/chezmoi # chezmoi apply --destination tmp/(安全测试,不动系统) make test/shellcheck # shellcheck 所有 .sh 文件 make test/lua # stylua 格式检查 nvim Lua 文件 make test/template # 验证 .tmpl 文件可渲染 make test/gitignore # 确认没有私密数据被 git 跟踪 make test/wezterm # WezTerm 配置行为测试(默认 shell、每机覆盖) make test/windows-cli # Windows 启动器与用户 PATH 钩子 # 调试 make debug # 工作区状态、chezmoi 版本 make debug/env # 当前环境变量和 private_data.toml make debug/chezmoi-diff # chezmoi diff 看会改什么 make debug/sources # 列出所有 chezmoi 源文件 # 预览模板渲染结果 make debug/template-env # 预览 env.conf 输出 make debug/starship-nerd # nerd-font starship 配置 make debug/starship-ascii # ascii 回退 starship 配置 # 手动渲染模板 chezmoi execute-template dot_config/dotfiles/env.conf.tmpl # 日常操作 chezmoi apply # 部署所有配置 chezmoi update # 拉取源目录的更新 + apply(仓库改了之后用这个) chezmoi status # 看有哪些文件需要更新 chezmoi add # 跟踪新文件 ``` ## 平台处理 - `.chezmoi.os` 在 Go 模板中提供当前操作系统标识 - Termux 被 chezmoi 视为 `linux`,需运行时通过 `[[ -d /data/data/com.termux ]]` 判断 - 模板中可使用 `{{ if eq .chezmoi.os "linux" }}...{{ else }}...{{ end }}` 做平台分支 ## dotfiles CLI `~/.local/bin/dotfiles` 是一个 bash 全局 CLI 工具,由 chezmoi 部署到 PATH。交互式菜单只用 bash 内建(read / printf),不依赖 fzf、dialog 之类的外部工具。 ```bash dotfiles # 显示帮助 dotfiles version # 版本号 dotfiles bash status # 桥接块在 ~/.bashrc 和登录文件里的状态 dotfiles bash install # 幂等附加桥接块 dotfiles bash uninstall # 幂等移除桥接块 dotfiles attach # 等价于 'bash install' dotfiles detach # 等价于 'bash uninstall' dotfiles status # 等价于 'bash status' dotfiles mise init # 创建 ~/.config/mise/config.local.toml dotfiles mise edit # 编辑每机 mise 覆盖 dotfiles usel jq@1.7.1 # 安装并记录工具(只写 config.local.toml) dotfiles mise env menu # 交互式选择本机使用的工具类别 dotfiles mise status # 查看 example / 每机覆盖 / 类别 / mise 版本 ``` ### 每机文件的统一入口 仓库里的「每机文件」散落在三个目录、用了四套机制(`~/.env`、`~/.config//`、chezmoi source dir)。`dotfiles local` 是它们的统一入口: ```bash dotfiles local # 交互菜单:选一个文件,直接用 $EDITOR 打开 dotfiles edit # 'local' 的快捷方式 dotfiles edit # 不进菜单,直接编辑某一个 dotfiles edit --all # 一个编辑器会话里打开全部(nvim 多标签) dotfiles local list # 清单:每个文件在本机是否存在 dotfiles local path [name] # 打印绝对路径(可管道) dotfiles local status # 哪些已配置、哪些还缺 ``` 菜单长这样: ``` Per-machine files on this machine: 1) env [ready] ~/.env Machine environment variables 2) secrets [missing] ~/.config/dotfiles/secrets.age Encrypted per-machine secrets 3) mise-tools [missing] ~/.config/mise/config.local.toml mise tool override for this machine 4) mise-cats [ready] ~/.config/mise/miserc.local.toml Tool categories for this machine 5) nvim-custom [missing] ~/.config/nvim/lua/inori/custom.lua Neovim inori overrides 6) wezterm-local [missing] ~/.config/wezterm/local.lua WezTerm per-machine overlay 7) private-data [ready] ~/.local/share/chezmoi/.chezmoidata/private_data.toml Render-time per-machine data edit a file (number), a = all, p = paths, q = quit: ``` 几点值得注意: - **文件不存在会自动从 `*.example.*` 生成再打开**,不用再手动 `cp`。 - **改完会提示后续动作**:`private_data.toml` 是渲染期数据,不跑 `chezmoi apply` 改动不会生效;`config.local.toml` 加了新工具要 `mise install`。 - **清单在仓库里**:`dot_config/dotfiles/local-files`,一行一个文件(`name | target | example | kind | description`)。加一个每机文件,往这个文件里加一行就行。 - **没有终端时不会卡住**:`dotfiles local` 在管道里直接打印清单然后退出。 桥接块格式(写入 `~/.bashrc` 末尾): ```sh # >>> dotfiles-bridge >>> # Managed by dotfiles -- regenerate with: dotfiles bash install if [ -f "$HOME/.config/bash/bashrc" ]; then . "$HOME/.config/bash/bashrc" fi # <<< dotfiles-bridge <<< ``` 桥接块外的所有原生内容**逐字节保留**;所有写操作通过 `tmp + mv -f` 原子完成。 ### Windows 上的 dotfiles 命令 `dotfiles` 是 bash 脚本,Windows 无法直接执行(`cmd.exe` / PowerShell 按 `PATHEXT` 找命令,无扩展名的文件不算命令),而且 `~/.local/bin` 默认也不在 Windows PATH 上。仓库用两个文件补齐: | 文件 | 作用 | |---|---| | `dot_local/bin/dotfiles.cmd` | 部署到 `~/.local/bin/dotfiles.cmd`,用 Git for Windows 的 `bash.exe` 跑同一个脚本,并透传参数与退出码 | | `run_dotfiles-path.cmd` | apply 后的钩子,把 `~/.local/bin` 追加到 Windows **用户** PATH(`HKCU\Environment`) | ```cmd REM cmd.exe / PowerShell 里直接用 dotfiles bash status dotfiles --help ``` 钩子用 `reg query` / `reg add` 读写 PATH,**不用 `setx`**——`setx` 会在 1024 字符处截断,静默毁掉长 PATH。钩子只追加、不删除,重复 apply 不会重复添加,并且永远返回 0,不会让 apply 失败。 PATH 的改动只对**之后启动**的进程可见,所以改完要新开一个终端。 ## tsk 任务看板 [tsk](https://gettsk.sh) 是人和 agent 共用的任务看板:一个 TUI 给你,一个无头 CLI(`tsk list/add/status/steps --json`)给 agent,数据存在 `~/.tsk`。 它在 `task` 类别里(`dot_config/mise/mise.task.toml` → `~/.config/mise/mise.task.toml`),钉死精确版本 `"github:smarzban/tsk" = "0.13.0"` —— 后端必须写死,因为 `tsk` 在 mise 和 aqua 的 registry 里都没有,裸写 `"tsk"` 根本解析不出来。 ```sh dotfiles mise env add task # 选中 task 类别(写进 ~/.config/mise/miserc.local.toml) mise install # 装上 tsk ``` **二进制归 mise 管,不要跑 `tsk update`。** 它会原地覆盖已安装的二进制(pin 就成了空话),还会往 `~/.bashrc` 和登录文件里追加 PATH 块 —— 那两个文件归桥接块管。上游安装脚本更糟:它往 `~/.local/bin` 装,和 `dotfiles` CLI、pin 住的 `mise` 同目录。升级方式是改 `dot_config/mise/mise.task.toml` 里的版本号再 `mise install`。 **herdr 插件由仓库自己提供**(`dot_config/herdr/plugins/herdr-tsk/`),不用 `tsk setup herdr`:它生成的 manifest 会把跑它的那个 `tsk` 的**绝对路径**烤进去(路径里带版本号),升 pin 就失效;生成的目录名还是内容哈希,每次改动都留一堆没人清理的旧目录。仓库的脚本改成**运行时**找二进制(PATH → `mise which tsk` → mise 的 shim → install 目录里最新的版本目录),所以升 pin 不用重新注册。 快捷键写在 chezmoi 管的 herdr 配置里:`alt+t` 开看板,`alt+a` 快速录入。`prefix+a` 被 `previous_agent` 占了,而且 `tsk setup herdr` 在非交互环境下遇到这个冲突会**直接拒绝**。 插件的注册是机器级状态,`run_dotfiles-herdr-plugin.sh` 钩子在每次 apply 之后跑 `herdr plugin link`。 agent 侧的 skill 每台机器自己装:`tsk setup agents`(内容嵌在 tsk 二进制里,跟着版本走,仓库不重新发布)。装出来的三个路径(`~/.config/opencode/skills/tsk-cli/`、`~/.claude/skills/tsk-cli/`、`~/.agents/skills/tsk-cli/`)都在 `.chezmoiignore` 里,`chezmoi apply` 不会覆盖。 ## WezTerm 配置在 `dot_config/wezterm/`(`wezterm.lua` + `cockpit/` 模块树),部署到 `~/.config/wezterm/`。 **Windows 上默认 shell 的优先级:WSL → PowerShell → cmd。** `cockpit/launch.lua` 在配置加载时按顺序取第一个真实存在的程序: | 候选 | 程序 | 判定方式 | |---|---|---| | `wsl` | `wsl.exe`(可带 `-d <发行版>`) | `wezterm.default_wsl_domains()` 非空(WezTerm 自己问 WSL,`wsl.exe` 存在不代表装了发行版) | | `powershell` | `pwsh.exe -NoLogo`,否则 `powershell.exe -NoLogo` | PATH 查找 + `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe` | | `cmd` | `cmd.exe` | PATH 查找 + `%SystemRoot%\System32\cmd.exe` | 非 Windows 平台不设置 `default_prog`,仍然用你自己的登录 shell。 ### 关闭按钮:直接关掉整个 WezTerm `cockpit/window.lua` 设 `window_close_confirmation = "NeverPrompt"`:点关闭按钮就是关窗口, 开了多少个 tab 都一起关掉,中间不再弹确认框(WezTerm 默认在多 tab 时会问一句)。 想找回确认框,在 `local.lua` 里写 `window_close_confirmation = "AlwaysPrompt"` 即可。 ### 每机覆盖:local.lua `~/.config/wezterm/local.lua` 会覆盖在仓库配置之上,机器想改什么就改什么,不用动仓库。仓库里提供模板 `dot_config/wezterm/local.example.lua`,复制过去改就行: ```sh cp ~/.config/wezterm/local.example.lua ~/.config/wezterm/local.lua ``` ```lua return { shell = "powershell", -- "wsl" | "powershell" | "cmd" wsl_distribution = "Ubuntu-24.04", -- 其它任意 WezTerm 配置项 } ``` `shell` 把该 shell 提到最前面(其余仍作为后备),`wsl_distribution` 给 WSL 候选加上 `-d `。其余键原样并入配置,所以在覆盖里写 `default_prog` 会直接生效。 这个文件属于机器:`chezmoi apply` 既不写它也不删它(和 nvim 的 `custom.lua` 同样的两段式约定:源侧 gitignore + `.chezmoiignore` 列出目标路径)。改完 WezTerm 会自动重载。 ## 迁移说明(从旧桥接 `~/.bashrc` 升级) 如果你之前运行过 `chezmoi apply`,你的 `~/.bashrc` 可能被替换成了 8 行桥接(旧的 `dot_bashrc` 部署)。本变更后 `chezmoi apply` 不再写 `~/.bashrc`,但你目前的 `~/.bashrc` 仍是旧桥接。要恢复发行版原生内容: ```bash # Ubuntu/Debian: cp /etc/skel/.bashrc ~/.bashrc # 或者从你之前的备份恢复 # 然后让 dotfiles 工具写入新的带 marker 的桥接块: chezmoi apply # 部署新工具到 ~/.local/bin/dotfiles dotfiles bash install # 写入新桥接块到 ~/.bashrc 末尾 ``` ## 安全 以下内容**绝不提交**到 git: - `.chezmoidata/private_data.toml` — 机器专属数据(hostname、platform 等) - `.env` — 手动环境配置(`~/.env`,永不入库) - 任何 secrets、API keys `make test/gitignore` 会在每次 `make test` 时自动检查这些文件是否被误跟踪。