简介
本手册面向日常开发场景，从零开始，按操作顺序组织。所有示例使用 .py 文件，注释简洁明了。
适用环境：Windows 10/11 + Git Bash（推荐）或 macOS/Linux 终端。
一、准备工作
1、安装 Git
-
Windows 用户：安装 Git for Windows（自带 Git Bash）
-
验证安装：
git --version
2、配置用户名和邮箱（首次使用需设置）
git config --global user.name "你的名字"
git config --global user.email "your_email@example.com"二、连接 GitHub（两种方式选其一）
方式 A：使用 SSH（推荐，更安全）
# 1. 生成 SSH 密钥（一路回车用默认路径）
ssh-keygen -t ed25519 -C "your_email@example.com"
# 2. 启动代理并添加私钥
eval $(ssh-agent)
ssh-add ~/.ssh/id_ed25519
# 3. 复制公钥内容
cat ~/.ssh/id_ed25519.pub
# 4. 登录 GitHub → Settings → SSH and GPG keys → New SSH key
# 粘贴上一步输出的整段内容，保存
# 5. 测试连接
ssh -T git@github.com方式 B：使用 Token（HTTPS 方式）
# 1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
# 创建新 token，勾选 `repo` 权限，生成后复制（只显示一次！）
# 2. 克隆时使用 token（替换 YOUR_TOKEN 和 YOUR_USERNAME）
git clone https://YOUR_TOKEN@github.com/YOUR_USERNAME/your-repo.git三、克隆与初始化
克隆已有仓库
# SSH 方式（推荐）
git clone git@github.com:用户名/仓库名.git
# HTTPS 方式（用 token）
git clone https://ghp_xxx@github.com/用户名/仓库名.git初始化新项目（本地新建）
mkdir my-project
cd my-project
git init
echo "# 我的项目" > README.md
git add README.md
git commit -m "初始提交"
# 然后在 GitHub 新建空仓库，按提示关联远程
git remote add origin git@github.com:用户名/仓库名.git
git push -u origin main四、日常开发流程（核心）
假设你要修复两个 bug：
-
auth/login.py：修复用户邮箱为空时崩溃
-
profile/avatar.py：修复头像上传失败
步骤 1：创建修复分支
git checkout main # 切到主干
git pull origin main # 拉取最新代码
git checkout -b fix # 创建并切换到 fix 分支步骤 2：修改代码（示例）
文件：auth/login.py
def login(email, password):
# 修复：邮箱为空时直接返回错误，避免后续崩溃
if not email:
return {"error": "邮箱不能为空"}
# ... 其他逻辑文件：profile/avatar.py
def upload_avatar(file):
# 修复：网络超时时自动重试一次
try:
send_to_server(file)
except TimeoutError:
send_to_server(file) # 重试步骤 3：分别提交不同文件（重要！）
# 查看修改了哪些文件
git status
# 提交第一个修复（只包含 login.py）
git add auth/login.py
git commit -m "fix(auth): 邮箱为空时返回错误提示"
# 提交第二个修复（只包含 avatar.py）
git add profile/avatar.py
git commit -m "fix(profile): 头像上传超时自动重试"这样 GitHub 上会显示两个独立提交，清晰对应各自功能。
步骤 4：推送分支
# 首次推送，设置上游（加 -u）
git push -u origin fix步骤 5：创建 Pull Request（PR）
- 打开 GitHub 仓库页面
- 点击 Compare & pull request
- 确认 base 分支是 main，compare 是 fix
- 填写描述："修复登录邮箱校验和头像上传问题"
- 点击 Create pull request
合并后，建议点击 Delete branch 删除 fix 分支。
五、常用辅助操作
查看状态与差异
# 查看哪些文件被修改
git status
# 查看具体改了什么（未暂存）
git diff
# 查看已暂存的改动
git diff --cached
# 查看某文件的改动
git diff auth/login.py撤销操作
# 撤销工作区修改（恢复成上次提交的样子）
git restore auth/login.py
# 撤销已暂存但未提交的文件
git restore --staged auth/login.py
# 撤销最近一次提交（保留代码在工作区）
git reset --soft HEAD~1同步主干更新（避免 PR 冲突）
git checkout main
git pull origin main
git checkout fix
git rebase main # 把 fix 的提交"接"到 main 最新后面
git push --force-with-lease origin fix # 强制推送（安全版）解决冲突（当 rebase 或 merge 出现冲突时）
-
打开冲突文件，找到：
<<<<<<< HEAD 你的代码 ======= 别人的代码 >>>>>>> commit-id -
手动编辑，保留正确部分，删除
<<<<<<<等标记 -
标记解决：
git add 冲突文件.py git rebase --continue # 如果是 rebase # 或 git commit # 如果是 merge
六、版本发布（打标签）
发布 v1.0
git checkout main
git pull origin main
# 提交最终代码
git add .
git commit -m "feat: release v1.0"
# 打带注释的标签（正式版本推荐）
git tag -a v1.0 -m "正式发布 v1.0"
# 推送代码和标签
git push origin main
git push origin v1.0在旧版本上修紧急 bug（如 v1.0 → v1.1）
# 切到 v1.0（进入"分离头指针"状态）
git checkout v1.0
# 修改 bug（例如 auth/login.py）
# ... 编辑代码 ...
git add auth/login.py
git commit -m "fix: 修复 v1.0 登录安全漏洞"
# 打新标签
git tag -a v1.1 -m "v1.0 紧急修复版"
# 切回 main 并同步修复
git switch main
git cherry-pick <刚才的commit-id> # 把修复"移植"到 main
# 推送
git push origin main
git push origin v1.1七、清理与查看
删除文件/文件夹
# 删除文件
git rm config.json
git commit -m "删除配置文件"
git push origin main
# 删除文件夹
git rm -r old_module/
git commit -m "移除旧模块"
git push origin main查看历史
# 简洁日志
git log --oneline
# 查看谁改了某行代码
git blame auth/login.py清理临时文件
# 预览要删的文件
git clean -n
# 删除未跟踪的文件（如 .pyc、日志等）
git clean -fd八、常见问题速查
| 问题 | 命令 |
|---|---|
忘记加 -u？ |
下次 git push -u origin 分支名 补上即可 |
| 提交信息写错了？ | git commit --amend -m "新信息"（未推送时） |
| 想临时保存修改去切分支？ | git stash → 切分支 → git stash pop |
| 查看远程地址？ | git remote -v |
| 强制推送？ | git push --force-with-lease（比 --force 安全） |