Git教程

——如何参与开源项目合作 - 从 Fork 到 PR 全流程指南

适合 Git 新手 | 适用于 Gitee 平台 | 附带避坑指南

无论你是想为开源项目贡献代码、修复错别字，还是学习 Git 协作流程，本指南将带你一步步完成你的第一次开源贡献！

总体流程概览

注册并登录 Gitee 账号
Fork 项目到你的个人仓库
克隆 Fork 后的仓库到本地
配置 Git 身份信息
拉取最新代码 → 修改文件 → 提交 → 推送
在 Gitee 上发起 Pull Request（PR）
等待项目维护者审核并合并

详细操作步骤

第一步：注册 & 登录 Gitee

访问 https://gitee.com
注册账号并登录
确保邮箱已验证（用于 Git 提交身份识别）

第二步：Fork 项目

📌 你在做什么：复制一份别人的项目到你的账号下，这样你才能自由修改。

打开你想贡献的项目页面（例如：https://gitee.com/funokegd/www.kps-project.cn）
点击右上角的 「Fork」按钮
等待 Fork 完成（通常几秒）
此时你会拥有一个属于你自己的副本，URL 会变成：
https://gitee.com/你的用户名/www.kps-project.cn

✅ 小贴士：Fork 后，你可以在自己的仓库里随意修改，不会影响原项目。

第三步：克隆项目到本地

📌 你在做什么：把你在 Gitee 上的 Fork 仓库“下载”到电脑，开始本地编辑。

复制你 Fork 后仓库的 HTTPS 地址（点击「克隆/下载」→ 复制 HTTPS 链接）
打开 Git Bash（Windows）或终端（Mac/Linux）
运行：

git clone https://gitee.com/你的用户名/www.kps-project.cn.git
cd www.kps-project.cn

⚠️ 重要提醒：
请将项目克隆到普通本地文件夹，不要放在百度网盘、OneDrive、iCloud 等自动同步文件夹中！
否则 Git 状态会被干扰，导致提交失败或冲突！

推荐路径：

Windows: C:\Projects\kps-project
Mac/Linux: ~/projects/kps-project

第四步：设置 Git 身份（只需一次）

📌 你在做什么：告诉 Git 你是谁，这样你的贡献才会被正确记录到项目历史中。

在 Git Bash 中运行：

git config --global user.email "你的Gitee注册邮箱@example.com"
git config --global user.name "你的Gitee用户名"

✅ 必须使用 Gitee 注册邮箱和用户名，否则提交可能不被识别！

第五步：开始贡献 —— 修改 & 提交

📌 核心原则：改之前 pull → 改完后 commit → 提交前再 pull → 最后 push

1. 拉取最新代码（避免冲突）

git pull origin master

❗ 如果报错：fatal: refusing to merge unrelated histories
原因：本地与远程历史不相关（常见于首次克隆后直接 pull）
解决：

git pull origin master --allow-unrelated-histories

然后会进入编辑器：

按 i 进入编辑模式
（可选）修改第一行黄色文字，如：“合并远程主分支”
按 Esc → 输入 :wq → 回车保存退出

2. 修改文件

用任意编辑器（VS Code、记事本等）打开项目文件夹，进行修改：

修复错别字
添加笔记
优化文档格式
修改网页内容等

✅ 修改前建议先备份，或使用 VS Code 等支持 Git 的编辑器，方便查看改动。

3. 添加修改到暂存区

git add .

💡 . 表示添加当前目录下所有改动，别漏掉！

4. 再次拉取最新代码（提交前最后检查）

git pull origin master

✅ 如果有冲突，Git 会提示你手动解决（新手可先撤销修改，重新开始）

5. 提交修改（生成版本快照）

git commit -m "修复了XX页面错别字 / 添加了XX课程笔记 / 更新了README格式"

✍️ 提交信息要具体清晰！例如：

✅ 好：“修复首页‘电压’错写为‘店压’”

❌ 差：“改了一下”

6. 推送到你的远程仓库

git push origin master

🔐 如果是第一次推送，会弹出登录框，输入你的 Gitee 账号密码（或 Token）即可。
以后无需重复输入（Git 会记住凭证）。

