====================================================================
                        Git 提交 GitHub 完整实战指南
====================================================================

倾听风雨著 2026-08-09
更多教程请去网址：https://blog.qtfyu.top/

目录
====================================================================

一、基础配置
二、Fork 仓库与克隆
三、已 Fork 但未 git init 的提交流程（实战版）
四、分支操作（创建、切换、删除）
五、上游（Upstream）管理
六、日常开发提交流程
七、Pull Request 提交指南
八、常见问题与解决
九、常用命令速查表


====================================================================
一、基础配置
====================================================================

1.1 配置用户名和邮箱（全局）
--------------------------------------
    git config --global user.name "你的GitHub用户名"
    git config --global user.email "你的GitHub注册邮箱"

1.2 配置默认编辑器（可选）
--------------------------------------
    git config --global core.editor "vim"
    # 或 nano、code 等

1.3 查看当前配置
--------------------------------------
    git config --list
    git config user.name
    git config user.email


====================================================================
二、Fork 仓库与克隆
====================================================================

2.1 在 GitHub 网页上 Fork 仓库
--------------------------------------
    1. 打开目标仓库页面
    2. 点击右上角 "Fork" 按钮
    3. 选择自己的账号，等待 Fork 完成
    4. 此时你的账号下会生成一个同名仓库

2.2 克隆自己 Fork 的仓库到本地
--------------------------------------
    # 使用 HTTPS（无需配置密钥，浏览器登录即可）
    git clone https://github.com/你的用户名/仓库名.git

2.3 进入项目目录
--------------------------------------
    cd 仓库名


====================================================================
三、已 Fork 但未 git init 的提交流程（实战版）
====================================================================

    适用场景：已在 GitHub Fork 了仓库，在本地修改了代码，
             但项目目录还没有执行过 git init。

    以 Firefly 主题为例：
    你的仓库：https://github.com/wuziyue840/Firefly
    作者仓库：https://github.com/CuteLeaf/Firefly

3.1 进入项目目录并初始化 Git
--------------------------------------
    cd /path/to/你的项目文件夹
    git init

3.2 关联远程仓库（全部使用 HTTPS）
--------------------------------------
    # 添加你自己的 Fork 仓库（origin）
    git remote add origin https://github.com/wuziyue840/Firefly.git

    # 添加作者原仓库（upstream）
    git remote add upstream https://github.com/CuteLeaf/Firefly.git

    # 确认配置
    git remote -v

3.3 先把本地修改提交（关键！避免 merge 报错）
--------------------------------------
    git add .
    git commit -m "save: 本地修改备份"

    # 如果不先 commit，后续 merge 会报错：
    # error: Untracked working tree file '.gitattributes' would be overwritten by merge.

3.4 拉取作者仓库代码并合并
--------------------------------------
    # 获取作者仓库的所有分支信息
    git fetch upstream

    # 查看作者仓库有哪些分支
    git branch -r
    # 注意：Firefly 默认分支是 master，不是 main

    # 合并作者仓库代码到本地
    git merge upstream/master --allow-unrelated-histories

    # --allow-unrelated-histories 必须加，因为本地是新仓库，
    # 和远程没有共同的历史记录。

3.5 处理合并冲突
--------------------------------------
    如果提示冲突，文件里会出现类似：

    <<<<<<< HEAD
    你本地改好的代码
    =======
    作者仓库的代码
    >>>>>>> upstream/master

    【快速解决】全部保留自己的版本：
    git checkout --ours .
    git add .
    git commit -m "feat: 添加项目功能"

    # 注意：merge 状态下不能 amend！
    # git commit --amend 会报错：
    # fatal: You are in the middle of a merge -- cannot amend.

    【如需单独处理某个文件】
    # 保留作者版本
    git checkout --theirs 文件名
    # 保留自己版本
    git checkout --ours 文件名

3.6 推送到你的 Fork 仓库
--------------------------------------
    # 首次推送
    git push -u origin master

    # 如果之前用了 SSH，改成 HTTPS：
    方法一（推荐）：
    git remote remove origin
    git remote add origin https://github.com/wuziyue840/Firefly.git
    方法二：
    git remote set-url origin https://github.com/wuziyue840/Firefly.git
    
    git push -u origin master

    # 首次连接 GitHub 会提示确认，输入 yes 回车即可


