mise bootstrap dotfiles add捕获与更新点文件配置的完整实操指南【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/misemise bootstrap dotfiles add是 mise 点文件dotfiles管理体系中最核心的“捕获capture”命令它把一份正在使用中的配置文件收编进[dotfiles]管理表并自动为其建立受管副本source。本文围绕该命令的完整用法、全部参数语义、配置写入规则与底层事务回滚实现展开帮助你安全地把~/.zshrc、~/.gitconfig、~/.config/starship.toml等文件纳入 mise 的统一管理实现跨机器的同步与历史回溯。命令概览add 做了什么add的作用是“添加或更新[dotfiles]中的点文件条目”它属于修改状态Effect: modifies state类命令完整用法为mise bootstrap dotfiles add [FLAGS] [TARGET]…其核心行为分两种场景依据 src/cli/dotfiles/add.rs 的文档注释目标尚未被管理在配置中创建一条[dotfiles]条目并把目标文件的内容“播种seed”到dotfiles.root默认~/.dotfiles下作为受管 source除非你用--source显式指定源路径目标已被管理跳过建条目的步骤直接用线上目标live target的最新内容更新已有的 source 文件。捕获完成后除非传入--no-applyadd会立即对新条目执行应用apply使用--dry-run则可以只预览 source 捕获与配置写入而不产生任何实际变更。需要说明的是add只是mise bootstrap dotfiles子命令族的一员完整子命令见 src/cli/dotfiles/mod.rs。旧版顶层mise dotfiles命令已废弃并被隐藏将在 mise 2027.2.0 开始警告、2028.2.0 移除见 src/cli/dotfiles/mod.rs请始终使用mise bootstrap dotfiles前缀。参数与标志完全参考参数/标志说明[TARGET]…要添加或更新的目标路径一个或多个每个目标必须为绝对路径或以~/开头源码在 add.rs 中校验相对路径会直接报错--changed批量更新所有处于copy模式下、内容已发生变化的文件的 source不可与 TARGET 同时使用-f, --force覆盖已存在的 source 时跳过确认提示-g, --global写入全局配置默认行为与--local、--path互斥-l, --local写入本地项目配置而非全局配置与--global、--path互斥-m, --mode MODE指定写入的 dotfile 模式symlink、symlink-each、copy、template-n, --dry-run仅打印配置/source 更新内容不写入任何东西--no-apply只添加条目、不立即应用-p, --path PATH写入指定的配置文件或目录与--global、--local互斥-s, --source PATH为单个目标指定 source 路径仅能配合一个目标使用-y, --yes跳过确认提示-h, --help打印帮助信息几点从源码确认的互斥与校验规则见 add.rs 的validate()--changed与[TARGET]…不能同时出现不带--changed时必须至少提供一个目标否则报错--source只能配合恰好一个目标使用--mode track被明确拒绝——需要原地跟踪请改用mise bootstrap dotfiles track path未知模式会报错unknown dotfile mode: {mode}不指定模式时回退到dotfiles.default_mode设置值默认symlink见 src/system/files.rs 与 docs/settings.toml。注意-p/--path没有--file别名在add上-f已被--force占用若给-f传路径会被静默当作点文件目标处理源码注释 add.rs 专门说明了这一设计取舍。快速上手四个典型示例官方示例见 add.md 与 add.rs# 1. 收编 ~/.zshrcseed 到 ~/.dotfiles/.zshrc按默认模式symlink应用 mise bootstrap dotfiles add ~/.zshrc # 2. 以 copy 模式收编 starship 配置目标是普通文件不被链接 mise bootstrap dotfiles add --mode copy ~/.config/starship.toml # 3. 显式指定 source把 ~/.gitconfig 的内容存到 dotfiles/gitconfig mise bootstrap dotfiles add --source dotfiles/gitconfig ~/.gitconfig # 4. 批量回写把所有 copy 模式下已改动的文件更新回其 source mise bootstrap dotfiles add --changed场景一收编一个已有文件对于未受管的目标add会先在dotfiles.root~/.dotfiles下推导并创建 source 副本推导规则见下文再向目标配置文件写入[dotfiles]条目随后按dotfiles.default_mode应用。默认symlink模式会把原路径变成指向已保存 source 的链接想保留普通文件则加--mode copy。若不想让原文件在捕获时被改动使用--no-apply先审查 source 与配置内容之后再手动apply。场景二回写 copy 模式的就地修改点文件管理中一个经典场景是copy模式的程序自己改写了目标文件如 starship 运行时写配置此时用add再次捕获即可把改动保存回 source$EDITOR ~/.config/starship.toml mise bootstrap dotfiles add ~/.config/starship.toml详见 docs/dotfiles.md 的“Capturing changes”一节add对已管理目标只会更新既有 source不会新建条目。场景三--changed 批量同步mise bootstrap dotfiles add --changed会遍历配置中所有满足以下条件的条目并更新其 source源码条件见 add.rs模式为copy目标是普通文件且不是符号链接source 不是目录当前状态为Differs与 source 内容不一致。它跳过目录复制、symlink、template 与 inline content 条目。另一个重要约束是每个被选中文件的配置必须受信任trusted——若其来源配置既非全局配置又未被信任命令会直接报错并中止--changed requires trusted configuration。若没有任何文件需要更新命令打印dotfiles: no changed copy-mode files并正常退出此时若发现存在未被信任却声明了[dotfiles]的配置文件会打印跳过警告逻辑见 mod.rs。源码视角add 的完整执行链路run()把整个操作包装在OperationScope::wrap(bootstrap dotfiles add, ...)中执行add.rs意味着它像apply、unapply一样会为受影响的文件记录前后两个历史检查点checkpoint可用mise bootstrap dotfiles history浏览。整体流程可拆为五步校验validate处理上文的互斥与模式校验解析配置目标通过resolve_target_config_path决定写入哪个配置文件默认全局、prefer_toml: true、且禁止写入 home 目录下的本地配置add.rs规划planned对每个目标解析绝对路径、检查是否与既有track条目或[dotfiles]编辑条目冲突、复用已管理条目的 source 与 mode--mode对已管理条目会被忽略并给出警告add.rs并去重——通配符展开或等价写法可能解析到同一个配置键配置写入按目标唯一因此文件系统工作也只规划一次add.rs事务执行先做备份再逐项捕获 source、写入配置、执行 apply失败回滚任何一步出错都会把 source、target、配置文件和移动过的文件全部还原。source 的推导规则当目标位于$HOME之下且未提供--source时source 由implied_source()推导src/system/files.rs~/.zshrc→~/.dotfiles/.zshrc~/.config/foo.toml→~/.dotfiles/.config/foo.toml目标在$HOME之外如/etc/...时必须显式指定source或使用内联content。写入配置时add会智能精简条目能推导出 source 就省略source字段默认symlink模式也省略mode字段只有显式用--mode选择的模式才会被写出inline_entry实现见 add.rs。目标键会被规范化为~/开头的形式normalized_target_rawadd.rs。事务性备份、跨文件系统与回滚捕获过程中涉及把线上文件移动到 source 位置mise 将其视为一次事务add.rs备份source 与 target 都会被备份到临时目录符号链接备份其链接目标、普通文件复制内容、缺失则记录Missing跨文件系统当 source 与 target 不在同一文件系统时rename会失败CrossesDevicesmise 改为先在目标父目录创建一个.mise-dotfiles-rollback-临时目录暂存原文件再把原文件复制为 source——这样回滚时只需一次原子重命名避免递归删除可能再次失败add.rs回滚rollback_add()逆序恢复被移动的目标、还原 target/source 备份、并把配置文件写回捕获前的原文若配置原本不存在则删除add.rs。该逻辑有对应单元测试覆盖如rollback_uses_staged_cross_device_originaladd.rsapply 阶段条目捕获完成后会以force: false、yes: true的参数执行一次内联 applyadd.rs把新条目真正落到目标路径上。add 与其他 dotfile 模式的关系add捕获出的条目究竟以什么方式落盘取决于你选择的模式模式含义详见 docs/dotfiles.md 的 Modes 一节模式apply 时的行为适用场景symlink创建一个指向文件或整个目录的链接默认希望透过目标路径的编辑直接改到 sourcesymlink-each为目标目录下每个文件分别建链接目标目录中还有 mise 不应管理的其他文件copy复制文件/目录覆盖同名文件应用需要普通文件或会自己改写配置template用模板引擎渲染 source 文件输出依赖机器相关变量示例链接整个目录[dotfiles] ~/.config/nvim { source dotfiles/nvim, mode symlink }dotfiles.default_mode与dotfiles.root都可以在配置中调整分别对应环境变量MISE_DOTFILES_DEFAULT_MODE与MISE_DOTFILES_ROOT见 docs/settings.toml。捕获后的条目长什么样以add ~/.zshrc为例命令会在全局配置默认~/.config/mise/config.toml中写入[dotfiles] ~/.zshrc { mode symlink }而add --mode copy ~/.config/starship.toml会写出[dotfiles] ~/.config/starship.toml { source ~/.dotfiles/.config/starship.toml, mode copy }手动维护时你也可以写得更灵活省略 source 使用推导路径、source 写成字符串沿用默认模式、用content内联整个文件、用通配符一次匹配多个文件、用exclude排除目录中的部分文件、用manifest git只管理 Git 索引中的文件或用block/line编辑条目只管理文件的某一段——这些条目同样可以通过add开始管理详细条目语法见 docs/dotfiles.md。冲突处理与安全须知add场景下最常遇到的冲突是“目标已被其他方式管理”目标已处于track模式报错并提示先untrack再带--mode copy重新捕获add.rs目标已被[dotfiles]的编辑条目block/line管理报错要求先移除或重命名那些条目add.rs目标已存在且与 source 不同交互式确认是否用线上内容覆盖 source-y跳过、-f强制覆盖拒绝则跳过该目标add.rs。关于应用阶段的冲突docs/dotfiles.md 给出了完整规则symlink 模式拒绝替换真实文件/目录需要apply --forcecopy/template模式则无需--force即可覆盖目标内容。文档特别提醒copy模式下再次 apply 会覆盖你对目标文件的直接修改所以在覆盖前应先用add把改动回写 sourcedocs/dotfiles.md 的警告框。配套命令链与后续操作捕获只是起点收编后的文件可以与以下命令配合形成完整工作流命令清单见 docs/dotfiles.mdmise bootstrap dotfiles status # 查看文件状态applied / differs / missing 等 mise bootstrap dotfiles diff ~/.zshrc # 查看某个目标的待应用差异 mise bootstrap dotfiles apply --dry-run # 预览应用不实际写入 mise bootstrap dotfiles edit ~/.zshrc # 直接编辑受管 source 或所属配置 mise bootstrap dotfiles unapply --dry-run # 预览移除受管目标想保存文件的历史版本对路径执行track见 track.md再用mise bootstrap dotfiles save手动打检查点或配置 watcher 服务实现自动保存想跨机器同步为历史仓库配置 origin 并开启自动同步见 docs/dotfiles.mdadd、apply、unapply、edit --apply都会记录操作前后两对历史检查点可用mise bootstrap dotfiles history浏览与回滚docs/dotfiles.md。小结mise bootstrap dotfiles add把“从零书写配置文件”变成“一步收编现有文件”它自动推导 source 路径、写入精简的[dotfiles]条目、按所选模式立即应用并以事务 回滚保证中途失败不破坏原文件。理解其参数互斥规则、source 推导逻辑与模式差异再配合apply、status、track与历史同步能力即可把整套 dotfiles 工作流放心交给 mise 管理。【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
