Git 教学工作区 · 课程 0002(加餐,一次讲完)· 约 20 分钟 · 前置:0001 · 2026-10-03

归档一个仓库:把它封存,而不是删掉

这节课的胜利:拿一个真实仓库走完 归档 → 写入被拒 → 解归档 → 恢复可写 的完整往返; 不管从界面、命令行还是 API 下手都知道该敲什么,并说清归档 / 删除 / 转私有三者的取舍。 这个功能到本节为止讲完,没有"下一节再说"的部分。

为什么是这一步

今天真实发生过一次:config-cli 与 config-ai-git 两个仓库的内容并进了 config-ai,它们不再需要维护,但也不能删——历史提交、别处引用过的 URL、 "我当初怎么写的"这类回溯价值都还在里面。删掉是不可逆的,放着不管又会被误当成还在维护的项目。 归档就是为这种情况准备的开关:它同时解决"不再改动"和"仍然可查"。

这条也不算偏离使命:使命里说 Git 是「把『我做了什么』变成别人能验证的东西」的底座。 归档回答的是它的后半句 —— 一件事结束之后,该以什么状态留在那里。

最小知识:三条

  1. 归档是一个开关,不是终点。它把仓库变成对所有人只读, 并明示"不再主动维护";随时可以解归档,解完立刻恢复可写。 官方原话是 "make it read-only for all users and indicate that it's no longer actively maintained"。
  2. 它冻结的是协作面,不是代码面。归档后以下全部只读: issues、pull requests、代码、标签、里程碑、projects、wiki、releases、commits、tags、branches、 reactions、code scanning 告警、评论、权限。你不能再增删协作者或团队; 有访问权限的人只能 fork 或 star。要改任何一处,必须先解归档。
  3. 读完全不受影响,可见性也不变。clone / fetch / ls-remote 照常; 仓库不会被删除,private 还是 private,pushed_at(最后一次真实推送时间)也不变 —— 变的只是"能不能写"。归档也不改"协作能力"的开关值(比如 has_issues 仍然是 true), 因为能力没被取消,取消的是写入。

三个入口,同一件事

入口归档解归档
网页界面Settings → Danger Zone → Archive this repository → 读完警告 → 输入仓库名 → 确认Settings → Danger Zone → Unarchive this repository → 输入仓库名 → 确认
命令行gh repo archive <owner>/<repo> --yesgh repo unarchive <owner>/<repo> --yes
纯 RESTgh api -X PATCH repos/<owner>/<repo> -F archived=truegh api -X PATCH repos/<owner>/<repo> -F archived=false

三个入口改的是同一个字段,gh repo archive 本身也是在调那条 PATCH。 命令行省略仓库参数时,作用对象是当前目录所在的仓库 —— 在别人的仓库里手滑就是这个后果, 所以 --yes 只在自己确定要归档时加。

动手:归档一个仓库,再验证它真的只读

下面每一步都是真实执行过的,输出原样贴出(仓库名用示例代替):

# ① 归档(带 --yes 跳过交互确认;不带参数则归档当前目录所在的仓库)
gh repo archive <owner>/<repo> --yes

# ② 看 API 眼里的状态:archived 变 true,别的都没动
gh api repos/<owner>/<repo> --jq \
  '{archived, disabled, visibility, has_issues, pushed_at, updated_at}'
# {"archived":true,"disabled":false,"visibility":"private","has_issues":true,
#  "pushed_at":"2026-09-23T13:21:47Z","updated_at":"2026-10-03T14:57:58Z"}
#   ↑ pushed_at 停在最后一次真实推送;updated_at 变成归档这个动作的时间

# ③ 归档后再推一次(重点:把远端拒绝你的原话记住)
git push origin main
# remote: This repository was archived so it is read-only.
# fatal: unable to access 'https://github.com/<owner>/<repo>.git/':
#        The requested URL returned error: 403

# ④ 走 API 改一个文件,换来另一句同样意思的拒绝
gh api repos/<owner>/<repo>/contents/x.txt -X PUT -f message=t -f content=aGk=
# gh: Repository was archived so is read-only. (HTTP 403)

# ⑤ 解归档,再推一次
gh repo unarchive <owner>/<repo> --yes
git push origin main          # 成功 —— 只读随解归档立即消失

顺手验证第 3 条(读不受影响):仓库处于归档状态时, git ls-remote https://github.com/<owner>/<repo> 仍然正常返回 refs, 一个字节都没少 —— 归档拦的是写,不是读。

一次归档一批

# 把不再维护的仓库列出来,逐个归档(先干跑一遍把名单看清楚)
for r in old-tool-a old-tool-b old-tool-c; do
  echo "will archive: Zzz210s/$r"
done
for r in old-tool-a old-tool-b old-tool-c; do
  gh repo archive "Zzz210s/$r" --yes
done
# 事后核对哪些还开着:gh repo list --archived 或 gh repo list(默认不含归档)
gh repo list Zzz210s --archived --limit 50

归档 / 删除 / 转私有:怎么选

动作它改变了什么什么时候选它
归档对所有人只读;可逆;内容、历史、URL 全留不再维护,但要留档可查(旧配置仓库、结题的项目、被取代的工具)
删除仓库连同 issues / PR / 历史一起消失;不可逆确实不该存在(误传的密钥、空壳实验),且确认没有引用价值
转私有可见性变化;依然可写只是不想公开,仍然要继续开发
什么都不动没有变化 —— 但半年后会有人以为它还在维护确实还会回来改

归档不挡接手:别人仍可 fork 走继续做,但那是一个新仓库, 不会解除原仓库的只读 —— "归档 + 别人 fork"正是开源项目停止维护时的常见交棒方式。

两个容易踩的坑:归档不等于免费——按旧版"按仓库计费"的计划, 归档仓库仍会照常收费(官方文档明确提示);另外归档整个组织是另一个操作, 一次把所有仓库封存,别顺手做成那个。

自测(选项一样长,别从长度上猜)

1. 归档一个仓库之后,下面哪件事仍然可以做?

对。归档只拦写入:issues、协作者增删、标签修改都被冻结,但 clone / fetch / ls-remote 一直可用 —— 留档的价值正来自这里。

2. 归档之后再想改一处文档,正确做法是?

对。归档是可逆开关:先解归档恢复可写,改完再归档回去。命令、界面、REST 三条路都行,强行写入只会拿到 read-only 的 403。

3. 归档和删除最本质的区别是?

对。归档不改变可见性、不删内容,还是一个可逆的开关;删除才是那个不可逆、连历史一起带走的选择。