====================================================================
四、分支操作（创建、切换、删除）
====================================================================

4.1 查看分支
--------------------------------------
    # 查看本地所有分支，当前分支前有 * 号
    git branch

    # 查看远程所有分支
    git branch -r

    # 查看本地和远程所有分支
    git branch -a

4.2 创建分支
--------------------------------------
    # 创建新分支（不切换）
    git branch 新分支名

    # 创建并立即切换到新分支（最常用）
    git checkout -b 新分支名
    # 或 Git 2.23+ 版本
    git switch -c 新分支名

    # 基于远程分支创建本地分支
    git checkout -b 新分支名 origin/远程分支名

4.3 切换分支
--------------------------------------
    # 切换到已有分支
    git checkout 分支名
    # 或 Git 2.23+ 版本
    git switch 分支名

    # 切换到上一个分支
    git checkout -

4.4 重命名分支
--------------------------------------
    # 重命名当前分支
    git branch -m 新分支名

    # 重命名指定分支
    git branch -m 旧分支名 新分支名

4.5 删除分支
--------------------------------------
    # 删除已合并的本地分支
    git branch -d 分支名

    # 强制删除本地分支（无论是否合并）
    git branch -D 分支名

    # 删除远程分支
    git push origin --delete 分支名
    # 或简写
    git push origin :分支名


====================================================================
五、上游（Upstream）管理
====================================================================

5.1 添加上游仓库（原仓库）
--------------------------------------
    # 查看当前远程仓库
    git remote -v

    # 添加原仓库为 upstream
    git remote add upstream https://github.com/CuteLeaf/Firefly.git

    # 再次查看确认
    git remote -v
    # 应该显示 origin 和 upstream 两个

5.2 从上游仓库同步最新代码
--------------------------------------
    # 拉取上游仓库的最新代码（不合并）
    git fetch upstream

    # 切换到主分支（Firefly 是 master）
    git checkout master

    # 将上游主分支合并到本地主分支
    git merge upstream/master
    # 或 git rebase upstream/master

    # 将更新推送到自己的 Fork
    git push origin master

5.3 删除上游仓库（如需重新配置）
--------------------------------------
    git remote remove upstream

5.4 修改远程仓库地址
--------------------------------------
    # 修改 origin 地址
    git remote set-url origin https://github.com/wuziyue840/Firefly.git

    # 修改 upstream 地址
    git remote set-url upstream https://github.com/CuteLeaf/Firefly.git


====================================================================
六、日常开发提交流程
====================================================================

6.1 开始新功能/修复前
--------------------------------------
    # 1. 确保本地主分支是最新的
    git checkout master
    git fetch upstream
    git merge upstream/master
    git push origin master

    # 2. 基于最新主分支创建功能分支
    git checkout -b feature/功能描述
    # 或 fix/bug描述

6.2 开发过程中
--------------------------------------
    # 查看文件修改状态
    git status

    # 查看具体修改内容
    git diff

    # 添加文件到暂存区
    git add 文件名
    # 或添加所有修改
    git add .

    # 提交更改
    git commit -m "feat: 做了什么修改"

    # 多次提交后查看提交历史
    git log --oneline

6.3 提交到远程仓库（自己的 Fork）
--------------------------------------
    # 首次推送新分支到远程
    git push -u origin 分支名
    # -u 是 --set-upstream 的简写，建立追踪关系

    # 后续推送（已建立追踪后）
    git push

    # 强制推送（慎用！会覆盖远程历史）
    git push --force
    # 或 git push -f

6.4 修改最后一次提交
--------------------------------------
    # 修改提交信息
    git commit --amend -m "新的提交说明"

    # 添加漏掉的文件到上一次提交
    git add 漏掉的文件
    git commit --amend --no-edit

    # 注意：merge 状态下不能 amend！
    # 如果已经 push 到远程，amend 后需要强制推送
    git push --force-with-lease


====================================================================
七、Pull Request 提交指南
====================================================================

7.1 为什么仓库主人能看到你的修改？
--------------------------------------
    因为你 Fork 了仓库，你的 Fork 和原仓库之间建立了关联。
    当你在 GitHub 上发起 Pull Request 时，GitHub 会自动检测到
    你 Fork 中的新分支与原仓库之间的差异，并通知仓库主人。

