Git maintenance start 怎样让仓库后台自动维护

Git 仓库长期 fetch、commit 后，对象数量和提交图会持续增长。git maintenance 的作用是把这些优化任务拆成适合后台执行的频率，减少把完整维护塞进某一次前台 Git 命令的等待时间。要让当前仓库进入后台维护范围，最小入口是：

官方地址：https://git-scm.com/docs/git-maintenance

# 在目标仓库目录执行：注册当前仓库并启动后台调度
git maintenance start --scheduler=auto

start 会完成类似 register 的配置，并更新系统调度器，让它按计划调用 git maintenance run --scheduled。下面只围绕当前仓库的启动、查看、停止和取消登记说明，手工 repack 与 CI 维护不在范围内。

先准备目标仓库和 Git 入口

先进入需要维护的仓库，再确认 Git 版本。git maintenance start 作用于当前仓库，不是把机器上的所有仓库一次性打开；全局配置中的 maintenance.repo 记录了被登记的仓库。

# 确认当前目录确实位于目标仓库
git rev-parse --show-toplevel

# 查看客户端版本，避免把旧版行为当成当前语义
git --version

# 查看当前用户已登记的维护仓库；没有结果也不代表命令失败
git config --global --get-all maintenance.repo

Git 官方维护页当前给出的入口包括 run、start、stop、register、unregister 和 is-needed。如果你只想手工执行一次任务，使用 run；如果目标是让系统周期性维护当前仓库，才使用 start。

用 start 把当前仓库交给后台调度

在仓库根目录执行下面的命令：

# auto 让 Git 按当前操作系统选择可用的调度器
git maintenance start --scheduler=auto

启动后，仓库会被加入维护列表，Git 也会建立按小时、按天和按周触发的调度入口。默认的增量策略会把任务分散到不同频率，例如提交图和预取可以按小时进行，松散对象清理和增量重打包可以按天进行；实际启用项仍受 Git 版本与配置影响。

--scheduler 也可以明确指定调度器，但通常先使用 auto 更稳妥：

不要把“启动调度”理解成每次立即完成全部清理。后台运行的是带计划参数的维护命令，任务会依据频率和配置判断本次是否需要执行。

查看仓库登记和任务策略

启动后可以从两个层面检查：Git 配置是否登记了当前仓库，系统调度器是否出现了 Git 维护任务。下面的命令只读取配置，不会替你修改调度。

# 读取所有已登记仓库，确认目标路径是否在列表中
git config --global --get-all maintenance.repo

# 查看维护策略；未设置时不要自行推断为某个固定策略
git config --show-origin --get maintenance.strategy

# 让 Git 只判断是否达到维护阈值，不真正执行维护任务
git maintenance is-needed --auto

# macOS 查看 Git 写入的用户级任务文件
ls "$HOME/Library/LaunchAgents"/org.git-scm.git.*.plist 2>/dev/null

is-needed --auto 的退出状态表示当前是否达到自动维护阈值：返回 0 表示需要维护，返回 1 表示暂时不需要。它适合放进脚本的判断分支，不适合拿来证明后台调度器已经成功注册。

Linux 可以查看用户级 timer，Windows 则在任务计划程序里查找 Git Maintenance 任务。不同系统的展示位置不同，但判断重点相同：当前仓库出现在 maintenance.repo，并且对应的小时、日、周调度入口存在。

stop、unregister 与重新启动

这三个动作最容易混淆。stop 只暂停后台调度，并保留当前仓库的登记；以后仍可再次 start。unregister 会把当前仓库从维护列表移除，但它本身不负责停止已经运行的后台维护进程。因此需要彻底撤销时，先停调度，再取消登记。

# 暂停小时、日、周后台调度，但保留仓库登记
git maintenance stop

# 彻底移除当前仓库的维护登记；force 允许仓库当前未登记时也返回成功
git maintenance unregister --force

# 需要恢复时，重新登记并启动调度
git maintenance start --scheduler=auto

如果只是临时排查仓库锁或磁盘压力，优先用 stop，观察结束后再 start。如果仓库已经迁移、目录将被删除，才使用 unregister；它不会替你处理仍在运行的任务。

几个常见误区

执行 start 后为什么没有立刻看到大量对象变化？

后台调度按任务频率与阈值运行，不代表启动命令会立即执行完整 GC。需要一次性维护时，用明确的 git maintenance run 任务，并自行评估仓库锁、耗时和磁盘空间。

start 和 register 应该选哪个？

register 主要初始化仓库登记与推荐配置；start 在此基础上还会更新后台调度器。希望“登记并开始后台维护”时直接用 start。

能不能同时运行 git gc 和后台 maintenance？

不建议把独立的 git gc 与 git maintenance run 并发安排在同一个仓库。官方文档特别提醒两者获取对象数据库锁的方式不同，应该统一维护入口，减少互相干扰。

停止后仓库还会出现在 maintenance.repo 吗？

会。stop 的设计就是暂停调度但保留登记；要让它不再属于后台维护范围，需要再执行 unregister。

最后按这张清单收尾

1. 在目标仓库执行 git maintenance start --scheduler=auto。
2. 用 git config --global --get-all maintenance.repo 确认仓库登记。
3. 按系统查看 launchctl、systemd/cron 或 schtasks 的调度入口。
4. 临时暂停用 stop，彻底移除用 stop 加 unregister。
5. 不要把调度启动、单次维护、完整 GC 和 CI 任务混成一个动作。

这样配置后，Git 的仓库维护就从“偶尔手动清理”变成了有范围、有频率、可暂停的后台任务；当仓库规模、磁盘空间或任务耗时发生变化时，再根据具体维护项调整策略。