7.1 使用Github管理你的研报

📢 投研手册共建招募中 我们正在组团打造一份超实用、还不无聊的研究手册📘

📩 发邮件到：[e-mail] 邮件标题写：【投研手册协作申请】+ 你的名字

✍️ 内容包括：想参与的方向、过往经验和每周可投入时间

🧠 你会收获什么？新朋友、写作技巧、项目视角、署名机会，还有可能是下一段旅程的开始！

💡 开始之前的小提示

本节课将带你实战掌握使用 Git 与 GitHub 管理你的研报作品集，无论是为了版本记录、协同创作，还是打造个人品牌形象，这都是值得投入学习的技能。

不过，版本控制工具的学习曲线不低，文字教程在初期看起来可能略显枯燥。如果你是视觉学习型选手，建议配合一些优质的教学视频一同学习，例如：

🧱 什么是版本控制系统（Version Control Systems，VCS）

版本控制系统是一种用于记录文件变更历史的工具，最初应用于软件开发，但如今已被广泛用于写作、设计、数据分析等领域。你可以把它理解为一个“增强型的时间机器”，能帮助你：

• 回到过去的任何一个编辑版本；

• 同步团队成员的修改；

• 清晰追踪每次内容更新的作者与目的。

VCS 常见分类

类型	描述	示例	优劣势
本地版本控制系统	仅在本地存储文件历史	RCS	简单易用，但易丢失数据
集中式版本控制系统 (CVCS)	所有版本集中存储在一个中央服务器	CVS、SVN	管理清晰，但中央节点是单点故障
分布式版本控制系统 (DVCS)	每个人都保存项目完整历史记录	Git、Mercurial	安全性高，支持离线操作，适合协作

🚀 Git 简介：为什么选择 Git？

Git 是目前最流行的分布式版本控制系统（DVCS），它最初由 Linux 之父 Linus Torvalds 开发，用于管理 Linux 内核源代码。

✅ Git 的核心优势：

1. 分布式架构：每台电脑上都有完整的项目历史，哪怕 GitHub 挂了，你本地的版本也不会丢失。

2. 高性能：适合管理大量小文件，非常适合投研项目中涉及的 Markdown、PDF、图表等资料。

3. 灵活分支机制：允许你创建独立的分支来修改草稿、添加补充，再合并到主线。

4. 数据完整性高：Git 使用 SHA-1 哈希算法防止版本篡改，保证每次提交都能追溯。

🔁 和 Dropbox 的区别：

项目	Git	Dropbox
版本历史存储	本地保存所有历史版本	远程服务器保存部分历史
回滚能力	精准控制任意历史状态	限制多、操作粗糙
多人协作	支持多人同时编辑+合并机制	文件冲突难处理

🛠 Git & GitHub 的安装与准备

💾 Git 本体下载：

• 官网地址：https://git-scm.com/

• 或参考教程：CSDN：Git 本地仓库建立与远程连接教程（含常见错误处理）

💻 GitHub Desktop 客户端下载：

• 地址：https://desktop.github.com/

• 特点：图形化界面，适合 Git 新手使用，无需记复杂命令。

🔄 其他推荐 Git 客户端（按操作系统划分）：

操作系统	推荐客户端	简介
macOS / Windows	Sourcetree	界面清晰、功能强大
macOS	Tower	适合专业用户
Windows	Git Extensions	开源，社区活跃
跨平台	VSCode + Git 插件	适合代码+文档混合管理场景

🗂 本地仓库管理

🔧 Git 的三大核心区域：工作区、暂存区、版本库（本地仓库）

使用 Git 的最大特征之一，是它采用了三段式的版本控制机制：工作区（Working Directory）、暂存区（Staging Area / Index） 和 本地仓库（Repository）。

img

这三者共同构成了 Git 的核心工作流：

1. 工作区（Working Directory）

   • 就是你日常编辑文件的地方。

   • 所有修改、删除、添加的内容都首先发生在这里。

2. 暂存区（Staging Area / Index）

   • 是一个用于组织和预览提交内容的中间缓冲区。

   • 你可以选择性地将改动“加入暂存”，从而控制哪些修改会被纳入下一次提交。

3. 版本库（Repository）

   • 是 Git 用于永久保存项目历史的数据库。

   • 一旦你执行 git commit，改动就被记录在版本库中，成为项目历史的一部分。

📌 关键优势： 这种多阶段提交机制让你可以非常灵活地管理改动内容，比如：只提交某部分文件、更细粒度地控制版本记录、避免提交临时或未完成的草稿。

✨ 为什么“暂存区”如此强大？

在 Git 中，你可以选择性地将文件或某段修改加入暂存区，这就意味着你不必一次性提交所有更改。

这在现实场景中极为实用： 比如你对一个文件做了两类逻辑完全不同的修改（如 bug 修复 + 文本润色），你可以将它们分两次提交，以便版本历史更清晰、可维护。

当然，如果你不想使用暂存区的这种细粒度控制，也可以使用 git commit -a 命令，跳过手动暂存，自动提交所有已修改（tracked）文件。

img

从这里开始：选择你的 Git 使用方式

🎯 接下来，我们将分别介绍 Git 的两种使用方式：

• 👉 一种是 命令行工具 Git Bash，面向希望深入理解 Git 底层机制、并追求灵活性与高度可控性的用户；

• 👉 另一种是 图形化客户端 GitHub Desktop，面向希望快速上手、注重用户体验、希望以最少阻力完成日常版本管理的用户。

这两种工具本质上都使用同样的 Git 核心机制，只是在交互方式上有所区别。你可以任选一种作为起点：

工具	类型	适用人群	特点
Git Bash	命令行工具	有一定技术基础、喜欢控制权的用户	强大灵活，支持 Bash 脚本与所有 Git 命令
GitHub Desktop	图形化客户端	初学者、内容创作者、视觉偏好的用户	操作简单直观，适合轻量化文件管理与版本控制

🔀 建议：如果你是 Git 新手，建议从 GitHub Desktop 入门；若你打算长期使用 Git 或希望写自动化脚本，建议逐步熟悉 Git Bash。

你可以只选择其中一种，也可以两种配合使用：用 GitHub Desktop 进行日常提交管理，用 Git Bash 补充一些进阶操作。

💻 Git Bash：命令行方式管理本地仓库

🧠 为什么先学命令行操作很重要？

虽然图形界面看起来更直观，但掌握命令行有诸多好处：

1. 精准控制： 通过命令行，你可以精确指定提交的文件、重命名、回滚等操作，远比鼠标拖动更可控。

2. 效率更高： 多文件处理、批量重命名、快速创建结构，用命令行能一键搞定。

3. 通用性强： 命令行知识在 Linux、macOS、服务器部署中通用，帮助你适应更广泛的工作场景。

4. 理解 Git 原理： 很多图形化工具隐藏了底层逻辑，命令行可以帮助你真正理解 Git 的行为方式，避免“出错不知为何”的状况。

🧱 Git Bash 中的基本命令行操作（必会）

以下是使用 Git Bash 时你需要掌握的一些基本命令，帮助你在文件系统中自由导航与操作。

命令	说明	示例
cd	进入指定目录	cd research
pwd	显示当前所在目录（绝对路径）	pwd
ls	列出当前目录中的文件和子目录	ls
ls -l	列出文件的详细信息（时间、权限等）	ls -l
mkdir	新建一个目录	mkdir drafts
touch	创建空文件	touch report.md
rm	删除文件	rm notes.txt
rm -r	递归删除目录及内容（⚠️危险）	rm -r old_versions
cp	复制文件	cp report.md backup.md
mv	移动或重命名文件	mv draft.md final.md

⚠️ 小提示：

• 粘贴命令时请使用：Shift + Insert 或 右键 → 粘贴（Windows 用户在 Git Bash 中默认 Ctrl+V 无效）

🆚 Git Bash vs Git CMD：有什么区别？

维度	Git Bash	Git CMD
Shell 环境	Bash（类 Unix）	Windows 命令提示符
路径符号	/path/to/file	C:\path\to\file
命令支持	支持 Unix 常用命令（如 grep, find）	仅支持 Windows 命令
附带工具	含 SSH、OpenSSL 等	功能相对精简
用户推荐	熟悉 Unix / 跨平台开发者	Windows 原生环境用户

📝本课程默认使用 Git Bash 作为教学环境。

🛠 使用 Git Bash 建立一个本地仓库：从零开始的版本管理实战

在这一节中，我们将通过一个形象的比喻——“保险柜”系统，帮助你理解 Git Bash 中最核心的命令与操作流程，并通过实战演练，建立一个可以追踪文件版本变化的本地仓库。

🚪 Git 命令速览：用“保险柜”比喻搞懂 Git 基础操作

Git 命令	保险柜类比	作用简述
git init	创建一个空保险柜	初始化仓库，使 Git 开始记录当前文件夹的版本变化
git add	将文件临时放入保险柜	把改动加入“候选列表”，准备好进行保存
git status	查看保险柜当前状态	查看有哪些文件已变动、已暂存、未跟踪
git commit	彻底锁定并记录保险柜内容	正式保存所有已暂存文件的当前状态，形成一个快照
git log	查阅以往所有保险柜内容	浏览每次提交的历史记录
git show	打开一个保险柜并看具体内容	显示某次提交的详细改动，包括文件差异
git restore	从保险柜里拿出旧版本文件	恢复或切换至某个指定的历史版本

🧱初始化一个本地仓库（git init）

我们从一个模拟项目开始：你希望整理、记录自己制作的各种食谱，每当有调整或优化，希望 Git 能帮你记住改动。

下面我们通过 Git Bash 在本地创建这个项目并初始化版本控制系统：

 cd /users/sandra 
 mkdir recipes
 cd recipes
 mkdir seitan
 mkdir tofu
 cd seitan
 nano smoky_carrot_tahini_seitan_slaw.txt
 nano boiled_seitan.txt
 cd ../tofu
 nano kung_pao_tofu.txt
 nano basil_ginger_tofu.txt

这些 nano 命令用于新建和编辑食谱文件，你也可以选择使用其他编辑器，如 vim、notepad++ 或 VS Code。

完成之后，我们返回 recipes 目录并初始化 Git 仓库：

 cd /users/sandra/recipes
 git init

git init的作用是告诉git版本控制系统，我们希望跟踪当前目录的历史记录，在本例中是“/users/sandra/recipes”。

📥 暂存文件（git add & git status）

git add    # 把文件暂时地放进保险柜中。
git status # 查看暂存在保险柜中的文件信息。

Git 默认不会自动跟踪所有文件，你需要显式告诉 Git：哪些文件我想让你开始“记录”。

git add ./tofu/kung_pao_tofu.txt

我们可以看到 使用 git status命令此命令的效果

git status

你会看到 Git 告诉你：“以下文件已准备好纳入下一次提交。”这表示文件已经进入暂存区（staging area），但还未真正保存到仓库。示例：在D盘Test文件夹中新建一个abtofu.txt，可以发现：

image-20250720085554262

❌ 如何撤销误添加的文件（git reset）

如果你不小心将不想提交的文件加入了暂存区（比如一个尴尬的视频或草稿），你可以这样做：

git reset HEAD [file]

示例：在目录中新建了一个bbb.txt，然后使用git add再撤销暂存

image-20250720085712419

image-20250720085719840

🔎 理解文件的四种状态（Untracked, Modified, Staged, Committed）

文件状态	含义
Untracked	Git 完全没记录过的文件，需手动用 git add 纳入管理
Modified	文件自上次提交后发生更改，还未加入暂存区
Staged	文件准备提交，已通过 git add 放入暂存区
Committed	文件已经保存进仓库，记录为一个正式快照

image-20250720085912461

✅ 提交修改并保存版本快照（Committing）

在上一节中，我们使用 git add 将文件放进了“暂存区”（也就是我们类比中的保险柜准备区）。接下来，正式的保存操作就是 git commit —— 这一步就像关上并锁好保险柜，记录快照，让我们可以随时回顾。

🔐 git commit: 正式保存当前改动

git commit -m "添加了豆腐食谱"

• -m 选项用于附加说明文字（提交信息），帮助你和他人理解这次修改做了什么。

• 提交操作只会保存那些已经 add 过的文件（即已进入暂存区的部分）。

💡 类比小结：

• git add：把文件放入保险柜准备区；

• git commit：把这些文件正式锁进保险柜，形成一个历史快照。

🕰️ git log 与 git show：查看历史记录和版本详情

为了查看之前提交的版本，可以使用log命令以及show命令:

🔍 查看提交历史：

git log         # 显示所有提交历史（详细）
git log --oneline  # 简洁版本，一行一个提交
git reflog      # 更侧重于操作历史，包括分支移动

👀 查看具体提交内容：

git show [commit_id]   # 查看指定提交的修改细节

🌟 示例：我们添加了 abtofu.txt 后提交，再查看历史

git add abtofu.txt
git commit -m "添加了abtofu.txt"
git log --oneline
git show HEAD

img

下图展示了 git log 输出的历史版本信息：

img

其中commit之后的字符串为版本号，末尾括号表示最新一次提交为master分支

git show 显示了具体提交内容，包括文件差异（diff）：

image-20250720090014555

🩹 修改最后一次提交（amend）

有时候你可能提交得太快，忘记加上一些文件，或者想修改刚刚写的提交信息。这时可以使用：

git add [forgotten-file]
git commit --amend

这会将刚才的提交覆盖（不是新增），并整合最新暂存的改动。

💡 注意： 若已将该提交推送到远程仓库，则不推荐使用 amend（会造成历史不一致）。

📸 示例演示：我先提交 bbb.txt，然后想补充漏掉的 forgotten_file.txt，于是我先 add，再使用 --amend：

image-20250720090028140

img

image-20250720090055146

image-20250720090118195

image-20250720090138476

image-20250720090146061

image-20250720090154581

♻️ 文件恢复（Restore）

修改错了？删错了？Git 的“后悔药”功能可以帮你找回文件。

🔙 恢复工作目录中的更改（未提交）

如果你误删、误改了文件，但还没提交，可以通过以下命令还原成最近一次提交的状态：

git restore [file]

🎯 示例：你误删了 a.txt，执行：

git restore a.txt

即可恢复（前提是你还没用 commit 把删除记录保存）。

⏪ 恢复到指定提交版本的文件

如果你已经提交了删除行为，但想从旧版本中恢复文件：

git restore --source=<commit> <file>

这样你可以从旧提交中“取出”这个文件，而不会改动现有提交记录。

📸 示例演示：我误删了 abtofu.txt 并提交，然后从早前的版本恢复它：

image-20250720090300205

随后我删除abtofu.txt并提交

image-20250720090307122

添加参数并恢复abtofu.txt

image-20250720090313994

📎 最终效果：文件回来了，但提交历史没有被改变！

image-20250720090330053

🔁 使用旧方式恢复文件（checkout）

git checkout 曾经用于文件恢复，但现在推荐使用 git restore，因为更清晰直观。

git checkout -- [file]

📌 此命令将文件恢复至最近一次提交时的状态，但已不建议在新版本 Git 中使用。

🖥 使用 GitHub Desktop 客户端创建与管理本地仓库

适合人群： Git / GitHub 初学者、希望图形化操作版本控制的用户

GitHub Desktop 是一款专为 Windows 和 macOS 用户打造的图形化 Git 客户端，它帮助你在不使用命令行的情况下完成大部分 Git 操作，包括创建仓库、提交文件、同步远程、管理历史版本等。

🌟 GitHub Desktop 的核心优势

1. 图形化界面：无需记忆繁复命令，操作直观可视，适合初学者入门。

2. 与 GitHub 网站高度集成：一键创建仓库、提交、发起 Pull Request 等功能，便捷管理开源项目。

3. 清晰的提交历史视图：以图形时间线展示每次改动，方便团队协作与版本回溯。

4. 多平台支持 & 免费开源：兼容 Windows / macOS，支持多账号切换。

🚨 温馨提示：GitHub Desktop 更适用于中小型项目、独立创作者、写作或研报类项目管理，也适合作为学习 Git 工作流的过渡工具。

🚀 快速上手 GitHub Desktop：从 0 创建一个仓库

🛠 1. 创建本地仓库（Initialize Repository）

打开 GitHub Desktop，点击首页按钮：

image-20250720091554086

填写相关信息：

• Name：仓库名称（如 web3-research-demo）

• Description：可选的简要描述

• Local Path：仓库在你电脑上的保存路径

• ✅ 你也可以选择是否初始化 .gitignore 和 README 文件

image-20250720091600034

点击 Create Repository 即可完成本地仓库的初始化！

📁 2. 追踪文件更改（Track Changes）与忽略文件（Ignore Files）

✅ 自动追踪修改

在对应目录中新建或修改一个文件，比如添加一个 sales.txt：

image-20250720091611223

回到 GitHub Desktop 界面，它会自动识别变动并显示在 Changes 区域：

image-20250720091618353

🚫 忽略文件与文件类型

GitHub Desktop 允许你右键选择要忽略的特定文件或文件类型：

• 忽略单个文件：右键点击 → Ignore

• 忽略某一类型（如全部 .doc 文件）：右键 → Ignore all

示例：创建 dash.doc 后，右键操作如下：

image-20250720091629800

系统会自动在 .gitignore 文件中添加对应规则。

✅ 3. 提交修改（Commit Changes）

完成修改后，需将改动提交至版本历史中。

步骤如下：

1. 在左下角输入此次提交的说明

2. 点击 Commit to main

image-20250720091646613

提交后，点击上方 History 标签页，即可查看提交记录和修改内容：

image-20250720091655657

🔁 4. 撤销操作（Undo / Discard）

GitHub Desktop 支持撤销两类操作：

❌ 撤销文件更改

对单个文件改动不满意？点击该文件旁的齿轮图标 → Discard changes 即可：

image-20250720091703762

系统会提示你确认操作：

image-20250720091711636

⏪ 撤销提交

提交错了？左下角点击 Undo 可撤销最近一次提交（但不会还原文件变动）：

img

📦 总结与比较：为什么推荐 GitHub Desktop？

功能	GitHub Desktop	Git Bash（命令行）
上手难度	✅ 低，适合新手	❌ 较高，需掌握命令
操作效率	✅ 快速点选，直观明了	⚠️ 更灵活但需输入命令
错误容忍度	✅ 支持可视化撤销	❌ 命令行操作失误代价较大
文件状态展示	✅ 图形时间线、diff 区块	❌ 需用多条命令手动查看
支持项目	个人项目、小团队	大型项目 / 自动化流程更优

对于 Web3 内容创作者、数据分析师或研究者来说，GitHub Desktop 提供了更为可控、简洁的文件版本管理方式，无需掌握太多命令行操作，也能完成常规的 Git 工作流。

🌿 分支管理

分支简介：为什么要使用分支？

在软件开发过程中，经常会同时进行多个工作：添加新功能、修复 bug、试验性开发等等。为了不让这些任务相互干扰，我们通常不会把所有的改动都直接写在主分支（main/master）上。这时候，就需要用到 Git 的分支功能了。

简单来说，分支就像是在主线（main）之外临时开辟的一条“副线”，你可以在副线上自由修改、提交、测试，不会影响到主线的稳定运行。任务完成后，你可以将副线的成果合并（merge）回主线中。

✨ 分支的优势

1. 并行开发：多个功能/任务可以同时在不同分支上独立进行。

2. 隔离风险：开发过程中出现问题，不会影响主分支；随时可以删除失败的分支重来。

3. 灵活合并：功能开发完成后，可以选择适当的时间将其合并进主分支。

4. 提升协作效率：团队成员可以基于同一个主线各自创建分支，协同开发互不干扰。

🌟 举例：你可以创建一个 feature/login 分支用于开发登录功能，另一个 bugfix/navbar 分支用于修复导航栏的 bug。开发完成后再分别合并回主分支。

image-20250720093000309

🧰 使用 Git Bash 创建和管理分支

我们将使用 Git Bash 来演示如何进行分支的基础操作，包括创建、切换、删除和合并等。

开始前我们先创建一个测试目录：

 mkdir gitdemo
 cd gitdemo/
 git init
 touch README
 git add README
 git commit -m '第一次版本提交'

image-20250720093014237

此时我们已经创建了一个新的本地 Git 仓库，并提交了第一个版本（README 文件）。默认情况下，Git 会生成一个名为 master（或 main）的主分支。

📄 创建/列出分支

git branch             # 列出本地所有分支，当前分支前带有 *
git branch -r          # 查看远程分支
git branch -a          # 查看本地 + 远程所有分支
git branch -v          # 查看各分支最后一次提交的信息
git branch --merged    # 查看已合并到当前分支的分支
git branch --no-merged # 查看尚未合并的分支

• 没有参数时，git branch会列出你在本地的分支。

img

意思就是，我们有一个叫做 master 的分支，并且该分支是当前分支。

当你执行 git init 的时候，默认情况下 Git 就会为你创建master分支。

• 如果我们要手动创建一个分支。执行 git branch (branchname) 即可。

例如：

git branch testing

此命令会基于当前所在的分支，创建一个名为 testing 的新分支。

img

🔄 切换分支

git checkout 分支名       # 切换到指定分支
git checkout -b 分支名     # 创建并切换到新分支（推荐）

切换分支时，Git 会将你的工作目录切换到该分支最后一次提交的状态。

示例：

首先检查在master分支下的文件只有README，然后我们切换到testing分支

image-20250720093038322

同样在testing分支下也只有README文件

我们创建一个新文件test.txt并提交

image-20250720093059719

切换回master分支，检查发现testing分支中新增的test.txt文件并没有出现在这里

image-20250720093108145

在 testing 分支中添加了 test.txt 文件并提交后，当你切换回 master 分支时，test.txt 并不会出现，因为两个分支是各自独立的。

🗑️ 删除分支

git branch -d 分支名    # 删除已经合并的分支
git branch -D 分支名    # 强制删除（即使未合并）

如我们要删除 testing 分支：

git branch -d testing

image-20250720093115204

这将在确认分支内容已合并的前提下删除 testing 分支。

🔀 合并分支：

git merge

一旦某分支有了独立内容，你终究会希望将它合并回到你的主分支。 你可以使用以下命令将任何分支合并到当前分支中去：

git merge <分支名>

注意，这里是把git merge命令后面的分支与当前的分支合并。

🔎 背后原理：

Git 会基于两个分支最近的共同祖先，以及两个分支的最后提交，自动生成一个新的合并提交（merge commit）。

📈 图示：

从 master 分支第 3 次提交处分出 develop 分支，两个分支分别继续各自的提交（到第 6 次和第 7 次）。执行 git merge develop 后，Git 自动生成第 8 次提交为合并点。

image-20250720093125018

git rebase

git rebase 会将当前分支的提交“挪动”到目标分支（如 master）的最新提交之后，避免生成额外的合并节点，适用于希望提交历史保持线性整洁的情况。

📈 图示对比：

rebase 会让你的提交历史看起来像是“直接在主分支后继续”，适合清晰回顾。

image-20250720093137135

⚔️ 合并冲突 Conflict

当两个分支对同一个文件的同一位置作出不同修改时，Git 就无法自动决定采用哪一个，这时就会出现合并冲突。

示例：合并冲突通常以类似下面的形式出现在代码中：

<<<<<<< HEAD
    // 这是开发者A的修改
    public void DeveloperA_Method()
    {
        // ...
    }
=======
    // 这是开发者B的修改
    public void DeveloperB_Method()
    {
        // ...
    }
>>>>>>> BRANCH_B

在这个例子中，HEAD是一个标记，表示当前版本的代码，而BRANCH_B是一个其他的分支，其中的代码被开发者B修改过。在HEAD和BRANCH_B之间的代码是冲突的，因为两个开发者都修改了同一部分的代码。

解决这种冲突通常需要人工干预，因为计算机无法确定哪种修改是更优的。开发者需要查看冲突的代码部分，然后手动选择他们认为更好的代码行，或者通过谈判来决定一个共同接受的解决方案。解决冲突后，可以使用版本控制系统（如Git）来提交合并后的代码。

⚙️ Git Bash 合并冲突示例

我们在 main 和 test 分支分别修改了 user.txt，在合并时出现冲突，Git 会提示你有哪些文件需要解决：

img

解决步骤：

1. 手动编辑冲突文件，删除冲突标记；

2. git add 文件名 标记冲突已解决；

3. git commit 完成合并提交。

🧩 使用 GitHub Desktop 客户端创建和管理分支

在现代协作式软件开发中，分支管理（Branching） 是不可或缺的部分。借助 GitHub Desktop 图形化界面，我们可以更方便地创建、切换、合并和删除分支，避免命令行的复杂性，特别适合初学者和视觉型用户。

📌 创建和查看分支

在 GitHub Desktop 中，新建一个仓库后，你可以在主界面顶部中间找到当前分支的名称（默认为 main），点击该名称会弹出分支管理菜单：

image-20250720093204106

点击 New branch 按钮，即可创建一个新的分支：

image-20250720093214888

你可以基于当前分支创建一个新分支，比如用于开发新功能或修复一个 bug。

🔄 分支切换

创建成功后，新分支将会出现在下拉菜单中。点击对应分支名即可完成切换：

image-20250720093221993

✅ 切换分支时，GitHub Desktop 会自动更新工作目录的内容，以匹配该分支最后一次提交的状态。

📝 在不同分支上进行文件操作

你可以在本地仓库对应的文件夹中修改或添加文件，例如创建一个 abab.txt 文件：

返回 GitHub Desktop，界面会自动检测到更改：

image-20250720093235164

添加提交说明后，点击 Commit to local-test-branch1 即可完成提交：

image-20250720093241827

你可以在 History 标签页中查看该分支的提交历史：

而在 main 分支中，并不会看到刚才的提交，说明你的更改已经正确地隔离在不同的分支中。

image-20250720093257143

这表示我们成功地在不同分支上完成提交操作。

🗑️ 删除分支

如果某个分支任务已完成或不再需要，你可以通过分支下拉菜单中右键点击目标分支，选择 Delete 来删除它：

image-20250720093304127

⚠️ 请注意：不能删除当前所在的分支，需先切换到其他分支再进行删除操作。

🔀 分支合并（Merge）

完成某个分支上的开发任务后，我们通常会将其合并回主分支（main）。点击分支栏中的 Choose a branch to merge into current branch：

image-20250720093311414

弹出合并窗口后选择你希望合并的目标分支：

image-20250720093321018

点击 Merge 后，将会把所选分支的提交整合进当前分支中。合并完成后，可以在 History 中看到合并记录：

image-20250720093328603

✏️ 修改分支名称

修改主分支默认名称

如果你想更改默认分支名（如将 master 改为 main），可以在设置页面的 Git 栏中进行更改：

image-20250720093335591

重命名任意分支

右键点击分支名，即可看到 Rename 选项：

image-20250720105048862

⚔️ 处理合并冲突

当两个分支对同一个文件做出不同修改时，合并可能引发冲突。我们来演示如何使用 GitHub Desktop 处理此类冲突。

示例：两个分支分别修改 user.txt

在 local-test-branch2 中创建 user.txt并输入：

image-20250720093406300

然后提交到local-test-branch2分支中

image-20250720093419416

提交之后可以查看历史记录

img

接着切换到 local-test-branch1，创建并对user.txt文件进行不同的修改：

image-20250720093440866

提交：

image-20250720093446831

查看历史记录

image-20250720093451834

最后我们合并两个分支到主分支，首先合并分支1到主分支

image-20250720093457053

可以看到历史记录的合并

image-20250720093506977

然后合并分支2，我们会看到如下警告信息

image-20250720093511739

可以在下拉栏中发现更多的选项

image-20250720093516976

这里就选择第一个选项

image-20250720093522682

