Git 提交 GitHub 完整实战指南

3249 字
16 分钟
Git 提交 GitHub 完整实战指南

本文档面向希望参与开源项目贡献的开发者,涵盖从 Fork 仓库到提交 Pull Request 的完整 Git 操作流程。 适用系统: Windows / macOS / Linux 适用平台: 本地开发环境 / 云服务器

目录#

  1. 基础配置
  2. Fork 仓库与克隆
  3. 已 Fork 但未 git init 的提交流程
  4. 分支操作
  5. 上游管理
  6. 日常开发提交流程
  7. Pull Request 提交指南
  8. 常见问题与解决
  9. 常用命令速查表

1. 基础配置#

首次使用 Git 前,必须配置用户名和邮箱,这些信息会嵌入到每一次提交记录中。

1.1 配置用户名和邮箱(全局)#

Terminal window
git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub注册邮箱"

1.2 配置默认编辑器(可选)#

Terminal window
git config --global core.editor "vim"
提示

也可设置为 nanocode(VS Code)等你习惯的编辑器。

1.3 查看当前配置#

Terminal window
git config --list
git config user.name
git config user.email

2. Fork 仓库与克隆#

2.1 在 GitHub 网页上 Fork 仓库#

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

2.2 克隆自己 Fork 的仓库到本地#

Terminal window
# 使用 HTTPS(无需配置密钥,浏览器登录即可)
git clone https://github.com/你的用户名/仓库名.git
重要

首次克隆时若提示确认主机指纹,输入 yes 回车即可。

2.3 进入项目目录#

Terminal window
cd 仓库名

3. 已 Fork 但未 git init 的提交流程#

提示

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

以下以 Firefly 主题为例:

仓库类型地址
你的 Forkhttps://github.com/wuziyue840/Firefly
作者原仓库https://github.com/CuteLeaf/Firefly

3.1 进入项目目录并初始化 Git#

Terminal window
cd /path/to/你的项目文件夹
git init

3.2 关联远程仓库(全部使用 HTTPS)#

Terminal window
# 添加你自己的 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 先把本地修改提交(关键步骤)#

Terminal window
git add .
git commit -m "save: 本地修改备份"
警告

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

3.4 拉取作者仓库代码并合并#

Terminal window
# 获取作者仓库的所有分支信息
git fetch upstream
# 查看作者仓库有哪些分支
git branch -r
重要

Firefly 默认分支是 master,不是 main,merge 时请注意分支名。

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

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

3.5 处理合并冲突#

如果提示冲突,文件里会出现类似标记:

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

快速解决(全部保留自己的版本):

Terminal window
git checkout --ours .
git add .
git commit -m "feat: 添加项目功能"
警告

merge 状态下不能使用 git commit --amend!会报错: fatal: You are in the middle of a merge -- cannot amend.

如需单独处理某个文件:

Terminal window
# 保留作者版本
git checkout --theirs 文件名
# 保留自己版本
git checkout --ours 文件名

3.6 推送到你的 Fork 仓库#

Terminal window
# 首次推送
git push -u origin master

如果之前用了 SSH,需要改成 HTTPS:

Terminal window
# 方法一(推荐)
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
Terminal window
git push -u origin master

4. 分支操作#

4.1 查看分支#

Terminal window
# 查看本地所有分支,当前分支前有 * 号
git branch
# 查看远程所有分支
git branch -r
# 查看本地和远程所有分支
git branch -a

4.2 创建分支#

Terminal window
# 创建新分支(不切换)
git branch 新分支名
# 创建并立即切换到新分支(最常用)
git checkout -b 新分支名
# Git 2.23+ 版本推荐语法
git switch -c 新分支名
# 基于远程分支创建本地分支
git checkout -b 新分支名 origin/远程分支名

4.3 切换分支#

Terminal window
# 切换到已有分支
git checkout 分支名
# Git 2.23+ 版本推荐语法
git switch 分支名
# 切换到上一个分支
git checkout -

4.4 重命名分支#

Terminal window
# 重命名当前分支
git branch -m 新分支名
# 重命名指定分支
git branch -m 旧分支名 新分支名

4.5 删除分支#

Terminal window
# 删除已合并的本地分支
git branch -d 分支名
# 强制删除本地分支(无论是否合并)
git branch -D 分支名
# 删除远程分支
git push origin --delete 分支名
# 或简写
git push origin :分支名

5. 上游管理#

5.1 添加上游仓库(原仓库)#

Terminal window
# 查看当前远程仓库
git remote -v
# 添加原仓库为 upstream
git remote add upstream https://github.com/CuteLeaf/Firefly.git
# 再次查看确认
git remote -v

确认输出中应同时显示 originupstream 两个远程地址。

5.2 从上游仓库同步最新代码#

Terminal window
# 拉取上游仓库的最新代码(不合并)
git fetch upstream
# 切换到主分支(Firefly 是 master)
git checkout master
# 将上游主分支合并到本地主分支
git merge upstream/master
# 或选择 rebase 方式
git rebase upstream/master
# 将更新推送到自己的 Fork
git push origin master

5.3 删除上游仓库#

Terminal window
git remote remove upstream