7.2 发起 Pull Request 的完整步骤
--------------------------------------

    步骤 1：确保代码质量
    --------------------
    git status                    # 确认没有遗漏的修改
    git log --oneline             # 确认提交历史清晰

    步骤 2：推送到自己的 Fork
    --------------------
    git push origin feature/你的分支名

    步骤 3：在 GitHub 网页上操作
    --------------------
    1. 打开你 Fork 的仓库页面
       https://github.com/wuziyue840/Firefly

    2. 页面顶部会出现黄色提示条：
       "This branch is X commits ahead of CuteLeaf/Firefly:master"
       点击 "Contribute" -> "Open pull request"

    3. 如果没有自动提示：
       - 点击 "Pull requests" 标签
       - 点击 "New pull request"
       - 确认对比设置：
         base repository: CuteLeaf/Firefly
         base: master
         head repository: wuziyue840/Firefly
         compare: master

    4. 填写 PR 信息：
       - Title：简洁描述修改，例如 "feat: 添加项目功能"
       - Description：详细说明修改原因、做了什么、如何测试

    5. 页面底部选择：
       - [x] Allow edits by maintainers（允许作者修改你的 PR，建议勾选）
       - 点击 "Create pull request"（正式提交）
       - 不要点 "Create draft pull request"（草稿模式，不能合并）

    步骤 4：等待仓库主人审核
    --------------------
    - 仓库主人会收到通知邮件和 GitHub 通知
    - 可能会提出修改意见（Review）
    - 根据意见修改后，继续推送到同一分支，PR 会自动更新

7.3 PR 描述模板示例
--------------------------------------

    feat: 添加项目功能

    ## Type of change
    - [x] New feature (a non-breaking change that adds functionality)

    ## Checklist
    - [x] I have read the CONTRIBUTING document.
    - [x] I have checked to ensure that this Pull Request is not for personal changes.
    - [x] I have performed a self-review of my own code.
    - [x] My changes generate no new warnings.

    ## Related Issue
    无

    ## Changes
    - 添加了项目功能
    - 更新了相关配置文件

    ## How To Test
    1. 拉取本分支代码
    2. 运行项目查看功能是否正常

7.4 PR 被合并后的清理工作
--------------------------------------
    # 切换回主分支
    git checkout master

    # 同步上游最新代码
    git fetch upstream
    git merge upstream/master
    git push origin master

    # 删除本地功能分支
    git branch -d feature/你的分支名

    # 删除远程功能分支
    git push origin --delete feature/你的分支名


====================================================================
八、常见问题与解决
====================================================================

8.1 merge 时报错 "not something we can merge"
--------------------------------------
    原因：分支名不对，作者仓库默认分支可能是 master 不是 main
    解决：git merge upstream/master --allow-unrelated-histories

8.2 merge 时报错 "Untracked working tree file would be overwritten"
--------------------------------------
    原因：本地有未提交的文件，Git 不敢覆盖
    解决：先 git add . && git commit -m "save: 备份"，再 merge

8.3 merge 后 commit 报错 "unmerged files"
--------------------------------------
    原因：冲突文件还没标记为已解决
    解决：git checkout --ours . && git add . && git commit -m "feat: xxx"

8.4 merge 状态下不能 amend
--------------------------------------
    报错：fatal: You are in the middle of a merge -- cannot amend.
    解决：merge 状态下直接用 git commit -m "xxx"，不要加 --amend

8.5 push 时提示输入用户名密码
--------------------------------------
    原因：HTTPS 方式需要 GitHub 登录验证
    解决：输入你的 GitHub 用户名和 Personal Access Token（不是密码）
    # 如果没有 Token，去 GitHub Settings -> Developer settings ->
    # Personal access tokens -> Tokens (classic) -> Generate new token

8.6 首次连接 GitHub 提示确认指纹
--------------------------------------
    提示：Are you sure you want to continue connecting (yes/no)?
    解决：输入 yes 回车即可

8.7 push 时提示 "rejected: non-fast-forward"
--------------------------------------
    原因：远程分支有更新，本地不是最新
    解决：git pull origin 分支名，解决冲突后再次 push

8.8 合并冲突（Merge Conflict）手动解决
--------------------------------------
    文件中出现：
    <<<<<<< HEAD
    你的代码
    =======
    别人的代码
    >>>>>>> branch-name

    手动编辑文件，保留需要的代码，删除标记行后：
    git add 冲突文件
    git commit -m "解决合并冲突"

