实验0：希冀平台与课程仓库接入¶
本节目标
登录希冀平台，进入课程 GitLab，创建一个空项目，并把本地课程仓库配置为 upstream/origin 双远程，完成首次 push。
重要限制：只能使用 HTTP(S)
当前希冀平台的 GitLab 只支持 HTTP/HTTPS 协议访问，不要使用 SSH，也不要配置 SSH Key。后续示例中的远程地址都应以 http:// 或 https:// 开头。
如果你已经按旧版仓库接入文档做完了
旧版文档中的典型配置是：
upstream指向课程仓库https://git.ustc.edu.cn/KONC/nexos.git；origin指向旧平台上的个人私有仓库，可能是git@git.ustc.edu.cn:os2026/<你的私有仓库名>.git，也可能是对应的HTTPS地址。
如果你已经完成过旧版流程，不需要重新 clone，也不需要把实验重做一遍。你现在要做的，是在希冀 GitLab 中创建一个空项目，然后把本地仓库的 origin 改成新的希冀 HTTP 地址，再把你已有的分支重新推送过去。下面第 5.1 节给出了对应命令。
1 登录希冀平台¶
希冀平台地址：http://cscourse.ustc.edu.cn/
进入平台后，从学生入口登录。当前课程平台通常使用学号作为账号，例如 PB20110001。如果你之前已经注册过希冀平台，请使用你原来的密码；如果是首次登录，初始密码通常与账号相同。(如果无法登陆，私信助教解决)
进入课程列表后，选择对应课程进入课程平台。
首次进入课程平台后，建议先修改默认密码，并完善个人信息，避免后续登录或提交时出现问题。
2 进入课程 GitLab¶
在课程平台页面中，使用右上角入口进入 GitLab。
进入 GitLab 后，如果页面先出现登录引导，请直接使用与希冀平台相同的用户名和密码登录。
如果你之前单独修改过 GitLab 密码、结果现在忘记了，可以先点击页面里的“GitLab 密码重置”，把 GitLab 密码重新改回与平台一致，再继续后续操作。
首次进入 GitLab 时，如果页面要求补充邮箱或完成账号激活，请按提示操作。平台当前通常会同步使用希冀平台的用户名；为了便于助教核对信息，建议不要自行修改用户名。
3 在 GitLab 中创建空项目¶
成功登录 GitLab 后，再进入“新建项目”页面创建一个项目。请在页面顶部选择 “空白项目”，不要切到“从模板创建”或“导入项目”。
建议按下面的方式填写：
- 在“项目名称”中建议直接填写
nexos，这样后续命令与文档示例可以完全一致。 - “项目 URL”和“项目标识串”通常会随项目名称自动生成；如果页面已经自动填好，保持与项目名称一致即可。
- “项目描述（可选）”可以留空，不影响后续实验。
- “可见性级别”按图中所示保持为“私有”即可。
- 不要勾选“使用自述文件初始化仓库”；你本地已经有课程仓库，后面要把现有仓库直接推上来，不需要让远程仓库先自动生成
README。
一定要创建空项目
如果你勾选了“使用自述文件初始化仓库”，远程仓库会先多出一条独立历史，后续第一次 git push 很可能出现非 fast-forward 或历史无关的问题。最省事的处理方式通常是删掉这个仓库并重新创建一个空项目。
项目名不必强制叫 nexos
如果你用了其他项目名，也完全可以；但后续命令中的远程地址最后一段就不再是 nexos.git，而要改成你自己的项目名。
4 准备本地课程仓库¶
如果你已经完成了 实验0：内核编译运行与 GDB 调试 中的 git clone，那么你已经有了本地课程仓库，直接继续本节即可，不需要再克隆第二份。
如果你还没有克隆课程仓库，请先执行：
可以先看一眼当前远程配置：
第一次 clone 完成后，你通常会看到：
$ git remote -v
origin https://git.ustc.edu.cn/KONC/nexos.git (fetch)
origin https://git.ustc.edu.cn/KONC/nexos.git (push)
5 把课程仓库设为 upstream，把个人仓库设为 origin¶
先判断自己属于哪种情况
如果你只是刚从课程仓库 clone 下来，本地还只有一个 origin，并且它当前指向课程仓库，那么执行下面的 rename + add 即可。
如果你已经按旧版文档完成过仓库接入，或者已经做过实验，本地仓库通常已经同时存在 origin 和 upstream。这时不要再执行 git remote rename origin upstream，否则很可能出现 remote upstream already exists。你应该直接用 git remote set-url origin <新的希冀 HTTP 地址> 修改个人仓库地址，具体见下文第 5.1 节。
现在开始配置双远程。下面仍以项目名为 nexos 为例，但请特别注意：远程地址中的用户名部分应以你在希冀 GitLab 页面上实际看到的内容为准，它有可能并不是学号。因此，最稳妥的做法是先按下图位置复制仓库的 HTTPS 地址，再把它直接填进命令里。
如果一切正常，输出应类似于：
$ git remote -v
origin https://cscourse.ustc.edu.cn/vdir/Gitlab/PB24000000/nexos.git (fetch)
origin https://cscourse.ustc.edu.cn/vdir/Gitlab/PB24000000/nexos.git (push)
upstream https://git.ustc.edu.cn/KONC/nexos.git (fetch)
upstream https://git.ustc.edu.cn/KONC/nexos.git (push)
推荐先直接复制 GitLab 给出的 HTTP 地址
最稳妥的做法，是在你刚创建好的空项目页面中点击“克隆”，然后直接复制“使用 HTTPS 克隆”下面的地址，再把它替换到 git remote add origin ... 或 git remote set-url origin ... 命令中。
不要手动去猜 HTTP 地址，也不要想当然地把“学号”填进 URL。有些同学在希冀 GitLab 中显示的用户名并不是学号，如果手动拼接，很容易把远程地址写错；直接复制页面给出的仓库链接最可靠。
下图红框标出了需要点击和复制的位置：
如果你已经改过远程地址
如果你之前误把个人仓库加成了 upstream，或者误用了 SSH 地址，也不用重来，直接执行：
5.1 如果你已经完成了旧版仓库接入¶
如果你以前已经按旧版仓库接入文档做过“接受邀请邮件 + 配 SSH Key + 私有仓库首次提交”，那么你本地仓库大概率已经是下面这种状态：
$ git remote -v
origin git@git.ustc.edu.cn:os2026/<你的私有仓库名>.git (fetch)
origin git@git.ustc.edu.cn:os2026/<你的私有仓库名>.git (push)
upstream https://git.ustc.edu.cn/KONC/nexos.git (fetch)
upstream https://git.ustc.edu.cn/KONC/nexos.git (push)
有些同学的 origin 可能不是 SSH，而是旧平台上的 HTTPS 地址；这种情况也一样处理。关键点是：保留当前本地仓库和已有提交，只把 origin 改到希冀平台。
先在希冀 GitLab 中创建一个空项目，然后从空项目页面直接复制仓库的 HTTPS 地址，再在本地仓库执行：
确认输出变成下面这样即可：
$ git remote -v
origin https://cscourse.ustc.edu.cn/vdir/Gitlab/PB24000000/nexos.git (fetch)
origin https://cscourse.ustc.edu.cn/vdir/Gitlab/PB24000000/nexos.git (push)
upstream https://git.ustc.edu.cn/KONC/nexos.git (fetch)
upstream https://git.ustc.edu.cn/KONC/nexos.git (push)
然后把你已经做过的分支重新推送到新的 origin。
如果你目前只在 main 上有提交(具体推送方法看第六节，直接输入账号密码会报错)：
旧提交会保留
只要你是直接在原来的本地仓库里修改 origin，你之前已经完成的提交历史、README.md 测试提交和各实验分支都会继续保留。迁移时不需要重新做实验，也不需要把旧提交手动拷来拷去。
6 创建 personal access token 并完成首次推送¶
当前平台通过 HTTP/HTTPS 访问 Git 仓库时，不能直接使用登录密码。因此，在第一次 git push 之前，请先创建一个 personal access token，再用它完成认证。
6.1 创建 personal access token¶
打开课程 GitLab 的 personal access token 页面，创建一个新的令牌。
创建时，建议至少勾选以下权限：
write_repository：用于git push；read_repository：用于git pull、git fetch等只读操作。
关于令牌名称或过期时间，可以自行设置一个便于识别的名字，例如 nexos-local，（注意，access token创建后需要立即复制，后续无法再次复制token，只能重新创建）。
6.2 可选：让 Git 记住凭据¶
如果你不想每次 git push / git pull 都重新输入认证信息，可以先在本地执行：
执行后，第一次认证成功时，Git 会把凭据保存在当前用户目录下的 ~/.git-credentials 中。之后在同一台机器上通常就不需要再重复输入了。
6.3 执行首次 push¶
课程仓库当前默认分支是 main，执行：
如果终端要求输入认证信息：
- 用户名填写你的课程
GitLab用户名；它通常与希冀平台账号一致，但不保证一定是学号； - “密码”位置不要填写登录密码，而应填写刚才创建的
personal access token。
首次推送成功后，main 分支会与远程 origin/main 建立跟踪关系，后续你在该分支上就可以直接使用：
不要泄露 access token
access token 的作用接近密码。不要把它写进仓库文件、命令截图、聊天记录或提交历史中；如果你怀疑它已经泄露，应立即在 GitLab 中撤销该令牌并重新生成一个新的。
7 之后的日常使用方式¶
完成本页后，你的仓库关系应当是：
upstream：课程公共仓库，用来接收助教发布的更新；origin：你自己在希冀GitLab上创建的仓库，用来提交自己的代码。
之后的常见流程通常是：
git fetch upstream --prune
git switch <lab分支名>
git pull --rebase upstream <lab分支名>
git push origin <lab分支名>
更完整的分支管理、merge/rebase 与冲突处理说明，可继续阅读 Git 提交、分支与合并。
8 常见错误排查¶
8.1 repository not found¶
优先检查以下几项：
- 你是否已经在
GitLab中创建了对应的空项目； - 远程地址中的用户名、项目名大小写是否正确；
- 你是否误用了
SSH地址。
8.2 我已经有本地仓库了，还要不要重新 clone 自己的空项目¶
不要。你的本地仓库应该继续使用最开始 clone 下来的课程仓库，只需要修改远程配置即可。不要为了接入希冀平台再额外 clone 一份空仓库。
8.3 我误用了 SSH 地址怎么办¶
直接改回 HTTP 地址即可：
8.4 我已经按旧版文档做完了，还要重新 clone 吗¶
不用。旧版流程已经完成的同学，最常见的情况是本地仓库里已经有了正确的 upstream，只是 origin 还指向旧平台仓库。此时只需要：
- 在希冀
GitLab中创建一个空项目； - 用
git remote set-url origin <新的希冀 HTTP 地址>改掉origin； - 把
main和你已经做过的实验分支重新push到新的origin。
只要你不删本地仓库，之前的提交历史就都会保留。
8.5 HTTP Basic: Access denied¶
如果你在 git push 时看到类似下面的报错：
remote: HTTP Basic: Access denied
remote: You must use a personal access token with 'read_repository' or 'write_repository' scope for Git over HTTP.
fatal: Authentication failed
这通常说明你输入了登录密码，而不是 personal access token。处理方法是：
- 打开课程
GitLab的 personal access token 页面； - 创建一个至少带有
write_repository权限的令牌；如果你也希望后续pull/fetch使用同一个令牌，可以同时勾选read_repository； - 重新执行
git push，用户名填写GitLab用户名，“密码”位置填写新生成的令牌。
如果你之前已经把错误的登录密码保存进了 ~/.git-credentials，可以先手动删除其中 cscourse.ustc.edu.cn 对应的那一行，再重新执行 git push 完成认证。
8.6 为什么这里不使用 SSH¶
这不是因为课程仓库流程特殊，而是因为当前希冀平台上的 GitLab 不支持 SSH 方式访问仓库。因此：
- 不要使用
git@...形式的远程地址； - 不需要为本课程仓库额外配置
SSH Key； - 请统一使用页面中提供的
HTTP/HTTPS地址，并配合personal access token完成认证。
如果你误用了 SSH 地址，通常会表现为连接失败、认证失败，或者根本无法完成 clone / push。这时直接把远程地址改回 HTTP/HTTPS 即可。