个人使用 GitHub 进行开发教程

先认识几个词

git pull 是拉取远程更新，Pull Request 是请求合并，两者不是同一个操作。

一、创建仓库

打开 GitHub，点击右上角的 + → New repository，填写仓库名称，例如 learn-github。

选择 Public 或 Private，勾选 README，再点击 Create repository。

勾选 README 后，仓库就有了第一条提交，方便后面克隆和创建分支。

二、Clone 到本地

在电脑的任意位置打开终端，输入

1

git clone 仓库地址

即可将项目克隆到本地

之后进入到项目文件夹对应的终端

三、修改项目内容

打开README.md后添加一波新的东西。然后执行以下命令可以查看分支、有哪些改动？改动提交到待提交区了没有？

1

git status

如果想查看具体发生了什么修改，可以执行以下命令进行查看

1

git diff

四、把文件放到暂存区

暂存区就是“这次准备提交的修改”，执行：

1

git add README.md

再次检查状态和即将提交的内容：

1
2

git status
git diff --staged

Changes to be committed 表示修改已暂存，尚未创建 Commit。

git diff 看尚未暂存的改动，git diff --staged 看已经暂存的改动。

如图所示git diff就是本次工作区文件夹的更改 和 暂存区里的结果比较

git diff —staged 就是暂存区结果 和 最新一次提交的结果进行比较

五、提交、上传分支

想要把对当前分支的修改提交到github上去，首先得存档

存档就是把待提交区的修改成品附上commit说明后存入档，算作一次提交

1

git commit -m "更新了README，新增了关于xxxxx的内容"

提交后，可以通过以下命令查看提交记录，-5就是之查看5条记录

1

git log --oneline -5

然后就是通过以下命令将本次提交上传到github官网上去

1
2
3
4
5
6
7

git push -u origin main

其中：
- push：上传本地提交。
- origin：克隆下来的 GitHub 仓库简称。
- main：要上传的分支。
- -u：记住本地分支和远程分支的对应关系。

六、创建自己的分支

分支让新功能和稳定版本分开，开发完成后再合并回 main。

1
2

main                       稳定版本
└─ feature/add-study-notes  新功能

1
2

git switch -c feature/add-study-notes
git branch

git switch -c 同时创建并切换分支，git branch 前面的 * 表示当前分支。

新分支刚创建时和主分支指向同一条提交；创建新的 Commit 后，两条分支才会出现不同内容。

七、在功能分支开发并上传

创建新文件或修改，写几条学习记录并保存：

检查、暂存、提交，再上传功能分支：

1
2
3
4

git status
git add .
git commit -m "新分支第一次提交的描述"
git push -u origin feature/add-study-notes

推送功能分支不等于合并主分支，此时 GitHub 的 main 仍然没有这次修改。

提交后可以切换分支观察文件变化：

1
2

git switch main
git switch feature/add-study-notes

本例中，新的修改在主分支消失、在功能分支出现，因为它只提交在功能分支中。

如图所示如果在新分支和主分支都进行了提交，就会进行分叉。通过log命令查看提交历史

1
2
3
4
5
6
7
8

#查看当前分支的一条线提交历史
git log --oneline --decorate -10

#查看所有分支的一条线提交历史
git log --oneline --decorate --all

#查看图形化的分叉式的提交历史
git log --oneline --graph --decorate --all

下一步有两种选择：第八节在本地合并，第九节在 GitHub 上用 PR 合并；练习同一个功能时选一种即可。

八、在本地合并分支

先切换到接收修改的 main，更新后再合并功能分支：

1
2

git switch main
git merge feature/add-study-notes

git merge 合并到当前分支，所以要先切换到 main，不能把方向弄反。

如果显示 Fast-forward，表示主分支只需向前移动，就能包含功能分支的提交。

如果两个分支都产生了新提交，Git 可能创建一个 Merge Commit，也可能要求先解决冲突。

完成合并后，检查文件、运行项目需要的测试，再上传主分支：

