mise bootstrap repos：在 mise.toml 中声明式管理 Git 仓库克隆与更新

mise bootstrap repos：在 mise.toml 中声明式管理 Git 仓库克隆与更新

【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise

mise 的 bootstrap 系统可以在[bootstrap.repos]配置块中声明 Git 仓库的克隆位置、远端地址与目标 ref，并通过mise bootstrap repos子命令族（status/apply/update/exec）实现声明式收敛、安全更新与批量命令执行。本文以 docs/bootstrap/repos.md 为主线，结合仓库源码（src/system/repos.rs、src/cli/system/install.rs、src/cli/bootstrap.rs）讲解配置语法、路径规则、各命令的实战用法、仓库状态模型以及"安全更新、绝不覆盖本地工作"的核心设计哲学。

[bootstrap.repos]配置语法

在任意 mise 配置文件（如项目根目录的mise.toml、~/.config/mise/config.toml）中声明：

[bootstrap.repos] "~/src/dotfiles" = { url = "git@github.com:jdx/dotfiles.git", ref = "main" } "~/src/mise" = { url = "https://github.com/jdx/mise.git" }

• key：仓库克隆的目标路径；
• url（必填）：Git 远端地址，支持 ssh、https 等常见形式；
• ref（可选）：分支名、tag 或完整 commit SHA，用于固定检出版本。

这些声明不会在加载配置时生效，必须通过显式命令应用。对应的 TOML 解析结构见源码 RepoTomlConfig（url与git_ref字段），校验逻辑位于 RepoRequest::from_toml：url不能为空、不能以-开头（防止被误解析为命令行选项），ref同样不能为空或以-开头。

目标路径的三种写法

源码 RepoRequest::from_toml 详细实现了相对路径校验：相对路径必须位于项目根目录之内——不能为空或.，不能包含..、绝对路径段或 Windows 盘符前缀；实际解析时只拼接Normal段，因此./foobar会干净地解析为<root>/foobar而非<root>/./foobar。若在全局配置（如~/.config/mise/config.toml）中写相对路径，由于没有项目根可供解析，会直接报错：

relative repo paths are only allowed in a project config; use an absolute path or a `~/` path

跨配置文件的合并语义

[bootstrap.repos]遵循 mise 的配置层级：加载所有配置文件后按"全局 → 本地"的顺序合并，以展开后的目标路径为 key——更本地的配置会完整替换同路径的整个条目（而非逐字段合并）。无效条目会告警并跳过。实现见 repos_from_config：

// config_files is ordered local -> global; reverse for global -> local for cf in config.config_files.values().rev() { for (path_raw, repo) in sys.repos { match RepoRequest::from_toml(path_raw.clone(), repo, cf.project_root().as_deref()) { Ok(request) => { merged.insert(request.path.clone(), request); } Err(err) => warn!("[bootstrap.repos].\"{path_raw}\": {err}"), } } }

这意味着你可以在全局配置中定义通用的仓库清单，再在某个项目里针对同一路径覆盖 url 或 ref。

四条命令的实战用法

命令族定义在 BootstrapRepos，包含apply、update、exec、status四个子命令。

status：查看仓库收敛状态

mise bootstrap repos status # 查看每个仓库的检出状态 mise bootstrap repos status --json # 输出机器可读的 JSON mise bootstrap repos status --missing # 存在未收敛仓库时以退出码 1 结束

• --json输出每个仓库的path、path_raw、url、ref、origin、current_ref、current_sha、state、reason字段，适合脚本化巡检（实现见 BootstrapReposStatus::run）；
• --missing用于 CI 或 hook：只要有任何仓库不是current状态即返回退出码 1，实现中通过if !s.state.is_current() { any_missing = true; }累积判断。

apply：建立声明好的检出

mise bootstrap repos apply # 克隆缺失仓库、收敛到声明 ref mise bootstrap repos apply --dry-run # 只打印将要执行的命令，不真正运行 mise bootstrap repos apply --yes # 跳过确认提示 mise bootstrap repos apply --skip-dirty # 跳过有本地改动的仓库

apply是收敛型操作：目标是对齐声明状态。对missing仓库执行git clone；对differs（干净但不在声明 ref 上）的仓库执行git fetch+git checkout+ 按需git pull --ff-only（见 apply_statuses 与 update_repo）。未声明ref的已有仓库会被视为 current，保持当前 commit 不动——apply 不会主动拉取。

update：拉取最新内容

mise bootstrap repos update # 克隆缺失并 pull 已有仓库 mise bootstrap repos update ~/src/mise # 只更新匹配该路径的仓库 mise bootstrap repos update --dry-run # 只打印命令 mise bootstrap repos update --yes # 跳过确认 mise bootstrap repos update --skip-dirty # 跳过有本地改动的仓库

与apply的关键区别在 update_statuses 和 update_repos：

• 对未声明ref的 current 仓库，update会执行 fetch 并将当前分支 fast-forward（update_unpinned_repo）；
• 对已声明ref的仓库，update仍以声明的 ref 为目标，不会脱离它去拉最新——ref是 apply 与 update 共同的靶心；
• 对处于 detached HEAD 且未固定 ref 的仓库，会告警并跳过；
• 路径参数用于精确筛选：源码 filter_repos 要求路径必须精确匹配配置中原始路径或展开后的路径，否则报错no configured repo matched path: ...。