选择合适的冲突解决方式，例如使用 RStudio 打开文件手动修改：

image-20250720093527825

修改文件内容解决冲突，例如合并两者的改动：

image-20250720093539709

保存文件后，回到 GitHub Desktop，它会检测到冲突已解决：

点击“Continue merge”继续合并流程，最后提交合并记录：

image-20250720093553638

合并完成后可以查看完整的提交历史：

image-20250720093605381

✅ 小结

GitHub Desktop 提供了一套完整的图形化分支管理工具，使得：

• 分支的创建、切换和合并更加直观；

• 文件更改可视化、提交流程清晰；

• 合并冲突可以通过外部编辑器手动解决，极大降低了出错风险。

对于不熟悉命令行的开发者来说，GitHub Desktop 是学习和掌握 Git 工作流的绝佳起点。

🌐 远程仓库管理

Git 的一个重要特性是它可以将代码仓库的副本存储在远程服务器上。这不仅让协作开发成为可能，还能作为备份手段，防止本地数据丢失。

🔍 回顾一下：我们之前提到，Git 的快照都存储在本地仓库的隐藏 .git/ 文件夹中。如果本地设备出现故障或数据丢失，所有提交记录可能会随之丢失。因此，我们需要远程仓库作为安全保障和协作平台。

🤝 GitHub 简介：你的远程仓库之家

GitHub 是一个广泛使用的代码托管平台，允许你将本地 Git 仓库同步到云端，便于分享、协作和备份。

• 对开源项目用户而言，GitHub 提供完全免费的仓库托管服务。

• 如果你想对代码保密，也可以选择私有仓库。

🚀 一步步创建你的 GitHub 仓库

Step 1：注册 GitHub 账号 前往官网：https://github.com/ 注册属于你的账号。

Step 2：新建一个远程仓库（如：test-repo） 点击右上角的 "+" → "New repository"，填写仓库名称，创建仓库：

image-20250720100028355

仓库创建成功后将看到如下页面：

image-20250720100036719

🧰 使用Git Bash管理远程仓库

以下是常用的远程仓库相关命令：

命令	功能说明
git remote add [name] [url]	添加一个远程仓库并起一个别名
git remote -v	显示当前所有远程仓库及其对应 URL
git clone [url]	克隆远程仓库到本地，包含全部历史
git push [remote] [branch]	将当前分支推送到远程仓库
git pull [remote] [branch]	拉取远程分支的最新更改并合并

🌍 添加远程仓库（git remote add）

在向远程仓库推送代码前，必须先告诉 Git 远程仓库的地址。

📝 添加命令格式：

注意：添加远程仓库之前请确保你当前的工作目录有一个Git仓库，如果没有需要用git init创建一个

git remote add [short-name] [remote-url]

• [short-name]：通常为 origin，表示默认远程仓库名称。

• [remote-url]：可以是 HTTPS 或 SSH 格式的 GitHub 仓库地址。

📌 示例：

git remote add origin https://github.com/zey9991/test-repo.git #HTTP
git remote add origin [e-mail]:zey9991/test-repo.git #SSH

⚠️ 注意：执行此命令前，请确保当前目录已是一个 Git 仓库（即包含 .git/ 目录）。如无，请使用 git init 初始化。

📷 添加远程仓库效果图：

image-20250720100112289

如果当前工作目录没有git仓库则会报错：

img

🔄 重命名、删除和查看远程仓库

操作	命令
查看远程仓库列表（含 URL）	git remote -v
重命名远程仓库	git remote rename old new
删除远程仓库	git remote remove [name]

示例输出如下：

image-20250720100126814

📥 克隆远程仓库到本地（git clone）

git clone 会下载远程仓库的完整历史记录并在本地创建一个对应目录。

git clone [remote-url]
git clone [remote-url] [directory-name]

克隆操作默认将远程仓库设置为名为 origin 的远程仓库。

📷 示例：

• 克隆 test-repo 到当前目录：

  git clone https://github.com/zey9991/test-repo.git

image-20250720100134253

打开对应目录可以发现test-repo已经复制完成：

image-20250720100140879

• 克隆并重命名本地目录：

  git clone https://github.com/zey9991/test-repo.git new-local-name

image-20250720100200793

image-20250720100206177

🔐 SSH Key 配置（用于免密连接 GitHub）

git clone支持https和ssh两种方式下载源码，当使用 SSH 格式的 URL 克隆或推送时，需要配置 SSH key 否则会遇到如下报错：

image-20250720100211854

第一步：检查用户名和邮箱

git config --global user.name
git config --global user.email
# 或使用 
git config --global --list

img

若未设置，请使用以下命令：

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

第二步：生成 SSH key

ssh-keygen -t rsa -C "你的GitHub邮箱"

执行命令后需要进行3次或4次确认：

1. 确认秘钥的保存路径（如果不需要改路径则直接回车）；

2. 如果上一步置顶的保存路径下已经有秘钥文件，则需要确认是否覆盖（如果之前的秘钥不再需要则直接回车覆盖，如需要则手动拷贝到其他目录后再覆盖）；

3. 创建密码passphrase（如果不需要密码则直接回车）；

4. 确认密码；

执行过程如下图：

image-20250720100245256

在指定的保存路径下会生成2个名为id_rsa（私钥）和id_rsa.pub（公钥）的文件：

img

第三步：将 SSH 公钥添加到 GitHub

1. 登录 GitHub → Settings → SSH and GPG keys

2. 点击 New SSH Key

3. 粘贴 id_rsa.pub 文件的全部内容，并保存

image-20250720100354923

image-20250720100408121

完成后你即可使用 SSH 协议免密码连接远程仓库：

git clone [e-mail]:zey9991/test-repo.git