1
2
3

git status
git log --oneline --decorate --graph --all -10
git push origin main

本地 Merge 不会自动更新 GitHub，需要再执行 Push。合并规则参见 Git 合并说明。

九、使用 Pull Request 合并分支

PR 是“请把我的功能分支合并进主分支”，它会保留修改说明、讨论和检查记录。

即使只有一个账号，也可以自己创建 PR、检查修改并合并；自己的 PR 不能给自己提交 Approve 审查。

本节假设第七节的功能分支已经推送，但还没有按第八节合并。

创建 PR

打开 GitHub 仓库，点击 Compare & pull request；没有提示时，进入 Pull requests → New pull request。

确认合并方向：

1

base: main  ←  compare: feature/add-study-notes

base 接收修改，compare 提供修改，不要选反。

填写标题和说明，再点击 Create pull request；还没写完时，可以创建 Draft PR。

说明写清两件事即可：改了什么，以及检查了什么；没运行测试就不要写“测试通过”。

检查 PR

重点检查有没有误删文件、提交敏感信息，以及本次修改是否符合目标。

PR 创建后还可以继续修改同一个功能分支，Commit、Push 后，PR 会自动更新，不需要重新创建。

1
2
3
4

git switch feature/add-study-notes
git add notes.md
git commit -m "docs: 补充学习笔记"
git push

上面的命令在继续编辑并保存 notes.md 后执行。

Merge PR 是什么意思

Merge PR 就是接受这个 PR，把修改合并到选定的目标分支。

确认修改正确、必要检查通过且没有未解决冲突，再点击 Merge pull request → Confirm merge。

按钮不能点击时，先看页面提示，可能需要解决冲突、等待检查或满足分支保护规则。

刚开始可以选择仓库允许的普通 Merge，不必同时练习所有方式。

Close pull request 只是关闭请求，没有把修改合并到主分支。

PR 操作参见 GitHub 创建 Pull Request。

十、合并后同步并清理分支

GitHub 上完成合并后，本地 main 还没自动更新，需要拉取：

1
2

git switch main
git pull --ff-only origin main

确认文件和提交已经进入主分支，再删除已完成的本地功能分支：

1

git branch -d feature/add-study-notes

远程分支可以在已合并的 PR 页面点击 Delete branch，也可以执行：

1
2

git push origin --delete feature/add-study-notes
git fetch --prune

远程分支已经通过网页删除时，不用再执行远程删除命令，只需 git fetch --prune 清理本地旧记录。

git branch -d 删除本地分支，不会删除 GitHub 分支；删除分支也不会删除已经合并进主分支的文件。

Squash 或 Rebase 合并后，-d 可能仍提示未合并；先核对 PR 和主分支内容，不要为了消除提示直接强制删除。

十一、合并冲突怎么处理

冲突表示两边修改重叠，Git 无法判断该保留哪一种内容，需要你决定。

处理前先 Commit 或 Stash 保存自己的改动，保证工作区干净，再在尚未合并的功能分支中整合最新主分支：

1
2
3

git switch feature/add-study-notes
git fetch origin
git merge origin/main

发生冲突时，git status 会列出文件，里面可能出现这些标记：

1
2
3
4
5

<<<<<<< HEAD
当前功能分支的内容
=======
主分支的内容
>>>>>>> origin/main

编辑冲突文件，保留需要的最终内容，并删除三种冲突标记。

例如冲突文件是 notes.md，解决后执行：

1
2
3
4

git add notes.md
git diff --staged
git commit -m "merge: 整合主分支并解决笔记冲突"
git push

不想继续本次合并，可以在合并尚未完成时执行：

1

git merge --abort

两边改动都要保留时，应把它们整理成最终内容，不是随便删掉其中一边。

十二、撤销修改和临时保存

下面是不同场景的处理方法，不要把全部命令连续执行。

文件暂存错了

取消暂存，但保留电脑上的修改：

1

git restore --staged README.md

放弃未暂存的修改

确认不需要这些内容，或先备份，再执行：

1

git restore README.md

它会用暂存区版本覆盖工作区文件，未保存到其他位置的改动会丢失。

开发到一半，需要切换分支

临时保存已跟踪文件的改动和未跟踪文件：

1
2

git stash push -u -m "临时保存开发进度"
git stash list

回到原来的开发分支后，恢复最近一份暂存：

1

git stash apply

apply 不会删除这份 Stash；恢复可能发生冲突，检查无误后再处理，忽略文件不在 -u 的保存范围内。

撤销已经提交的修改

对于已经上传的普通提交，优先用 Revert 新增一条撤销提交，不重写别人已获取的历史。

确认工作区干净；本例撤销当前分支最近一条普通提交，不适用于 Merge Commit：

1
2

git revert --no-edit HEAD
git push

如果撤销的是更早的提交，先用 git log --oneline 找到编号，再把 HEAD 换成该编号。

查找误操作前的提交

查看本地分支和 HEAD 的移动记录：

1

git reflog -10

它可以帮助找到误操作前的提交，但不是永久备份，也不能找回从未保存的全部文件。

刚开始不要随意执行 git reset --hard、git clean -fd 或强制 Push，它们可能丢失改动或覆盖远程历史。

具体规则参见 Git Stash 和 Git Revert。

十三、哪些文件不应该上传

在项目根目录创建 .gitignore，忽略临时文件和私密配置，例如：

1
2
3
4

node_modules/
build/
*.log
.env

这只是示例，按项目需要保留或修改规则，再把 .gitignore 本身提交进仓库。

.gitignore 不会自动取消已经跟踪的文件，也不会删除历史中的密码；秘密泄露后应先撤销或更换密钥。

每次提交前用 git diff --staged 检查，不上传密码、Token、验证码、私钥和不该公开的个人信息。

十四、个人开发的日常流程

开始前确认工作区干净，同步主分支并创建本次任务的分支：

1
2
3
4

git status
git switch main
git pull --ff-only origin main
git switch -c feature/update-readme

修改并保存 README，检查后提交和上传：

1
2
3
4
5

git diff
git add README.md
git diff --staged
git commit -m "docs: 完善项目使用说明"
git push -u origin feature/update-readme

接下来创建 PR、检查修改、合并，再更新本地 main。

1

同步 main → 创建分支 → 修改 → Add → Commit → Push → PR → Merge → 同步 main

一个 Commit 尽量只做一件清楚的事，一条分支尽量只完成一个任务。

这套流程也适用于多人协作，参见 GitHub Flow。

十五、和朋友协作开发

有仓库写入权限时，双方克隆同一个仓库，各自在自己的分支开发。

仓库负责人进入 Settings → Collaborators → Add people 邀请朋友，朋友接受邀请后再推送代码。

朋友先同步 main，创建自己的功能分支，修改后 Commit、Push，再提交 PR。

负责人检查 Files changed 和测试结果，有问题就留言，朋友继续在同一分支提交修改。

审查选项中，Comment 是留言，Approve 是同意，Request changes 是要求修改。

确认可以合并后由有权限的人合并，双方再拉取最新 main，不要直接覆盖对方的文件。

十六、给别人的项目贡献代码：Fork

没有原仓库写入权限时，先 Fork 到自己的账号，再在副本中修改并向原仓库提交 PR。

1

原作者仓库 → Fork 到自己的 GitHub → Clone 到电脑 → 分支修改 → Push 到自己的仓库 → PR 给原作者

克隆的是自己的 Fork，origin 指向自己的副本；原项目可另设为 upstream。

在 Fork 的项目目录中执行，下面的原仓库地址需要替换：

1
2
3
4
5

git remote add upstream https://github.com/原作者/原仓库.git
git fetch upstream
git switch main
git merge --ff-only upstream/main
git push origin main

工作区要先保持干净；如果 Fork 的主分支已经有自己的独立提交，快进会被拒绝，应先检查差异，不要强制覆盖。

贡献代码时从同步后的主分支创建功能分支，把功能分支推送到自己的 origin，再在网页上选择原仓库的主分支作为 PR 的 base。

Fork 和 Clone 不会让你获得原仓库的写入权限，是否接受修改由原项目维护者决定。

十七、记录任务和发布版本

在仓库的 Issues → New issue 创建任务，写清目标和完成条件。

修复同仓库的 Issue 时，可在 PR 说明里写 Closes #1；合并到默认分支后会关闭对应 Issue，1 换成实际编号。

准备发布时，先切到最新主分支，确认代码和测试无误，再标记版本：

1
2
3
4

git switch main
git pull --ff-only origin main
git tag -a v1.0.0 -m "第一个正式版本"
git push origin v1.0.0

版本号要选一个尚未使用的值；不要重复执行命令来覆盖已有版本。

随后在 GitHub 的 Releases 中创建发布，选择这个 Tag、填写版本说明，按需要上传安装包。

Tag 不等于安装包，上传 Tag 也不会自动替项目编译程序。

README 写清项目用途和使用方法；LICENSE 用于说明许可，没有许可文件不代表可以任意使用代码。

十八、GitHub Actions：自动检查

Actions 可以在 Push 或 PR 后自动运行任务，例如测试、编译和检查文档。

下面给 learn-github 练习仓库增加一个最小检查：确认 README 存在且不为空。

在练习项目根目录新建 .github\workflows\check.yml，内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

name: Check README

on:
  push:
  pull_request:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: 下载仓库
        uses: actions/checkout@v7
        with:
          persist-credentials: false
      - name: 检查 README
        run: test -s README.md

创建文件的目录需要先建好；它属于 GitHub 练习仓库，不是本文所在的 Hexo 博客项目。

使用功能分支提交这个文件：

1
2
3
4

git add .github/workflows/check.yml
git diff --staged
git commit -m "ci: 添加 README 自动检查"
git push

命令假设当前功能分支已经建立了远程对应关系；第一次推送时使用 git push -u origin 当前分支名。

打开仓库的 Actions 页面查看结果，绿色表示该任务成功，红色表示失败，应点进去看日志。

这个检查只确认 README 非空，不代表项目代码正确；实际项目要换成相应的测试或编译命令。

workflow_dispatch 用于手动运行，文件先进入默认分支后，才可以在 Actions 页面找到对应的手动运行入口。

需要 Token 或密码时，通过 GitHub 的 Secrets 配置，不直接写进 YAML，也不在日志里输出。

配置规则参见 GitHub Actions 工作流语法，Checkout 的用途参见 官方 Checkout。

十九、常见问题

Push 返回 403

先确认 git remote -v 指向自己的仓库，再检查当前登录账号是否有写入权限；设置 user.name 不会增加权限。

Push 被拒绝：non-fast-forward

远程有本地尚未包含的提交，先保存自己的改动，执行 git fetch origin 检查历史，再按需要合并或 Rebase。

本文的 --ff-only 遇到分叉会停止，不要把停止当作需要强制 Push 的理由。

PR 提示没有共同历史

功能分支和主分支不是从同一套历史分出来的，可能是重新 git init 或创建了孤立分支。

先备份自己的修改，再从正确的 origin/main 创建新分支，把需要的改动重新提交；不要直接强行合并无关历史。

明明修改了，Commit 却没内容

检查文件是否保存，执行 git status，确认需要的修改已经 git add 到暂存区。

Push 成功，主分支却没变化

可能只上传了功能分支，先切换 GitHub 网页的分支查看，再通过 Merge 或 PR 合并到 main。

切换分支时提示本地修改会被覆盖

先 Commit、Stash 或备份改动，再切换分支，不要直接强制丢弃。

二十、命令速查

最重要的区别：Add 是准备提交，Commit 是本地存档，Push 是上传，Merge 才是合并。