5.4 修改远程仓库地址#

Terminal window
# 修改 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. 日常开发提交流程#

6.1 开始新功能/修复前#

Terminal window
# 1. 确保本地主分支是最新的
git checkout master
git fetch upstream
git merge upstream/master
git push origin master
# 2. 基于最新主分支创建功能分支
git checkout -b feature/功能描述
# 或修复分支
git checkout -b fix/bug描述

6.2 开发过程中#

Terminal window
# 查看文件修改状态
git status
# 查看具体修改内容
git diff
# 添加文件到暂存区
git add 文件名
# 或添加所有修改
git add .
# 提交更改
git commit -m "feat: 做了什么修改"
# 多次提交后查看提交历史
git log --oneline

6.3 提交到远程仓库(自己的 Fork)#

Terminal window
# 首次推送新分支到远程(建立追踪关系)
git push -u origin 分支名
# 后续推送(已建立追踪后)
git push
# 强制推送(慎用!会覆盖远程历史)
git push --force
# 或简写
git push -f
警告

--force 会重写远程历史,团队协作分支上绝对不要使用,仅限个人 feature 分支且确认无他人基于该分支开发时方可使用。

6.4 修改最后一次提交#

Terminal window
# 修改提交信息
git commit --amend -m "新的提交说明"
# 添加漏掉的文件到上一次提交
git add 漏掉的文件
git commit --amend --no-edit
重要

如果已经 push 到远程,amend 后需要强制推送: git push --force-with-lease


7. Pull Request 提交指南#

7.1 为什么仓库主人能看到你的修改?#

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

7.2 发起 Pull Request 的完整步骤#

步骤 1:确保代码质量#

Terminal window
git status
git log --oneline

步骤 2:推送到自己的 Fork#

Terminal window
git push origin feature/你的分支名

步骤 3:在 GitHub 网页上操作#

  1. 打开你 Fork 的仓库页面:https://github.com/wuziyue840/Firefly
  2. 页面顶部会出现黄色提示条:

    “This branch is X commits ahead of CuteLeaf/Firefly” 点击 ContributeOpen 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. 页面底部选择:
    • 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 被合并后的清理工作#

Terminal window
# 切换回主分支
git checkout master
# 同步上游最新代码
git fetch upstream
git merge upstream/master
git push origin master
# 删除本地功能分支
git branch -d feature/你的分支名
# 删除远程功能分支
git push origin --delete feature/你的分支名

8. 常见问题与解决#

8.1 merge 时报错 “not something we can merge”#

原因解决
分支名不对,作者仓库默认分支可能是 master 不是 maingit 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 SettingsDeveloper settingsPersonal access tokensTokens (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

手动编辑文件,保留需要的代码,删除标记行后:

Terminal window
git add 冲突文件
git commit -m "解决合并冲突"

8.9 误删了本地分支#

Terminal window
git reflog
git checkout -b 分支名 commit-hash

8.10 误操作后想回退#

Terminal window
# 查看操作历史
git reflog
# 撤销提交但保留修改
git reset --soft HEAD~1
# 撤销提交并丢弃修改(慎用)
git reset --hard HEAD~1
警告

git reset --hard 会永久丢弃未提交的修改,执行前请确认。

8.11 忽略文件不生效#

Terminal window
git rm -r --cached .
git add .
git commit -m "更新 .gitignore"

9. 常用命令速查表#

配置#

Terminal window
git config --global user.name "name"
git config --global user.email "email"
git config --list

仓库操作#

Terminal window
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

分支操作#

Terminal window
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 分支名 # 删除远程分支

提交操作#

Terminal window
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 # 图形化查看历史

冲突解决#

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

撤销操作#

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

同步操作#

Terminal window
git pull # 拉取并合并
git pull --rebase # 拉取并使用 rebase
git rebase master # 将当前分支变基到 master

附录:Fork 工作流图解#

你通过 PR 贡献代码

git push origin feature/xx

git merge upstream/master

git pull origin master

原仓库 Upstream

你的 Fork Origin

本地仓库 Local

你通过 PR 贡献代码

git push origin feature/xx

git merge upstream/master

git pull origin master

原仓库 Upstream

你的 Fork Origin

本地仓库 Local


文档版本: 2026-08-09 适用系统: Windows / macOS / Linux 适用平台: 本地开发环境 / 云服务器



支持与分享

如果这篇文章对你有帮助,欢迎分享给更多人或打赏支持!

打赏
Git 提交 GitHub 完整实战指南
https://blog.qtfyu.top/posts/git-github-complete-guide/
作者
倾听风雨
发布于
2026-08-08
许可协议
CC BY-NC-SA 4.0

评论区

Profile Image of the Author
倾听风雨
你好,我是倾听风雨,很高兴你能来到我的小家。
公告
欢迎来到我的博客!这是我的个人博客。
音乐
封面

音乐

暂未播放

0:000:00
暂无歌词
分类
标签
最新动态
站点统计
文章
11
分类
5
标签
46
总字数
14,588
运行时长
0
最后活动
0 天前
站点信息
构建平台
Local
博客版本
Firefly v6.14.5
文章许可
CC BY-NC-SA 4.0
天气预报

文章目录