exec：在每个可用仓库中执行命令

mise bootstrap repos exec -- git status # 在每个可用仓库运行 git status mise bootstrap repos exec ~/src/mise -- git pull # 只在该仓库运行 mise bootstrap repos exec --continue-on-error -- command mise bootstrap repos exec --dry-run -- command

exec的实现见 repos::exec：

• 命令通过Command::new(program).args(args).current_dir(repo_path)直接执行，不经 shell 插值，避免注入与引号问题；
• missing与conflict状态的仓库会被跳过并告警；
• 默认遇到第一个失败即停止（bail），加--continue-on-error后遍历所有可用仓库，最后统一报告失败列表；
• --dry-run打印形如cd <path> && <command>的合成命令；
• 命令必须在--之后，--之前的位置参数用于筛选仓库路径。

参数速查

交互确认的实现位于 mutate_repos：非 dry-run、非--yes且终端有人工用户时，会先列出目标仓库并询问确认，用户拒绝则整批跳过。

仓库状态模型

status与各命令以统一的五态模型工作，枚举定义于 RepoState，状态判定逻辑在 status_one：

ref_is_current（src/system/repos.rs#L440-L457）支持三种对齐形式：当前分支名等于 ref、当前 HEAD SHA 等于 ref（即 ref 是完整 SHA）、或 ref 对应的本地引用指向当前 HEAD，同时会对照远端引用校验 head 是否与远端一致。

核心语义：安全第一的声明式设计

无隐式写入

仓库只会在显式的apply、update、exec或顶层mise bootstrap时被改动。status只读，配置加载本身零副作用。apply 永远不会主动 pull 一个未声明 ref 的已有仓库。

无强制重置（绝不覆盖本地工作）

dirty 仓库、非空且非 git 的目标路径、origin 不匹配的目录都会直接失败而不是覆盖。preflight 校验见 preflight_statuses：任何 dirty 或 conflict 都会整体终止。--skip-dirty则是先剔除 dirty 仓库（保留其余）再 preflight，因此冲突依旧会先于任何变更失败——你不可能在收敛过程中意外丢掉本地改动。

origin 匹配：三种网络形式视为同一仓库

mise 采用传输无关的比较：以下三种形式指向同一个仓库：

git@host:path ssh://git@host/path https://host/path

核心实现在 repo_identity 与 repo_identity_parts，将 URL 归约为[user@]host[:port]/path身份串：

• 只有显式用户（ssh）或约定俗成的git用户才参与比较；ssh 省略用户时 git 会解析为登录用户而非git，因此不归一化；
• https 的 userinfo 被视为凭据而非仓库身份，带用户名/密码的 https URL 直接返回None（保持精确匹配）；
• 其余形式一律精确匹配：http://与git://保持独立（不安全的传输绝不会被静默当作配置的 https 等价物）、带 query/fragment 的 URL、本地路径与file://URL、显式端口、非git的 ssh 用户、不同的主机或路径，都视为冲突；
• 比较前会统一去除末尾/，并对https://、ssh://、scp 形式剥离.git后缀（normalize_remote_url），本地路径与 Windows 绝对路径不剥（should_strip_git_suffix）。

省略ref的语义

对已有且 origin 匹配的仓库，未声明 ref 即视为 current：mise 不 fetch、不更新。想要"拉最新"的命令式行为，请使用mise bootstrap repos update。

在完整 bootstrap 流程中的位置

顶层mise bootstrap的执行顺序（源码 src/cli/bootstrap.rs 及模块注释）为：packages（+compose）→repos→ dotfiles → defaults → user → tools，每个阶段前后都有 pre/post hooks（PreRepos/PostRepos）。这一编排使下面的链条成为可能：

1. [bootstrap.packages]先安装git；
2. [bootstrap.repos]克隆 dotfiles 仓库；
3. [dotfiles]从该检出应用配置文件。

顶层命令会读取--skip-dirty并在 apply/update 之间选择：加--update走 update_repos，否则走 apply_repos。

实践建议

• 首次收敛用 apply：mise bootstrap repos apply --dry-run先预览全部将执行的git clone/git checkout/git pull --ff-only，再正式执行；
• 日常拉新用 update：mise bootstrap repos update --skip-dirty在不触碰本地改动的前提下将未固定 ref 的仓库 fast-forward；
• CI 校验用 status：mise bootstrap repos status --missing以退出码表达"是否全部收敛"，可直接接入检查脚本；
• 批量运维用 exec：mise bootstrap repos exec --continue-on-error -- git pull --ff-only遍历所有仓库并汇总失败；
• 固定版本用完整 SHA：将ref写为完整 commit SHA 可实现可复现的检出，apply 与 update 都会收敛到该 SHA；
• 前提条件：系统需安装 git，并能对每个配置的 origin 完成认证。若 dotfiles 源位于这些检出中，请按完整 bootstrap 的顺序先 apply repos 再应用 dotfiles。

相关实现与测试可继续阅读：src/system/repos.rs（状态机与 git 操作）、src/system/mod.rs#L780-L801（配置聚合）、src/cli/system/install.rs#L238-L347（apply/update 收敛流程）、src/cli/bootstrap.rs#L966-L1056（子命令定义）。

【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise