From 827ccf0ed1adbf4b3aaca1af41395d811b2befff Mon Sep 17 00:00:00 2001
From: Qiyuanqiii <2297740147@qq.com>
Date: Fri, 4 Sep 2026 03:13:48 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20Git=20=E5=85=A5?=
=?UTF-8?q?=E9=97=A8=E4=B8=8E=E8=B4=A1=E7=8C=AE=E5=8D=8F=E4=BD=9C=E6=8C=87?=
=?UTF-8?q?=E5=8D=97?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/.vitepress/theme/custom.css | 45 +++
docs/about/contribute.md | 581 ++++++++-----------------------
docs/development/git-basics.md | 323 ++++++++++++++++-
docs/development/index.md | 4 +-
4 files changed, 505 insertions(+), 448 deletions(-)
diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css
index 4ef23fa..2d50974 100644
--- a/docs/.vitepress/theme/custom.css
+++ b/docs/.vitepress/theme/custom.css
@@ -1176,6 +1176,51 @@
padding: 12px;
}
+@media (max-width: 640px) {
+ .content-meta {
+ margin-bottom: 20px;
+ }
+
+ .content-meta__header {
+ gap: 6px;
+ padding: 8px 10px;
+ }
+
+ .content-meta__badge {
+ font-size: 12px;
+ padding: 1px 7px;
+ }
+
+ .content-meta__body {
+ gap: 8px 12px;
+ grid-template-columns: repeat(2, minmax(0, 1fr));
+ padding: 10px;
+ }
+
+ .content-meta__item {
+ font-size: 13px;
+ line-height: 1.55;
+ min-width: 0;
+ overflow-wrap: anywhere;
+ }
+
+ .content-meta__item strong {
+ display: inline;
+ font-size: 12px;
+ margin-right: 5px;
+ }
+
+ .content-meta__item--sources {
+ grid-column: 1 / -1;
+ }
+
+ .content-meta__warning {
+ font-size: 13px;
+ line-height: 1.55;
+ padding: 8px 10px;
+ }
+}
+
.material-categories {
display: grid;
gap: 28px;
diff --git a/docs/about/contribute.md b/docs/about/contribute.md
index 5b3b730..a36b286 100644
--- a/docs/about/contribute.md
+++ b/docs/about/contribute.md
@@ -8,480 +8,230 @@ content_type: verified
status: active
maintainers:
- SCSWiki 维护组
-sources: []
+sources:
+ - name: GitHub Docs：使用 Fork
+ url: https://docs.github.com/en/pull-requests/how-tos/work-with-forks
+ - name: GitHub Docs：连接到 GitHub
+ url: https://docs.github.com/en/get-started/git-basics/set-up-git
+ - name: GitHub Docs：创建 Pull Request
+ url: https://docs.github.com/en/pull-requests/how-tos/create-pull-requests/creating-a-pull-request
---
# 如何贡献
-你可以通过 Issue 提交内容错误、过期反馈或新内容建议。熟悉 Git 的贡献者可以 Fork 仓库后提交 Pull Request。
+你可以通过 Issue 提交内容错误、过期反馈或新内容建议，也可以通过 Pull Request（PR）直接完善页面。第一次使用 Git 时，建议先阅读 [Git 入门](/development/git-basics)。
-> 下面展示如何提交 Pull Request
+:::: tip 选择合适的方式
-## 一、登录Github
+- 只想报告问题、暂时不方便修改：提交 Issue，写清页面地址、问题和可核验来源。
+- 已经准备好修改：Fork 仓库，在独立分支完成改动并创建 PR。
+- 涉及学校政策、费用、时间或个人信息：先确认公开来源和时效，不确定时宁可标记待核验。
-Github官网：[官网链接](https://github.com/)
+::::
-如果没有账号就注册一个，然后保持你浏览器的Github登录状态。
+## 一、登录 GitHub 并创建 Fork
-然后进入项目的首页：[项目链接](https://github.com/pppolf/SCSWiki)，你会看到如下页面
+登录 [GitHub](https://github.com/)，然后进入 [SCSWiki 官方仓库](https://github.com/CWNU-Open-Source-Community/SCSWiki)。
-
+点击页面右上角的 **Fork**，再选择 **Create fork**，在自己的 GitHub 账号下创建一份仓库副本。创建完成后请检查：
-然后我们点击 **Fork** 把这个代码克隆到本地。
+- 页面顶部的仓库所有者是你的 GitHub 用户名；
+- 页面显示它 Fork 自 `CWNU-Open-Source-Community/SCSWiki`。
-点击后直接点击Creat fork
+## 二、安装工具并运行项目
-
+### 1. 准备 Git、Node.js 和编辑器
-然后会自动跳转到你仓库的页面，现在你看到的就是Fork之后的仓库了。
+本项目需要：
-
+- Git，安装和首次设置见 [Git 入门](/development/git-basics)；
+- Node.js `>=20.11.0`，可从 [Node.js 官方下载页](https://nodejs.org/en/download) 安装；
+- 一个文本编辑器，下面以 [VS Code](https://code.visualstudio.com/Download) 为例，也可以使用其他编辑器。
-## 二、把项目跑起来
+安装 Node.js 后请重新打开终端；如果使用 VS Code，也请重启 VS Code，再检查版本：
-首先需要我们在本地找一个位置来放置我们的项目，然后去clone这个fork项目。
-
-
-
-这里我使用命令行操作，打开终端，cd到你想保存的位置，随后输入
-
-```sh
-git clone https://github.com/你的GitHub用户名/SCSWiki.git
+```bash
+git --version
+node --version
```
-
-
-然后我们使用vscode打开这个项目，这个应该都会吧。！打开之后你会看到如下界面
-
-
-
-然后我们进行下一步安装依赖，首先你需要保证你有node环境 Node.js `>=20.11.0`，如果不知道怎么安装node，可以问AI安装。。。
-
-打开自带的终端。
-
-
-
-输入 `node -v` 查看当前的node环境，符合条件即可，接下来就是安装依赖了，输入 `npm install -g pnpm` 我们使用pnpm管理依赖，然后输入 `pnpm install` 安装项目依赖，等几分钟就安装完了！
-
-安装完成你会看到
-
-
+### 2. 克隆自己的 Fork
-然后把项目启动起来，运行命令 `npm run dev`，然后打开网址 `http://localhost:5173` 你就会看到这个项目了。
+先选择一个不属于其他 Git 仓库的目录，用来保存项目。
-
+下面命令中的 `YOUR-USERNAME` 必须替换为你的 GitHub 用户名，不能原样复制：
-## 三、配置github信息
-
-回到 vscode 中查看当前分支和修改：
-
-```sh
-git status
+```bash
+git clone https://github.com/YOUR-USERNAME/SCSWiki.git
+cd SCSWiki
```
-查看远程仓库：
+克隆完成后，使用 VS Code 打开 `SCSWiki` 目录。
-```sh
-git remote -v
-```
+### 3. 安装依赖
-正常情况下应该至少有：
+仓库在 `package.json` 中指定 pnpm `9.15.4`。优先通过 Corepack 启用该版本，再安装依赖：
-```sh
-origin https://github.com/你的用户名/SCSWiki.git
+```bash
+corepack enable
+corepack prepare pnpm@9.15.4 --activate
+pnpm --version
+pnpm install
```
-其中：
-
-- `origin`：你自己的 Fork；
-- `upstream`：原始项目仓库。
+如果终端提示找不到 `corepack`，可以改用下面的固定版本安装方式，然后再运行 `pnpm install`：
-如果还没有 `upstream`，添加它：
-
-```sh
-git remote add upstream https://github.com/pppolf/SCSWiki.git
+```bash
+npm install --global pnpm@9.15.4
```
-再次确认：
+两种 pnpm 安装方式选择一种即可。若全局安装提示权限不足，请优先使用 Corepack 或参考 pnpm 官方安装说明，不要切换到 `root` 用户运行项目命令。
-```sh
-git remote -v
-```
+### 4. 启动本地预览
-应该类似：
-
-```sh
-origin https://github.com/你的用户名/SCSWiki.git (fetch)
-origin https://github.com/你的用户名/SCSWiki.git (push)
-upstream https://github.com/pppolf/SCSWiki.git (fetch)
-upstream https://github.com/pppolf/SCSWiki.git (push)
+```bash
+pnpm dev
```
-注意：你通常只向 `origin` 推送，不向 `upstream` 推送。
-
-同步原项目的最新代码，在开始修改前，先确保本地代码是最新的。
-
-切换到主分支：
-
-```sh
-git switch main
-```
-
-从原项目获取最新提交：
-
-```sh
-git fetch upstream
-```
-
-把上游最新代码合并到本地主分支：
-
-```sh
-git merge upstream/main
-```
-
-在同步之前我们要设置SSH才可以，打开终端
-
-以当前 `root` 用户执行：
-
-```sh
-ssh-keygen -t ed25519 -C "你的GitHub邮箱"
-```
-
-出现：
-
-```sh
-Enter file in which to save the key
-```
-
-直接回车，默认保存到：
-
-```sh
-/root/.ssh/id_ed25519
-```
+打开终端实际显示的本地地址，通常是 `http://localhost:5173`；如果端口被占用，开发服务器会使用其他端口。
-出现密码短语提示时，直接回车两次不设置。看到这个就行了
+开发服务器会持续占用当前终端。预览期间请保持它运行，并在 VS Code 中新建第二个终端执行后续命令；不再需要预览时，可回到该终端按 `Ctrl+C` 停止。
-
+## 三、配置远程仓库并同步主分支
-查看公钥
+查看当前远程仓库：
-```sh
-cat ~/.ssh/id_ed25519.pub
-```
-
-会输出类似：
-
-```sh
-ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... xxx@xxx.com
-```
-
-复制完整的一整行。进入 GitHub 网页：
-
-```text
-右上角头像
-→ Settings
-→ SSH and GPG keys
-→ New SSH key
-```
-
-填写：
-
-```yml
-Title: SCSWiki
-Key type: Authentication Key
-Key: 粘贴刚才的完整公钥
-```
-
-点击：
-
-```text
-Add SSH key
-```
-
-回到虚拟机测试连接：
-
-```sh
-ssh -T git@github.com
-```
-
-第一次可能出现：
-
-```sh
-Are you sure you want to continue connecting (yes/no/[fingerprint])?
-```
-
-输入：
-
-```sh
-yes
-```
-
-成功时会看到类似：
-
-```sh
-Hi github账号! You've successfully authenticated, but GitHub does not provide shell access.
+```bash
+git remote -v
```
-把仓库地址从 HTTPS 改成 SSH，当前你当前的地址是：
+刚克隆自己的 Fork 时，输出通常类似：
```text
-https://github.com/你的github账号/SCSWiki.git
+origin https://github.com/YOUR-USERNAME/SCSWiki.git (fetch)
+origin https://github.com/YOUR-USERNAME/SCSWiki.git (push)
```
-改为：
+`origin` 指向你自己的 Fork。再添加官方仓库为 `upstream`，这一步只需执行一次：
-```sh
-git remote set-url origin git@github.com:你的github账号/SCSWiki.git
+```bash
+git remote add upstream https://github.com/CWNU-Open-Source-Community/SCSWiki.git
+git remote -v
```
-检查：
+如果出现 `remote upstream already exists`，不要重复添加，先检查现有地址是否正确。
-```sh
-git remote -v
-```
+### GitHub 认证方式
-应该显示：
+同步公开仓库不需要先配置 SSH。向自己的 Fork 推送时，可以使用 HTTPS，也可以自行选择 SSH：
-```sh
-origin git@github.com:你的github账号/SCSWiki.git (fetch)
-origin git@github.com:你的github账号/SCSWiki.git (push)
-```
+- 使用 HTTPS 时，GitHub 不接受账户密码进行 Git 操作。首次推送通常会通过浏览器、Git Credential Manager 或令牌完成认证。
+- 使用 SSH 时，请按照 [GitHub 官方说明](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) 生成并添加密钥，不要用 `sudo` 或切换到 `root` 用户操作。
+- 不要把密码、访问令牌或私钥写进远程地址、源码、截图或聊天记录；共用电脑上不要长期保存凭据。
-然后再次推送：
+每次开始新任务前，同步官方 `main`：
-```sh
+```bash
+git switch main
+git fetch upstream
+git merge --ff-only upstream/main
git push origin main
```
-## 四、为本次修改创建新分支
+`git fetch` 只获取远程状态；`--ff-only` 可以避免同步时意外产生合并提交。若合并失败，先运行 `git status` 查看原因，不要直接强制推送。
+
+## 四、创建任务分支并完成修改
-不要直接在 `main` 分支修改。
+先确认要处理的 Issue、页面错误或内容任务，不要直接把教程中的演示文字提交到仓库。下面假设任务是更新已有的校园网络说明。
-例如，你准备添加一篇校园网教程：
+创建并检查任务分支：
-```sh
-git switch -c docs/add-campus-network-guide
+```bash
+git switch -c docs/update-campus-network
+git branch --show-current
```
-分支名称建议使用：
+分支名应简短描述本次任务，例如：
```text
-docs/xxx 文档修改
-fix/xxx 修复错误
-feat/xxx 新功能
-refactor/xxx 重构
-chore/xxx 工程配置
+docs/update-campus-network 文档修改
+fix/broken-campus-link 修复错误
+feat/new-search-filter 新功能
+refactor/sidebar-data 重构
+chore/update-tooling 工程配置
```
-查看当前分支：
+然后在编辑器中打开本次任务对应的真实文件，按照 Issue 或核验结果修改并保存。本例对应 `docs/campus/network.md`。
-```sh
-git branch
-```
+如果要新增页面，还应：
-带 `*` 的是当前分支：
+1. 先确认目标目录中没有同名文件或相同 URL；
+2. 参考同目录页面补全 Front Matter、``、来源和核验状态；
+3. 按项目现有结构更新 `docs/.vitepress/sidebar.ts`；
+4. 不编造学校政策，不写入账号、联系方式等个人敏感信息；
+5. 参考仓库根目录的 [内容贡献规范](https://github.com/CWNU-Open-Source-Community/SCSWiki/blob/main/CONTENT_GUIDE.md)。
-```sh
-* docs/add-campus-network-guide
- main
-```
+回到本地预览地址检查页面内容、链接和侧边栏。若示例中约定更新校园网络页，则访问 `/campus/network`。
-我们回到vscode，打开目录 `/docs/campus/` 新建一个文件名叫 `network.md` 文档可以写成
+## 五、检查、提交并推送
-```markdown
----
-title: 校园网络使用指南
-description: 介绍校园网络的基本使用方法
-category: campus
-audience:
- - 本科生
-content_type: experience
-status: needs-review
-maintainers:
- - SCSWiki 维护组
-sources: []
----
+下面仍以“已经修改并保存 `docs/campus/network.md`”为例。其他任务必须把路径和分支名替换为自己的实际内容。
-
-
-# 校园网络使用指南
-
-> 本页面仍在核验中，请以学校最新通知为准。
-
-## 使用前准备
-
-请先确认已经获得学校统一身份认证账号。
-
-## 注意事项
-
-不要向任何人泄露账号和密码。
-```
-
-请注意，在新添加了某页面，需要在 `/docs/.vitepress/sidebar.ts` 里添加对应的链接。比如现在我们是添加的 `/campus` 下的，所以我们就找对应的区域加，写上 text 和 link 就行了
-
-```ts
-...
-'/campus/': [
- {
- text: '校园生活',
- items: [
- { text: '总览', link: '/campus/' },
- { text: '校园网络待核验模板', link: '/campus/network-template' },
- { text: '校园网络使用指南', link: '/campus/network'},
- ],
- },
- ],
-...
-```
-
-然后我们可以回到浏览器看是否有了，点击链接：`http://localhost:5173/campus/network` 就有了。
-
-最后我们去检查一下语法什么的，运行 `pnpm check` 如果通过了就OK！
-
-## 五、如何提交
-
-查看状态：
-
-```sh
+```bash
git status
+git diff -- docs/campus/network.md
+pnpm check
+git add docs/campus/network.md
+git diff --staged
+git commit -m "docs: 更新校园网络说明"
+git status
+git push -u origin docs/update-campus-network
```
-添加到暂存区：
-
-```sh
-git add .
-```
-
-检查暂存区内容：
-
-```sh
-git diff --cached
-```
-
-这一步非常重要。它可以避免把 `.env`、临时文件、密码或无关内容提交进去。检查无误按 `q` 退出。
-
-创建 Commit 提交：
-
-```sh
-git commit -m "docs: add campus network guide"
-```
-
-中文也可以：
-
-```sh
-git commit -m "docs: 添加校园网络使用指南"
-```
-
-推荐格式：
-
-```yml
-类型: 简短描述
-```
-
-常用类型：
-
-```yml
-docs: 文档修改
-fix: 修复问题
-feat: 添加功能
-refactor: 重构
-test: 测试
-chore: 工程配置
-style: 格式调整
-```
-
-示例：
-
-```sh
-git commit -m "docs: add freshman registration guide"
-git commit -m "fix: correct broken link in campus guide"
-git commit -m "feat: add assistant entry component"
-```
-
-提交后查看记录：
-
-```sh
-git log --oneline -5
-```
-
-推送分支到自己的 Fork
-
-第一次推送当前分支：
-
-```sh
-git push -u origin docs/add-campus-network-guide
-```
-
-其中：
-
-```sh
-origin
-```
-
-是你自己的 Fork。
+注意：
-后续再修改并提交后，只需要：
+- `pnpm check` 包含类型检查、Markdown 检查、格式检查、内容校验、链接检查、测试和生产构建。
+- `git add` 后应写出本次实际修改的一个或多个文件路径；新增页面时通常还要暂存相应的侧边栏文件。
+- 不把 `git add .` 当作默认操作，避免夹带 `.env`、临时文件、密码或无关改动。
+- `git diff --staged` 展示真正会进入提交的内容，务必逐项检查；若进入分页界面，按 `q` 退出。
+- 一组改动只需执行一次 `git commit`。提交信息可使用中文或英文，重点是简短说明“做了什么”。
-```sh
-git push
-```
+常见提交类型：
-如果命令成功，终端一般会提示：
+- `docs:` 文档修改；
+- `fix:` 修复问题；
+- `feat:` 添加功能；
+- `refactor:` 重构；
+- `test:` 测试；
+- `chore:` 工程配置；
+- `style:` 格式调整。
-```sh
-Create a pull request for 'docs/add-campus-network-guide'
-```
+第一次推送使用 `git push -u origin 分支名`；同一个 PR 后续有新提交时，执行普通的 `git push` 即可。
-在 GitHub 创建 **Pull Request**
+## 六、创建 Pull Request
-打开你 Fork 后的 GitHub 仓库页面。
+打开自己的 GitHub Fork。推送成功后，页面通常会显示 **Compare & pull request**，点击后确认：
-通常会看到一个黄色或绿色提示：
-
-```sh
-Compare & pull request
-```
-
-点击它。
-
-确认以下内容：
-
-```sh
-base repository: 原始项目仓库
+```text
+base repository: CWNU-Open-Source-Community/SCSWiki
base branch: main
-
head repository: 你的 Fork
-compare branch: docs/add-campus-network-guide
-```
-
-也就是说：
-
-```sh
-你的分支
- ↓ 合并到
-原项目 main 分支
-```
-
-PR 标题建议：
-
-```sh
-docs: 添加校园网络使用指南
+compare branch: 本次任务分支
```
-PR 描述可以使用：
+PR 标题应直接说明改动，例如 `docs: 更新校园网络说明`。描述可以参考：
```markdown
## 修改内容
-- 新增校园网络使用指南
-- 添加页面 Front Matter
-- 更新校园生活栏目侧边栏
+- 更新校园网络说明
+- 修正过期内容并补充来源
## 修改原因
-现有 Wiki 缺少校园网络相关说明，新生难以快速找到对应信息。
+说明原页面存在的问题，以及本次修改如何解决。
## 信息来源
@@ -492,79 +242,42 @@ PR 描述可以使用：
## 本地检查
- [x] `pnpm check`
-- [x] `pnpm build`
-- [x] 检查移动端页面
-- [x] 未包含个人隐私信息
-- [x] 未包含未经核验的学校政策
+- [x] 检查桌面端和移动端页面
+- [x] 未包含个人隐私或凭据信息
+- [x] 对时效性内容标明来源和核验状态
## 截图
-如涉及页面样式，请附上截图。
+如涉及页面样式，请附上修改前后截图。
```
-然后点击：
-
-```text
-Create pull request
-```
+只勾选自己实际完成的检查，然后点击 **Create pull request**。PR 创建后可在 SCSWiki 交流群通知维护者审核。
-> 👉👉👉**在通过了PR之后再进行以下的操作，现在可以在SCSWiki交流群通知审核了。**
+收到评审意见后，继续在同一分支修改、检查、提交并推送，原 PR 会自动更新，不需要重新创建。
-## 六、PR 合并后清理分支
+## 七、PR 合并后同步与清理
-PR 合并后，先切回主分支：
+确认 PR 已合并后，回到本地仓库同步主分支：
-```sh
+```bash
git switch main
-```
-
-同步上游最新内容：
-
-```sh
git fetch upstream
-git merge upstream/main
-```
-
-推送到自己的 Fork：
-
-```sh
+git merge --ff-only upstream/main
git push origin main
```
-删除本地分支：
+先尝试删除已经完成的本地任务分支：
-```sh
-git branch -d docs/add-campus-network-guide
+```bash
+git branch -d docs/update-campus-network
```
-删除远程 Fork 上的分支：
+如果 PR 使用 Squash Merge 合并，`git branch -d` 可能因无法确认合并关系而安全拒绝。先在 GitHub 确认 PR 已合并，并核对分支没有需要保留的提交；不确定时先保留分支。
-```sh
-git push origin --delete docs/add-campus-network-guide
-```
+确认 PR 已合并且分支内容无需保留后，再删除 Fork 上的远程任务分支：
-## 七、以后每次提交 PR 的标准命令
-
-每次开始新任务：
-
-```sh
-git switch main
-git fetch upstream
-git merge upstream/main
-git push origin main
-git switch -c docs/your-change
-```
-
-完成修改后：
-
-```sh
-git status
-git diff
-pnpm check
-git add 相关文件
-git diff --cached
-git commit -m "docs: describe your change"
-git push -u origin docs/your-change
+```bash
+git push origin --delete docs/update-campus-network
```
-然后去 GitHub 创建 PR。
+以后每次贡献都重复“同步 `main` → 创建任务分支 → 修改和预览 → 检查 → 精确暂存 → 提交并推送 → 创建 PR”这个闭环。
diff --git a/docs/development/git-basics.md b/docs/development/git-basics.md
index 4a4ec97..45f9677 100644
--- a/docs/development/git-basics.md
+++ b/docs/development/git-basics.md
@@ -1,33 +1,332 @@
---
title: Git 入门
-description: Git 的最小可用工作流
+description: 从安装和配置 Git 到完成一次安全提交并创建 Pull Request
category: development
audience:
- 本科生
-content_type: experience
+ - SCSWiki 贡献者
+content_type: verified
status: active
maintainers:
- SCSWiki 维护组
-sources: []
+sources:
+ - name: Git 官方安装指南
+ url: https://git-scm.com/downloads
+ - name: Pro Git：初次运行 Git 前的配置
+ url: https://git-scm.com/book/zh/v2/起步-初次运行-Git-前的配置
+ - name: Pro Git：记录每次更新到仓库
+ url: https://git-scm.com/book/zh/v2/Git-基础-记录每次更新到仓库
+ - name: GitHub Docs：使用 Fork
+ url: https://docs.github.com/en/pull-requests/how-tos/work-with-forks
---
# Git 入门
-Git 用于记录代码和文档的变更历史。初学阶段先掌握少量命令即可。
+Git 是运行在本机上的版本控制工具，用来记录代码和文档的变更历史。GitHub、Gitee 等则是托管远程仓库和开展协作的平台。
-## 最小工作流
+:::: tip 学完本页，你可以
+
+- 安装 Git 并完成首次身份设置；
+- 解释工作区、暂存区、本地仓库和远程仓库的区别；
+- 在独立分支中检查改动、完成提交并安全撤销暂存；
+- 把分支推送到自己的 Fork，并向 SCSWiki 创建 Pull Request。
+
+::::
+
+## 安装 Git
+
+先打开终端并运行：
+
+```bash
+git --version
+```
+
+如果能看到类似 `git version 2.x.x` 的输出，说明 Git 已经安装。若提示找不到命令，请按操作系统选择一种安装方式。
+
+### Windows
+
+可以在 PowerShell 或“命令提示符”中使用 Windows 程序包管理器安装：
+
+```powershell
+winget install --id Git.Git -e --source winget
+```
+
+如果电脑没有 `winget`，可从 [Git for Windows](https://git-scm.com/install/windows) 下载安装程序。初次使用可以保留安装器的默认选项；安装完成后关闭并重新打开终端。
+
+### macOS
+
+安装 Apple 命令行工具：
+
+```bash
+xcode-select --install
+```
+
+如果已经安装 Homebrew，也可以运行：
+
+```bash
+brew install git
+```
+
+### Linux
+
+Debian 或 Ubuntu：
+
+```bash
+sudo apt update
+sudo apt install git
+```
+
+Fedora：
+
+```bash
+sudo dnf install git
+```
+
+Arch Linux：
+
+```bash
+sudo pacman -S git
+```
+
+安装完成后再次运行 `git --version`。`sudo` 只用于安装系统软件，不要在项目目录中使用 `sudo git add` 或 `sudo git commit`。
+
+:::: info 命令环境
+
+本页的 Git 命令可以在 PowerShell、Git Bash、macOS 终端和常见 Linux Shell 中运行。`touch`、`rm`、`cat` 等普通文件命令在不同终端中的行为可能不同，因此本页不依赖它们创建或删除文件。
+
+::::
+
+## 首次设置
+
+每次提交都会记录作者名和邮箱。请把下面的示例文字替换为自己的信息，不要原样复制：
+
+```bash
+git config --global user.name "你的姓名或公开昵称"
+git config --global user.email "你的公开邮箱或 GitHub noreply 邮箱"
+git config --global init.defaultBranch main
+```
+
+- `user.name` 是提交记录中的作者名，不要求与 GitHub 用户名相同。
+- 邮箱会写入提交记录。如果不想公开私人邮箱，可按 [GitHub 的说明](https://docs.github.com/en/account-and-profile/how-tos/email-preferences/setting-your-commit-email-address) 使用平台提供的 `noreply` 邮箱。
+- `--global` 表示作者信息等 Git 配置对当前操作系统账户下的所有仓库生效；进入仓库后可改用 `--local` 只配置当前仓库。
+
+作者信息与 GitHub 登录凭据是两回事。在机房或共用电脑上，除了避免留下全局作者信息，还要退出浏览器账号，并单独清除凭据管理器中的登录信息；`--local` 不能代替这些操作。
+
+只检查刚才设置的三项，避免在截图或求助时暴露其他自定义配置：
+
+```bash
+git config --global --get user.name
+git config --global --get user.email
+git config --global --get init.defaultBranch
+```
+
+## Git 在保存什么
+
+Git 的核心流程可以理解为：
+
+```text
+工作区（当前检出的项目文件）
+ ↓ git add
+暂存区（下次提交的选择）
+ ↓ git commit
+本地仓库（本机提交历史）
+ ↓ git push
+远程仓库（GitHub / Gitee）
+```
+
+- **工作区**：当前实际看到和编辑的整套项目文件；用 `git status` 和 `git diff` 检查其中的变化。
+- **暂存区**：下一次提交将采用的内容快照；用 `git add` 选择，用 `git diff --staged` 检查。
+- **本地仓库**：已经创建的本地提交历史；用 `git commit` 保存，用 `git log` 查看。
+- **远程仓库**：上传到 GitHub 等平台的提交和分支；用 `git fetch` 获取，用 `git push` 推送。
+
+`git add` 是“选择下次提交的内容”，`git commit` 只创建本地提交；只有 `git push` 才会把本地提交发送到远程。Pull Request（PR）则是在托管平台上请求把一个分支的改动合并到另一个分支。
+
+文件执行 `git add` 后仍然存在于工作区；如果暂存后又继续编辑，同一文件可以同时包含已暂存和未暂存的修改。
+
+## 完成第一次本地提交
+
+建议先新建一个空的一次性练习目录熟悉流程，不要在已有项目中执行下面的 `git init`，也不要直接拿课程作业或重要文件试验。
+
+```bash
+mkdir git-practice
+cd git-practice
+git init
+git status
+```
+
+接着用任意文本编辑器在 `git-practice` 目录中创建 `README.md`，写入一两行学习目标并保存，然后执行：
+
+```bash
+git status
+git add README.md
+git diff --staged
+git commit -m "添加学习说明"
+git status
+git log -5 --oneline
+```
+
+完成后应看到：
+
+1. `git log -5 --oneline` 中出现刚才的提交；
+2. `git status` 显示工作区干净；
+3. 提交仍只保存在本地，没有自动上传到 GitHub。
+
+如果 `git log` 打开了分页界面，按 `q` 退出。
+
+## 安全提交工作流
+
+下面继续以“再次修改并保存 `README.md`”为例，展示真实项目中的参考流程。处理其他文件时，应把 `README.md` 替换为实际修改的路径：
```bash
git status
-git add .
-git commit -m "docs: update note"
-git log --oneline
+git diff
+git add README.md
+git diff --staged
+git commit -m "补充 Git 学习笔记"
+git status
+```
+
+- **`git status`**：确认当前分支，以及哪些文件已修改、未跟踪或已暂存。
+- **`git diff`**：阅读尚未暂存的具体改动。
+- **`git add README.md`**：只把指定文件的当前内容放入暂存区。
+- **`git diff --staged`**：提交前再次核对真正会进入提交的内容。
+- **`git commit -m "..."`**：创建一个本地提交，消息应说明“做了什么”。
+
+普通 `git diff` 不显示尚未跟踪的新文件内容。先用 `git status` 发现新文件，再精确暂存，并通过 `git diff --staged` 检查它将提交的内容。
+
+初学阶段优先暂存明确的文件，不把 `git add .` 当作默认操作。`.` 会递归选择当前目录下的变化，可能夹带无关文件、生成文件或敏感信息。
+
+提交前还应做到：
+
+- 一次提交只处理一件清楚的事情；
+- 按项目 README 或贡献指南运行检查命令；SCSWiki 使用 `pnpm check`；
+- 用项目的 `.gitignore` 排除依赖、构建产物和本地配置，但仍要用 `git status` 主动核对；
+- 不提交 `.env`、密钥、访问令牌、账号、真实个人信息、构建产物或编辑器缓存；
+- 密钥一旦进入提交历史，应立即撤销或轮换；只删除文件不能让已经泄露的密钥重新安全。
+
+## 使用分支
+
+分支让一项修改与稳定的 `main` 分开。创建并切换到新的任务分支：
+
+```bash
+git switch -c docs/improve-git-guide
+git branch --show-current
```
-## 建议
+分支名应简短描述任务，建议使用小写英文、斜杠和连字符，不使用空格。为开源项目贡献时，不要直接在 `main` 上完成任务修改。
+
+如果已经在 `main` 上修改了文件但还没有提交，通常可以直接运行 `git switch -c 新分支名`，当前修改会一起带到新分支；不要为了“清理”而运行 `git reset --hard`。
+
+## 为 SCSWiki 创建 Pull Request
+
+下面是一条从 Fork 到 PR 的最小路径。完整的项目运行和贡献说明见 [参与贡献](/about/contribute)。
+
+请打开一个新终端，或者先离开前面的 `git-practice` 练习仓库并回到普通工作目录。不要把 SCSWiki 克隆到另一个 Git 仓库内部。
+
+### 1. Fork 并克隆仓库
+
+先在 GitHub 上 Fork [SCSWiki 官方仓库](https://github.com/CWNU-Open-Source-Community/SCSWiki)，然后克隆自己的 Fork。请将 `YOUR-USERNAME` 替换为自己的 GitHub 用户名：
+
+```bash
+git clone https://github.com/YOUR-USERNAME/SCSWiki.git
+cd SCSWiki
+git remote -v
+```
+
+`origin` 默认指向自己的 Fork。再添加官方仓库为 `upstream`，这一步只需执行一次：
+
+```bash
+git remote add upstream https://github.com/CWNU-Open-Source-Community/SCSWiki.git
+git remote -v
+```
+
+如果看到 `remote upstream already exists`，不要重复添加，先用 `git remote -v` 检查现有地址。
+
+### 2. 同步并创建任务分支
+
+```bash
+git switch main
+git fetch upstream
+git merge --ff-only upstream/main
+git switch -c docs/improve-git-guide
+```
+
+`git fetch` 只获取远程状态，不会直接覆盖当前文件。`--ff-only` 可以避免在同步时意外产生合并提交；如果命令失败，先运行 `git status` 查明原因，不要强制推送。
+
+### 3. 检查、提交并推送
+
+创建任务分支后，先按照实际任务修改并保存文件。下面假设本次任务就是完善 `docs/development/git-basics.md`；处理其他任务时，必须换成自己的实际文件路径。
+
+以下以已经按照 [参与贡献](/about/contribute) 安装 Node.js、pnpm 和项目依赖为前提。完成修改后，先运行 SCSWiki 的项目检查：
+
+```bash
+pnpm check
+```
+
+再检查并提交 Git 改动。SCSWiki 示例中的 `docs:` 用来标识文档变更，是项目约定而不是 Git 强制语法；参与其他项目时，应优先遵循该项目的贡献规范。
+
+```bash
+git status
+git diff -- docs/development/git-basics.md
+git add docs/development/git-basics.md
+git diff --staged
+git commit -m "docs: 完善 Git 入门教程"
+git push -u origin docs/improve-git-guide
+```
+
+推送后在 GitHub 创建 PR，并确认：
+
+- base repository 是 `CWNU-Open-Source-Community/SCSWiki`；
+- base branch 是 `main`；
+- compare branch 是自己 Fork 中刚推送的任务分支；
+- 标题说明改了什么，描述中写清改动内容和检查结果。
+
+收到评审意见后，继续在同一分支修改、提交并执行普通的 `git push`，原 PR 会自动更新，不需要重新创建。
+
+:::: warning 认证和凭据
+
+GitHub 的 HTTPS Git 操作不再使用账户密码。请按 GitHub 提示通过浏览器、Git Credential Manager、令牌或 SSH 完成认证。不要把令牌写进远程地址、源码、截图或聊天记录，在公共电脑上也不要长期保存凭据。
+
+::::
+
+## 撤销与恢复
+
+以下示例以已有至少一次提交的项目为前提。先判断改动处于哪个位置，再选择命令：
+
+- **文件误加入暂存区**：运行 `git restore --staged README.md`。这只取消暂存，工作区修改仍然保留。
+- **确认要丢弃已跟踪文件的未暂存修改**：运行 `git restore -- README.md`。它会让工作区恢复为当前暂存区版本；若该文件没有已暂存改动，通常就是上次提交版本。被丢弃的修改无法靠 Git 找回；`--` 表示后面开始是文件路径。
+- **已经提交或推送后发现错误**：优先将提交编号代入 `git revert COMMIT-ID` 创建一个撤销提交，再检查并正常推送。不要在共享历史上使用强制推送改写记录。
+
+`git restore` 无法找回被删除的未跟踪文件；这类文件只能尝试从编辑器本地历史、回收站或备份中恢复。
+
+:::: danger 不要盲目复制危险命令
+
+`git reset --hard`、`git clean -fd`、`git restore .`、旧式的 `git checkout -- .` 和 `git push --force` 可能删除本地工作或覆盖远程历史。它们不属于入门排错手段；遇到不确定的状态时，先运行 `git status` 并保留现场，再寻求帮助。
+
+::::
+
+## 常见报错
+
+- **`git: command not found` 或“不是内部或外部命令”**：Git 未安装，或安装后终端尚未重启。重新打开终端并运行 `git --version`。
+- **`fatal: not a git repository`**：当前目录不是 Git 仓库。进入正确目录；不要为了消除报错就在任意目录执行 `git init`。
+- **`Please tell me who you are`**：没有配置提交作者信息。检查 `user.name` 和 `user.email`。
+- **`nothing to commit`**：没有改动，或文件尚未保存。先运行 `git status`。
+- **`remote ... already exists`**：同名远程仓库已经配置。用 `git remote -v` 检查，不要重复添加。
+- **`non-fast-forward` 或 `fetch first`**：远程有本地没有的提交。先获取并查看差异，不要立即使用强制推送。
+
+## 完成自查
+
+本地 Git：
+
+- `git --version` 能正确输出版本；
+- 能说明 `add`、`commit`、`push` 和 PR 的区别；
+- 当前位于自己的任务分支，而不是直接在 `main` 上修改；
+- 提交前检查过 `git status` 和 `git diff --staged`；
+- `git status` 在提交后显示工作区干净；
+
+SCSWiki 贡献：
-- 每次提交只描述一个清晰变更。
-- 提交前先运行项目检查命令。
-- 不提交密钥、账号、个人隐私或临时文件。
+- `git remote -v` 中能分清自己的 `origin` 和官方 `upstream`；
+- PR 的目标仓库、目标分支和来源分支均正确。
diff --git a/docs/development/index.md b/docs/development/index.md
index 0813998..86fd13a 100644
--- a/docs/development/index.md
+++ b/docs/development/index.md
@@ -20,14 +20,14 @@ sources: []
## 建议掌握
- 基本终端命令，见 [Linux 入门](/development/linux-basics)。
-- Git 提交、分支和远程仓库概念，见 [Git 入门](/development/git-basics)。
+- Git 安装、首次配置、安全提交、分支和远程协作，见 [Git 入门](/development/git-basics)。
- 编译器或解释器的安装检查。
- 错误信息的复制、搜索和归纳。
- 常用 AI 工具的账号、订阅和使用边界，见 [GPT 订阅与支付经验](/development/gpt-subscription)。
## 相关页面
-- [Git 入门](/development/git-basics)：最小可用工作流。
+- [Git 入门](/development/git-basics)：安装配置、安全提交、分支协作、撤销恢复与 Pull Request。
- [Linux 入门](/development/linux-basics)：路径、文件、权限、进程和包管理基础。
- [传统开发](/development/tradition)：待补充。
- [AI 赋能开发](/development/ai)：待补充。