8.9 误删了本地分支
--------------------------------------
    git reflog
    git checkout -b 分支名 commit-hash

8.10 误操作后想回退
--------------------------------------
    git reflog
    git reset --soft HEAD~1      # 撤销提交保留修改
    git reset --hard HEAD~1      # 撤销提交丢弃修改（慎用）

8.11 忽略文件不生效
--------------------------------------
    git rm -r --cached .
    git add .
    git commit -m "更新 .gitignore"


====================================================================
九、常用命令速查表
====================================================================

配置
--------------------------------------
    git config --global user.name "name"
    git config --global user.email "email"
    git config --list

仓库操作
--------------------------------------
    git clone https://github.com/用户名/仓库名.git
    git remote -v
    git remote add origin https://github.com/用户名/仓库名.git
    git remote add upstream https://github.com/作者/仓库名.git
    git remote set-url origin https://github.com/用户名/仓库名.git
    git remote remove upstream
    git fetch upstream
    git merge upstream/master

分支操作
--------------------------------------
    git branch                    # 查看本地分支
    git branch -a                 # 查看所有分支
    git branch 分支名             # 创建分支
    git checkout -b 分支名        # 创建并切换
    git switch -c 分支名          # 创建并切换（新语法）
    git checkout 分支名           # 切换分支
    git switch 分支名             # 切换分支（新语法）
    git branch -d 分支名          # 删除已合并分支
    git branch -D 分支名          # 强制删除分支
    git push origin --delete 分支名  # 删除远程分支

提交操作
--------------------------------------
    git status                    # 查看状态
    git diff                      # 查看差异
    git add 文件                  # 添加文件
    git add .                     # 添加所有
    git commit -m "说明"          # 提交
    git commit --amend -m "说明"  # 修改最后一次提交
    git push origin 分支名        # 推送到远程
    git push -u origin 分支名     # 首次推送并建立追踪
    git log --oneline             # 查看提交历史
    git log --graph --oneline     # 图形化查看历史

冲突解决
--------------------------------------
    git checkout --ours .         # 全部保留自己版本
    git checkout --theirs 文件    # 单个文件保留作者版本
    git checkout --ours 文件      # 单个文件保留自己版本
    git add .                     # 标记冲突已解决

撤销操作
--------------------------------------
    git checkout -- 文件          # 撤销文件修改
    git reset HEAD 文件           # 取消暂存
    git reset --soft HEAD~1       # 撤销提交保留修改
    git reset --hard HEAD~1       # 撤销提交丢弃修改
    git reflog                    # 查看操作历史

同步操作
--------------------------------------
    git pull                      # 拉取并合并
    git pull --rebase             # 拉取并使用 rebase
    git rebase master             # 将当前分支变基到 master


====================================================================
                         附录：Fork 工作流图解
====================================================================

    原仓库 (Upstream)                    你的 Fork (Origin)
    ┌─────────────┐                      ┌─────────────┐
    │  master     │◄─────────────────────│  master     │
    │  (官方代码)  │   你通过 PR 贡献代码  │  (你的副本)  │
    └─────────────┘                      └─────────────┘
           ▲                                    │
           │                                    │
           │         Pull Request               │
           └────────────────────────────────────┘

    本地仓库 (Local)
    ┌─────────────┐
    │  master                 │◄── git pull origin master
    │                              │◄── git merge upstream/master
    │  feature/xx            │───► git push origin feature/xx
    │  (开发分支)             │
    └─────────────┘


====================================================================
                              结语
====================================================================

    掌握以上命令和流程，你就可以熟练地：
    ✓ Fork 任意开源仓库
    ✓ 在已修改但未 init 的情况下正确提交
    ✓ 处理各种 merge 冲突和报错
    ✓ 与上游仓库保持同步
    ✓ 提交 Pull Request 让仓库主人看到你的贡献

    记住核心原则：
    1. 永远在主分支保持与上游同步
    2. 每个功能/修复都创建独立分支
    3. 提交信息要清晰描述修改内容（feat:/fix:/chore:）
    4. PR 前确保代码质量和测试通过

    倾听风雨著 2026-08-09
    更多教程请去网址：https://blog.qtfyu.top/

====================================================================