第六步：发起 Pull Request（PR）

📌 你在做什么：请求原项目作者将你的修改合并到他们的主仓库中。

打开你的 Gitee 仓库页面（https://gitee.com/你的用户名/www.kps-project.cn）
点击绿色按钮 「Pull Request」
确认：
- 源分支：你的用户名:master
- 目标分支：原作者用户名:master
填写 PR 标题和描述：
- 标题：简洁说明改动（如：“修复错别字”）
- 描述：详细说明修改内容、原因、影响范围
点击 「创建 Pull Request」

🎉 恭喜！你的 PR 已提交，等待项目维护者审核！

第七步：等待审核 & 合并

项目维护者会收到通知，审查你的代码
可能会要求你修改、补充说明或添加测试
审核通过后，维护者会点击 「合并」，你的代码就正式进入主项目！

✅ 你可以在原项目页面的「Pull Requests」标签页查看状态。

🔄 后续贡献流程（第二次及以后）

以后你只需重复以下步骤：

# 1. 拉取最新代码
git pull origin master

# 2. 修改文件...

# 3. 添加修改
git add .

# 4. 再次拉取（确保无冲突）
git pull origin master

# 5. 提交
git commit -m "你的修改说明"

# 6. 推送
git push origin master

# 7. 去 Gitee 发起新的 PR（如果还没自动关联）

✅ 养成习惯：改之前 pull，提交前再 pull，push 前确认无冲突！

🛑 常见错误 & 避坑指南

问题	原因	解决方案
`fatal: refusing to merge unrelated histories`	本地与远程无共同历史	加 `--allow-unrelated-histories` 参数
提交后 Gitee 不显示贡献者	Git 身份未正确设置	重新设置 `user.name` 和 `user.email`
文件修改后 Git 不识别	在同步文件夹中操作	移动项目到普通文件夹再操作
PR 提交后无反应	没有正确选择目标分支	检查源/目标分支是否正确指向原项目

🖥️ 项目部署说明（仅限管理员）

普通贡献者无需操作此部分

此处以在 Fedora + Nginx 服务器上部署最新代码为例：

# 进入网站根目录
cd /usr/share/nginx/html

# 清空旧内容（可选）
rm -rf *

# 克隆最新项目
git clone https://gitee.com/funokegd/www.kps-project.cn.git

# 复制文件到当前目录
cp -rf www.kps-project.cn/build/* ./

# 重载 Nginx 生效
sudo systemctl reload nginx

🔐 确保目录权限正确，Nginx 可读取文件。

📬 遇到问题怎么办？

提交 Issue 到项目仓库
在 PR 下留言询问
联系项目维护者：@FunokeGD

❤️ 开源协议

本项目采用 ISC License —— 自由使用、修改、分发，只需保留原作者声明。

🌱 知识因分享而强大，学习因协作而高效。
你的每一次 PR，都是开源世界的一颗星星。
加入我们，一起打造属于电气学子的“知识发电站”！

✅ 现在，就去 Fork 一个项目，迈出你的开源第一步吧！

📌 附：流程图速记

Fork → Clone → Config → Pull → Edit → Add → Pull → Commit → Push → PR → Merge

祝你贡献顺利，开源快乐！ 🎉

总体流程概览​

详细操作步骤​

第一步：注册 & 登录 Gitee​

第二步：Fork 项目​

第三步：克隆项目到本地​

第四步：设置 Git 身份（只需一次）​

第五步：开始贡献 —— 修改 & 提交​

1. 拉取最新代码（避免冲突）​

2. 修改文件​

3. 添加修改到暂存区​

4. 再次拉取最新代码（提交前最后检查）​

5. 提交修改（生成版本快照）​

6. 推送到你的远程仓库​

第六步：发起 Pull Request（PR）​

第七步：等待审核 & 合并​

🔄 后续贡献流程（第二次及以后）​

🛑 常见错误 & 避坑指南​

🖥️ 项目部署说明（仅限管理员）​

📬 遇到问题怎么办？​

❤️ 开源协议​