📤 推送本地更改到远程仓库（git push）

git push <remote-name> <branch-name>

如：

 git push origin master

此命令表示将本地 master 分支的提交推送到远程 origin 仓库中。

📷 示例：新建并推送一个文件到远程仓库：

image-20250720100429489

image-20250720100433945

image-20250720100438819

推送成功后，GitHub 页面会提示可以创建 Pull Request 来合并代码：

image-20250720100443650

可以点击Compare & pulling request比较两个分支的改变：

image-20250720100448883

🔄 获取远程仓库的更新

当远程仓库发生变化时（比如他人推送了更新），你可以通过以下命令同步：

✅ git fetch

git fetch是将远程主机的最新内容拉到本地，用户在检查了以后决定是否合并到工作本机分支中。

 git fetch <remote-name>

如果只想取回特定分支的更新，可以指定分支名：

git fetch <remote-name> <branch-name> # 注意之间有空格

现在用git fetch获取test-repo仓库的更新

img

✅ git pull

其基本语法如下：

git pull <remote-name> <branch-name> #和git push的语法对应

• pull 等价于 fetch + merge

• 会直接将远程分支的最新提交合并到你当前分支中

📌 示例：从 origin 的 master 分支拉取并合并到当前分支：

git pull origin master

📌 高级用法：指定将远程分支合并到本地其它分支：

git pull origin master:branchtest

可以知道，git pull没有那么注重代码的安全性，比较适合队友之间熟悉的情况。例如假设我的合作伙伴已经向我们共享的远程仓库的 master 分支推送了一些修复 AI 启发式算法的提交。我碰巧知道这不会破坏我的代码，所以我可以立即拉取并将其合并到我的代码中。

🧠 总结

操作	命令
添加远程仓库	git remote add origin [url]
查看远程仓库列表	git remote -v
克隆远程仓库	git clone [url]
推送到远程	git push origin [branch]
获取远程更新（不合并）	git fetch origin
获取并合并更新	git pull origin [branch]

🖥️ 使用 GitHub Desktop 客户端管理远程仓库

对于不熟悉命令行操作的用户来说，GitHub Desktop 提供了一个直观易用的图形界面，能够轻松管理本地仓库与远程 GitHub 仓库之间的同步与协作。下面将带你快速上手这一工具的核心功能。

✅ 第一步：关联 GitHub 账户

首次打开 GitHub Desktop 时，你需要登录你的 GitHub 账户。点击 File > Options > Accounts，进入账户管理界面。

登录后，界面将显示你的 GitHub 用户名和头像，说明账户已经成功关联：

image-20250720100514581

📁 克隆已有的远程仓库到本地

如果你已经在 GitHub 上创建了一个仓库，想要将它同步到本地，可以按如下操作：

1. 在顶部菜单中点击 File → Clone repository

2. 在弹出的对话框中，切换到 GitHub.com 标签页

3. 你将看到与你账户关联的所有仓库，选择一个仓库

4. 指定要克隆到本地的路径，点击 Clone 开始下载

界面如下所示：

image-20250720100522718

等待片刻，仓库将被克隆到你设定的目录：

image-20250720100542432

⬆️ 提交并推送本地更改到远程仓库

首先，点击右上角的 Show in Explorer（Windows）或 Reveal in Finder（Mac），快速打开本地仓库文件夹：

image-20250720100553038

在文件夹中新建一个测试文件，如 newfile.txt：

image-20250720100557286

返回 GitHub Desktop，会自动检测到文件变动。你只需在底部填写提交说明（如 "添加测试文件"），然后点击 Commit to main 完成本地提交：

image-20250720100601887

接着点击右上角的 Push origin，将更改推送到 GitHub 上：

image-20250720100608642

几秒钟后，打开 GitHub 网页端仓库即可看到文件已经同步：

image-20250720100612941

🔄 获取远程仓库的最新更改

如果你的团队成员或自己从其他设备对仓库进行了修改，该如何在本地同步这些更新？

1. 先在网页端对仓库中的文件做出修改，比如编辑 newa.txt 并点击 Commit changes：

img

image-20250720100630203

回到 GitHub Desktop，点击工具栏上的 Fetch origin 拉取远程仓库状态：

image-20250720100635151

如果有变更，会提示你是否合并。点击 Pull origin 以将更新合并到当前分支：

img

合并完成后，你可以在 History 选项卡中查看所有提交记录和更新历史：

image-20250720100645905

本课总结

恭喜你完成本课学习！在这一课中，我们从零开始，全面梳理了版本控制系统的核心理念，并通过 Git 与 GitHub 两大工具，搭建起了你进行 Web3 投研、代码协作与内容管理的基础能力。

你不仅了解了 什么是版本控制系统（VCS），还清晰掌握了为何 Git 成为主流工具的原因。通过安装 Git 和 GitHub Desktop，并亲自搭建本地仓库，你已经完成了版本控制的第一步实战。

🧠 本课你学到了什么？

• 理解版本控制的意义：掌握了版本控制的基本概念，明白了其在团队协作、内容管理、代码追踪中的价值。

• 初识 Git 和 GitHub：区别两者的功能定位，理解“Git 负责本地版本管理，GitHub 实现远程协作”的基本逻辑。

• 三大核心区域的原理：深入理解工作区、暂存区和版本库之间的关系，为今后高效提交和管理修改打下基础。

• 掌握两种 Git 使用方式：

  • 通过 Git Bash 使用命令行管理版本控制，体验原生强大但稍具门槛的操作流程；

  • 通过 GitHub Desktop 使用图形界面轻松进行本地操作、分支管理与远程同步。

• 熟练进行分支管理：理解分支的作用，学习创建、切换、合并、删除分支，以及如何处理分支冲突。

