Git 提交 GitHub 完整实战指南
本文档面向希望参与开源项目贡献的开发者,涵盖从 Fork 仓库到提交 Pull Request 的完整 Git 操作流程。 适用系统: Windows / macOS / Linux 适用平台: 本地开发环境 / 云服务器
目录
1. 基础配置
首次使用 Git 前,必须配置用户名和邮箱,这些信息会嵌入到每一次提交记录中。
1.1 配置用户名和邮箱(全局)
git config --global user.name "你的GitHub用户名"
git config --global user.email "你的GitHub注册邮箱"1.2 配置默认编辑器(可选)
git config --global core.editor "vim"也可设置为 nano、code(VS Code)等你习惯的编辑器。
1.3 查看当前配置
git config --list
git config user.name
git config user.email2. Fork 仓库与克隆
2.1 在 GitHub 网页上 Fork 仓库
- 打开目标仓库页面
- 点击右上角 Fork 按钮
- 选择自己的账号,等待 Fork 完成
- 此时你的账号下会生成一个同名仓库
2.2 克隆自己 Fork 的仓库到本地
# 使用 HTTPS(无需配置密钥,浏览器登录即可)git clone https://github.com/你的用户名/仓库名.git首次克隆时若提示确认主机指纹,输入 yes 回车即可。
2.3 进入项目目录
cd 仓库名3. 已 Fork 但未 git init 的提交流程
适用场景: 已在 GitHub Fork 了仓库,在本地修改了代码,但项目目录还没有执行过 git init。
以下以 Firefly 主题为例:
| 仓库类型 | 地址 |
|---|---|
| 你的 Fork | https://github.com/wuziyue840/Firefly |
| 作者原仓库 | https://github.com/CuteLeaf/Firefly |
3.1 进入项目目录并初始化 Git
cd /path/to/你的项目文件夹
git init3.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 -v3.3 先把本地修改提交(关键步骤)
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 -rFirefly 默认分支是 master,不是 main,merge 时请注意分支名。
# 合并作者仓库代码到本地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 状态下不能使用 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.gitgit push -u origin master4. 分支操作
4.1 查看分支
# 查看本地所有分支,当前分支前有 * 号git branch
# 查看远程所有分支git branch -r
# 查看本地和远程所有分支git branch -a4.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 :分支名5. 上游管理
5.1 添加上游仓库(原仓库)
# 查看当前远程仓库git remote -v
# 添加原仓库为 upstreamgit 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
# 或选择 rebase 方式git rebase upstream/master
# 将更新推送到自己的 Forkgit push origin master5.3 删除上游仓库
git remote remove upstream5.4 修改远程仓库地址
# 修改 origin 地址git remote set-url origin https://github.com/wuziyue840/Firefly.git
# 修改 upstream 地址git remote set-url upstream https://github.com/CuteLeaf/Firefly.git6. 日常开发提交流程
6.1 开始新功能/修复前
# 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 开发过程中
# 查看文件修改状态git status
# 查看具体修改内容git diff
# 添加文件到暂存区git add 文件名
# 或添加所有修改git add .
# 提交更改git commit -m "feat: 做了什么修改"
# 多次提交后查看提交历史git log --oneline6.3 提交到远程仓库(自己的 Fork)
# 首次推送新分支到远程(建立追踪关系)git push -u origin 分支名
# 后续推送(已建立追踪后)git push
# 强制推送(慎用!会覆盖远程历史)git push --force
# 或简写git push -f--force 会重写远程历史,团队协作分支上绝对不要使用,仅限个人 feature 分支且确认无他人基于该分支开发时方可使用。
6.4 修改最后一次提交
# 修改提交信息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:确保代码质量
git status
git log --oneline步骤 2:推送到自己的 Fork
git push origin feature/你的分支名步骤 3:在 GitHub 网页上操作
- 打开你 Fork 的仓库页面:
https://github.com/wuziyue840/Firefly - 页面顶部会出现黄色提示条:
“This branch is X commits ahead of CuteLeaf/Firefly
” 点击 Contribute → Open pull request - 如果没有自动提示:
- 点击 Pull requests 标签
- 点击 New pull request
- 确认对比设置:
- base repository:
CuteLeaf/Firefly - base:
master - head repository:
wuziyue840/Firefly - compare:
master
- base repository:
- 填写 PR 信息:
- Title:简洁描述修改,例如
feat: 添加项目功能 - Description:详细说明修改原因、做了什么、如何测试
- Title:简洁描述修改,例如
- 页面底部选择:
- 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 Test1. 拉取本分支代码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. 常见问题与解决
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-hash8.10 误操作后想回退
# 查看操作历史git reflog
# 撤销提交但保留修改git reset --soft HEAD~1
# 撤销提交并丢弃修改(慎用)git reset --hard HEAD~1git reset --hard 会永久丢弃未提交的修改,执行前请确认。
8.11 忽略文件不生效
git rm -r --cached .
git add .
git commit -m "更新 .gitignore"9. 常用命令速查表
配置
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 # 拉取并使用 rebasegit rebase master # 将当前分支变基到 master附录:Fork 工作流图解
文档版本: 2026-08-09 适用系统: Windows / macOS / Linux 适用平台: 本地开发环境 / 云服务器
支持与分享
如果这篇文章对你有帮助,欢迎分享给更多人或打赏支持!













