Git worktree lock 何时用于保护长期工作树

如果一个 linked worktree 放在移动硬盘、偶尔挂载的网络共享目录，或者会暂时离线的开发盘上，建议在离线前执行 git worktree lock。它保护的是 Git 在主仓库中保存的工作树管理记录，避免该目录暂时不可见时被自动或手动 prune；它不是分支权限锁，也不会把文件变成只读。

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

判断标准很简单：工作树会暂时不可用，但以后还要回来继续使用，就锁定；工作树已经永久删除，才考虑清理；只是换路径，则优先用 move 或在手工移动后用 repair。

先看清目标工作树是不是 linked worktree

不要一看到目录离线就直接执行 prune。先在主仓库或任意仍可访问的 linked worktree 中查看记录。软件界面中对应的路径可以理解为“仓库 → 工作树列表 → 选中目标路径 → 查看状态”；Git 命令的稳定输出则更适合留作自动化记录。

# 用稳定格式查看路径、分支、锁定和可清理状态
git worktree list --porcelain

重点看三类信息：worktree 是实际路径，branch 说明它当前关联的分支，locked 表示已经锁定，prunable 表示 Git 判断其工作目录缺失并可能被 prune。主工作树不是这个命令要保护的 linked worktree 记录，通常不要把主工作树当成锁定对象。

需要长期离线时，给工作树加锁

在工作树仍然可访问时，进入主仓库执行锁定。软件界面说明图中的“工作树列表 → 选中路径 → 锁定原因 → 确认锁定”，对应的命令是下面这一条：

# 用路径指定目标，并留下便于排查的原因
git worktree lock --reason "移动硬盘暂时离线，计划下周继续开发" ../release-worktree

--reason 是可选的，但长期任务建议填写。Git 会在该 linked worktree 的管理目录中保存 locked 标记；以后用 git worktree list --verbose 可以看到原因。锁定后，Git 会阻止普通的移动和删除操作，这正是它适合“暂时不可见但不能丢记录”的场景。

如果只是希望创建工作树后立即保持锁定，也可以在创建时使用 add --lock。但它仍然只解决管理记录被清理的问题，不替代远端备份、分支保护或文件系统权限。

# 创建后直接保持锁定，适合一开始就会离线的工作树
git worktree add --lock --reason "外置盘长期保存" ../archive-worktree main

恢复访问后，先解锁再移动

工作树重新挂载后，先确认路径没有变化，再解除锁定。界面路径可以对应为“工作树列表 → 选中 locked 项 → 查看锁定原因 → 解锁”；命令如下：

# 恢复磁盘或网络目录后，解除保护状态
git worktree unlock ../release-worktree

# 重新列出状态，确认 locked 标记已经消失
git worktree list --porcelain

如果目的是换目录，优先使用 Git 管理的移动命令。它会同时更新工作树的关联信息，不需要手工修改 .git 文件。

# 把 linked worktree 移到新路径；锁定状态存在时先 unlock
git worktree move ../release-worktree ../release-worktree-2026

如果已经用文件管理器移动过目录，原路径与管理记录可能脱节。此时不要反复 add 同一个分支，而是在新位置使用 repair 重新建立连接：

# 手工移动后，从主仓库修复指定工作树的关联路径
git worktree repair ../release-worktree-2026

清理前先预览，别把 prune 当成 remove

prune 处理的是“工作目录已经缺失，但仓库里还残留管理记录”的情况；它不是正常删除工作树的首选。仍然需要保留的目录，即使暂时不可见，也不应被清理。确认某个 linked worktree 永久不再使用时，正常路径是先让目录回到可访问状态，再使用 git worktree remove；如果目录已经消失，才考虑 prune 残留记录。

# 只预览将要清理的缺失记录，不立即删除
git worktree prune --dry-run --verbose

# 确认列表只包含应当移除的残留后，再执行清理
git worktree prune --verbose

看到 locked 时不要用强制参数绕过确认。先判断锁定原因是否仍然成立；只有确认工作树不再需要并承担相应后果时，才解锁并按正确生命周期处理。

几个容易混淆的边界

• lock 不是分支锁。 它不会阻止别人推送同名分支，也不提供代码审查或权限控制。
• lock 不是只读模式。 工作树重新可访问时，仍可正常修改文件；锁定主要影响 move、remove 和 prune。
• move 优先于手工搬目录。 手工移动后要用 repair，不能只改文件夹名称就认为 Git 已经知道新路径。
• prune 不是日常回收。 普通 linked worktree 应使用 remove；prune 主要针对工作目录已经缺失的残留记录。

常见问题

什么时候一定值得写 --reason？

当工作树会离线一段时间、由多人轮换维护，或未来需要根据状态记录判断是否解锁时，建议填写。短期本地目录可以不写。

锁定后还能直接移动工作树吗？

默认不能。先执行 git worktree unlock，再用 git worktree move；不要为了省一步直接使用强制参数。

工作树目录被删除后，应该执行 remove 还是 prune？

目录还在且要正常结束生命周期，用 remove；目录已经缺失，只剩管理记录时，先用 prune --dry-run 预览，再决定是否清理。

速查

# 查看状态
git worktree list --porcelain

# 长期离线前锁定
git worktree lock --reason "暂时离线，稍后继续" 

# 恢复后解锁
git worktree unlock 

# 迁移或修复
git worktree move 
git worktree repair 

# 清理前预览
git worktree prune --dry-run --verbose