• 实现本地与远程仓库同步：能够上传本地文件、拉取远程更新、完成完整的 Push / Pull 工作流，为未来协作开发打下基础。

🔜 接下来怎么做？

接下来，你可以聚焦于 如何将 Git 技能服务于 Web3 投研，包括如何：

• 构建结构化的项目资料仓库；

• 发布分析报告并进行版本追踪；

• 与他人协作管理项目研究进度；

• 结合 Git 与平台工具（如 GitBook、Mirror）打造你的 个人投研品牌。

无论你是写研报、做开源协作，还是管理自己的内容资产，Git 都将是你数字技能工具箱中不可或缺的一部分。

课后思考

1. 版本控制不仅是技术工具，也是思维方式

   传统的写作常常是“覆盖式”的，但 Git 的逻辑是“版本叠加”的。请思考：

   • 在撰写项目研报时，你是否会因为“怕写错”而迟迟不敢发布初稿？版本控制是否能帮助你减少这种心理负担？为什么？

   • 回顾一次你在 GitHub 上的修改操作，能否清晰描述一次从提交修改（commit）到推送（push）的过程？你觉得它在管理内容时比直接“存文件”好在哪里？

   • 如果一个团队用 GitHub 协作完成研报撰写，你认为在哪些环节会体现出 Git 的优势？

2. 内容管理平台的对比与选择

   我们之前已经介绍了 Substack、Mirror等平台，分别支持发布研报。请比较：

   • 你觉得 GitHub 最大的优势是哪些？它的“弱点”又可能是什么？（如：内容呈现友好度、读者互动方式、审美设计等）

   • 如果你要构建一个“专业可信”的内容主页（Content Portfolio），你会将 GitHub 放在怎样的位置？是底层数据管理？研报全文展示？还是专业信誉背书？

3. 思考你的作品的“可复用性”与“可持续性”

   GitHub 的一个强大价值在于“复用”和“协作”：

   • 如果你在 GitHub 上发布了一篇详尽的 DeFi 项目研报，并开源了数据分析脚本，你希望别人如何使用你的成果？

   • 如果你将这篇研报不断更新、维护，是否能成为一个“持续演化的知识资产”？你认为这和发布一次性文章有什么根本区别？

   • 请思考一个例子：你是否能设计一个模板化的投研仓库结构，方便后续的研报快速复用与分发？例如：/data/、/drafts/、/final/、README.md 等目录。

4. 未来想象：你愿意让别人“Fork”你的研报吗？

   Fork 是 GitHub 的一种机制，意味着他人可以在你的基础上“复制一份”进行再创作。请设想：

   • 如果你是一名投研作者，是否希望他人 Fork 并改写你的研报？你会设立什么样的使用许可或贡献方式？

   • 你觉得 Fork 是一种“抄袭”，还是一种“合作”？你会在自己的研报中主动开放这种机制吗？

   • 请尝试给你的 GitHub 仓库写一个 LICENSE 文件，定义你允许别人怎么用你的内容（可选 MIT、Creative Commons、或自定义说明）。

5. 开放性练习建议

   找到你曾经完成的一份项目分析内容（可以是 Word、Notion 或笔记本中的草稿），试着将它迁移到一个 GitHub 仓库中，并完成：

   1. 一次 Commit（写清楚你做了什么修改）；

   2. 写一个结构清晰的 README.md，说明研报核心观点、数据来源；

   3. 将它设置为公开仓库，并发送链接给一位朋友，看看他们是否能快速理解你的研究思路。

参考资料

1. CSDN：Git 本地仓库建立与远程连接教程（含常见错误处理）

2. 尚硅谷新版Git快速入门(3h迅速掌握git)_哔哩哔哩_bilibili

3. Using Git | CS 61B Spring 2018 (datastructur.es)

4. git ssh key配置-CSDN博客

内容声明

1. AI 协助声明 本书部分内容由人工智能工具（如 ChatGPT）协助整理和润色，具体包括：内容草拟、语言优化、结构调整等。所有输出均经作者人工审校，力求表达准确、逻辑清晰。 若您对 AI 参与创作有所顾虑，建议谨慎阅读与参考。

2. 署名与许可协议 除特别说明外，本书由 Peyton 撰写，隶属于 LYS Lab 研究团队原创发布，收录于项目 Web3-research-handbook（Web3 投研手册）。全文采用 Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International（CC BY-NC-ND 4.0） 协议共享。

   您可以在不修改内容、仅用于非商业用途的前提下自由转载和分享本书，但必须注明原作者与来源。 严禁擅自改编、删改或用于任何商业用途。作者及 LYS Lab 保留未来以其他方式授权或商用的全部权利。

   推荐署名格式示例：

   本文原载于《Web3-research-handbook（Web3 投研手册）》，由 Peyton 编写，隶属 LYS Lab，遵循 CC BY-NC-ND 4.0 协议发布。协议链接：https://creativecommons.org/licenses/by-nc-nd/4.0/deed.zh

3. 免责声明 所有内容仅供学习交流使用，不构成任何投资、法律或其他实务建议。如书中引用第三方数据或接口，请以其官方文档为准。

4. 内测与阶段性观点声明 本书目前处于内容内测与试行发布阶段，其结构、章节安排与论述视角均为作者在特定时间点下的思考成果，不代表最终定稿。 作者将根据行业变化、读者反馈及研究进展，保留对本书整体内容进行大幅度修改、重写或重组的权利，包括但不限于添加新章节、删除部分内容或调整行文风格。 本书的部分观点、方法论可能随着作者认知演进而变化，亦可能在未来版本中被修正、更新或彻底重构。敬请读者理解并持续关注最新版本。