（十一）建立 GitHub 仓库并连接本地项目

1. 从已有本地历史开始托管

GitHub 和 Gitea 都提供 Git 仓库托管。把本地项目放上去时，操作过程相似：先在网站创建仓库，复制克隆地址，在本地添加远程，再推送提交。本节用 GitHub 演示，VS Code 部分用 gitea.kronecker.cc 演示；两处使用同一套 Git 命令，连接的是各自网站上的仓库。

登录 GitHub，从右上角新建菜单选择 New repository，填写仓库名，例如 reading-git，再选择可见性。Public 的内容可公开访问，Private 由仓库访问权限控制；仓库名、描述、README 与代码都应该反映准备交给读者的项目内容。

本地已经有 README 和提交历史，这次在创建页让 README、.gitignore、License 都保持不初始化，取得一份空远程仓库。这样第一次推送直接把现有历史送上去。若是在 GitHub 上先创建带 README 的项目，则从 clone 开始，再往克隆目录中添加程序。新建仓库

在仓库 Code 菜单复制自己的 HTTPS 地址，下面把 YOUR_ACCOUNT 换成实际账户名：

下面的实拍使用独立的 python-notes-git-lab 仓库。空仓库先显示 Quick setup；推送后会显示文件、分支和 README，Code 菜单中也能复制 HTTPS 地址。阅读命令时使用自己创建的仓库名。

# 在 reading-git 中把地址保存为 origin；origin 是远程的名字。
git remote add origin https://github.com/YOUR_ACCOUNT/reading-git.git
git remote -v
# 第一次推送 main，同时设置它的上游分支。
git push -u origin main
git branch -vv

-u 建立本地 main 与 origin/main 的跟踪关系，之后在 main 中执行 git push、git pull 就有默认目标。origin 是约定俗成的名字，origin/main 则是本机记录的远程分支位置。

把远程仓库放在 Gitea 时，git remote add origin 后面换成该仓库页面复制的地址即可：

例如选择 Gitea 这一行，就把它的完整地址填入前面的 git remote add origin 命令。origin 是本地给这条连接起的名字，不表示 GitHub；地址才决定连接哪个网站、哪个账户下的哪个仓库。添加远程只在本地保存这条连接，第一次 git push -u origin main 才发送提交并设置分支的跟踪关系。之后的 clone、fetch、pull 和 push 也沿用本章的操作。远程连接与推送

已经存在的 origin 要改地址时，使用 git remote set-url origin 新地址；反复 remote add 不会覆盖旧配置。前面已连接 GitHub，后来想把 origin 改为 Gitea，就用 set-url 填入 Gitea 的地址，再核对并推送。git remote -v 同时列出读取与推送地址，网络报错前先核对仓库所属账户与名称。认证时使用目标网站对应的账户、令牌或 SSH 密钥。

2. HTTPS 登录与 SSH 密钥

HTTPS 推送需要认证。Git for Windows 常通过 Git Credential Manager 引导浏览器登录，VS Code 也可以通过账户入口登录 GitHub。GitHub 的 Git HTTPS 认证不再使用账户密码；需要手动凭据时，使用账号对应的令牌和凭据管理器，不把令牌写进远程 URL、脚本或 README。GitHub 认证方式

另一种方式是 SSH。公钥交给 GitHub，私钥留在本机；已经配置好可用密钥的电脑可以继续使用现有配置。需要新建密钥时，在 Git Bash 中执行下面的命令，按提示选择保存位置与口令；出现已有文件提示时，选择另一个文件名保存新密钥：

# Git Bash：生成密钥，并把它加入本次会话的 ssh-agent。
ssh-keygen -t ed25519 -C "YOUR_GITHUB_EMAIL"
eval "$(ssh-agent -s)"
# 使用默认文件名时添加该私钥；改过保存位置则填写相应路径。
ssh-add ~/.ssh/id_ed25519

把对应的 .pub 公钥内容添加到 GitHub Settings → SSH and GPG keys → New SSH key。首次连接时，对照 GitHub 官方 SSH 指纹 核对远程主机信息，然后测试：

# 成功消息会说明已通过认证、GitHub 不提供 shell；该测试本身可能以状态 1 结束。
ssh -T git@github.com
# 将当前项目改用 SSH 地址，再核对地址。
git remote set-url origin git@github.com:YOUR_ACCOUNT/reading-git.git
git remote -v

作者邮箱、浏览器登录状态与 SSH 密钥是三件不同的事：前者写进提交，后两者决定远程能否确认身份与访问权限。生成与添加 SSH 密钥、测试连接

3. 在另一目录克隆并运行

# 在保存项目的父目录运行，reading-copy 是新建的本地目录。
git clone https://github.com/YOUR_ACCOUNT/reading-git.git reading-copy
cd reading-copy
git status
git remote -v
python check_reading.py

clone 取得提交历史、建立 origin，并检出一个工作目录。它不会复制原电脑未提交的编辑，也不会重建那台电脑的 .venv。克隆第六章的完整项目后，继续执行 uv sync --locked，再运行 uv run python tools/check.py。