Git & GitHub 老兵操作手册

Git & GitHub 老兵上手手册

用"作战日志 + 档案室"类比，快速上手版本管理 适用场景：公众号文章 · 个人定位分析 · 资产分析 · 微信小程序 · 个人网站 品牌：LeiFlow · 老雷慢慢说

老兵，git/github 不用先背命令，先把"直觉"建立起来最要紧。我把它类比成你最熟的作战日志 + 档案室，三张图给你讲透，再落到你手头的五件事上。

一、核心直觉（先记一句口诀）

口诀 仓库是柜子，提交是盖章的日志页，分支是备用方案，push/pull 是云端同步。 GitHub 不过是把柜子放到云上、按权限共享——你自己看叫"私有仓库"，公开给别人看叫"公开仓库"。

二、Git 核心概念类比

左边是 git 术语，右边是你能秒懂的老兵类比。

三、三种方式能力对比

一眼可见：本地文件夹几乎全是短板（靠手动命名 v1/v2/final 版，迟早乱）；Obsidian 写文章/笔记是强项，但版本管理和协作弱；Git+GitHub 在版本、同步、代码、协作上全面强，唯一代价是"上手门槛"要投入点时间，隐私靠"私有仓库"兜住。

图例：强 = 适合 / 中 = 一般 / 弱 = 短板（"上手门槛"那行反过来：低 = 容易）

四、老雷的最优策略

左边是你正在做的五类事，右边是我建议的工具组合。

核心结论：你不需要在"本地文件夹 / Obsidian / Git"里三选一，它们是分工不是替代—— Obsidian 是"写作主战场"（管怎么写得顺、连得清）； Git 是"时光机和保险柜"（管改动留痕、随时退回、丢不了）； GitHub 是"云端指挥部 + 协作入口"（私有当保险柜，公开还能白嫖 Pages 托管）。

一句话：Obsidian 写、Git 管版本、GitHub 私有做云端保险柜；代码类跑标准流程，资产只留本地。

五、第一次动手 · 操作手册

不用先啃命令，先在 Obsidian 仓库试水。以下 4 步即可把你的知识库变成"带时光机的档案柜"。

第 1 步：进到你的 Obsidian 库根目录

cd ~/你的Obsidian库路径

第 2 步：初始化仓库（相当于立一个档案柜）

git init

第 3 步：把当前所有文件收进第一次提交（盖第一枚章）

git add .
git commit -m "初版：公众号+定位文档"

第 4 步：在 GitHub 建一个私有仓库，把柜子推上去

git remote add origin https://github.com/你的名/你的库.git
git push -u origin main

日常用法（每次写完一段就做一次）

git add .
git commit -m "改了啥"

等于盖一次章。哪天想回到上周的稿子，用 git log 看记录、git checkout 翻回去——这就是你的"作战日志时光机"。

隐私红线（务必遵守） 资产分析那一块，建议永远留在本地 + Obsidian 私有 vault，连 GitHub 都别推。财务隐私这事，宁可少点便利，不能冒半点险。公开仓库只用于个人网站这类"本就该让人看"的内容。

LeiFlow · 老雷慢慢说 ｜ Git & GitHub 老兵上手手册 ｜ 本手册基于"作战日志 + 档案室"类比整理。

Git 与 GitHub 学习及 LeiFlow 项目管理策略

整理日期：2026 年 8 月 20 日
GitHub 账号：leiflowAI
适用项目：公众号文章、个人定位分析、资产分析、微信小程序、个人网站、AI 课程及视频内容

一、总体结论

最优策略不是在“本地文件夹、Obsidian、Git、GitHub”之间四选一，而是明确分工：

Obsidian 管思考，Git 管版本，GitHub 管远端代码与协作，敏感资料和大型媒体单独保管。

二、通过类比理解本地文件夹、Obsidian、Git 和 GitHub

把 LeiFlow 事业想象成一个作战体系：

特别注意：

• iCloud“同步当前状态”，误删也可能同步。
• Git“记录历史版本”，适合文字和代码。
• GitHub“保存远端 Git 仓库”，也提供协作和部署。
• 大视频、客户录音、客户资料不能简单依赖 GitHub。

Git 官方把一次提交定义为对项目状态的一次快照；git add 是选择哪些变化进入下一次快照，git commit 才是正式归档。Pro Git：记录变更

Git 的核心概念

继续用作战类比：

• repository / repo：一个独立任务的完整档案。
• 工作区：你桌上正在修改的材料。
• git add：把准备归档的文件放进“呈批夹”。
• git commit：签字归档，形成一个可追溯版本。
• branch：从当前方案分出一条试验路线。
• merge：确认试验可用，合并回正式方案。
• push：把本地档案送到 GitHub。
• pull：从 GitHub 取回最新档案。
• .gitignore：明确哪些文件永不归档。

一句话记忆：

改文件 → 看变化 → 选变化 → 做快照 → 传远端。

对应命令：

git status
git diff
git add 文件名
git commit -m "说明这次完成了什么"
git push

三、当前 LeiFlow 文件体系分析

1. Obsidian 已经是知识中枢

leiflow-obsidian 当前大约有 192 个文件，其中约 155 个为 Markdown 文件，已经形成：

学习思考 → 写作输出 → 保险主业 → 复盘反哺

leiflow-writing、leiflow-reflect 和视频脚本已经通过符号链接连接到 Obsidian。

但是，整个 Obsidian 库里同时存在：

• 客户沟通资料；
• 客户录音；
• 财务风险诊断 PDF；
• 核保预判和配置方案；
• 个人定位、文章与视频稿。

因此：

不要把整个 Obsidian 库推到 GitHub，即使是私人仓库。

私人 GitHub 仓库只允许本人和授权人员访问，但仍然是外部托管系统；私人仓库不能代替专业的客户资料管理与加密备份。GitHub 仓库可见性说明

2. 项目管理建议

四、结合五类工作的最优分工

flowchart LR
    A["灵感、学习、定位研究"] --> B["Obsidian 知识中枢"]
    B --> C["定稿与脱敏"]
    C --> D["文章内容仓库"]
    C --> E["个人网站仓库"]
    C --> F["小程序仓库"]
    D --> G["GitHub 私人仓库"]
    E --> G
    F --> G

    H["客户资料、真实资产数据"] --> I["加密业务存储与备份"]
    J["原始视频、录音、渲染文件"] --> K["媒体硬盘或云盘"]

1. 公众号文章

• 灵感、素材、草稿、复盘：放 Obsidian。
• 准备发布的最终稿：复制到 leiflow-dailywork。
• leiflow-dailywork 用 Git 记录每一期的修改。
• 未发布内容先使用私人 GitHub 仓库。
• 将来只把精选已发布文章开放展示。

建议：

Obsidian 是草稿源头，内容仓库是发布版本档案。

2. 个人定位分析

定位是不断迭代的认知，最适合放在 Obsidian。正式版本文档由 Git 记录 V1.0、V1.1、V2.0，不再依赖大量“最终版、最终版2”文件名。

3. 资产分析

分成两部分：

• 分析方法、计算公式、网页代码、脱敏示例：进入 Git。
• 真实账户、负债、身份证明、银行流水、数据库：不进入 GitHub。

debt-planner 已经有 Git 和一个非 GitHub 远端，不需要立即迁移；先学会看清现有历史和远端关系。

4. 微信小程序

leiflow-mini 应当使用 Git，并建立私人 GitHub 仓库。

推送前重点排除：

• project.private.config.json
• 密钥、AppSecret、Token
• 本地环境配置
• 客户档案和导出数据
• 云数据库备份

5. 个人网站

leiflow-website 是最好的 Git 入门项目：

• 文件少，容易理解。
• 每次改文案或页面都能马上看到效果。
• 出错容易回退。
• 后续可直接连接自动部署。
• 成熟后可以公开，成为技术能力和个人品牌展示。

五、一个任务对应一个仓库

不要建立一个巨大的 leiflow-all。

一个可以独立运行、独立发布或独立承担责任的项目，就是一个 Git 仓库。

建议最终形成：

leiflow-website        # 网站，可逐步公开
leiflow-mini           # 小程序，私人
leiflow-content        # 定稿文章与发布素材，私人
leiflow-debt-planner   # 资产分析工具，私人
leiflow-video-tools    # 视频生成代码和模板，私人
leiflow-workbench      # AI技能与工作流，私人

以下永远不要成为 GitHub 仓库：

leiflow-cases
leiflow-vpn
客户原始录音和视频
真实家庭资产数据
密钥、Token、AppSecret

视频仓库也不要直接上传大型媒体。Git 不擅长比较视频、音频和大型二进制文件；GitHub 建议大型二进制使用 Git LFS，并建议把程序生成文件放在 Git 之外。GitHub仓库限制、Git LFS说明

六、Git 在 Mac 上的安装与结构

当前 Mac 已经安装：

git version 2.50.1

GitHub Desktop、Obsidian、VS Code 也都已经安装，因此不需要重新安装 Git。

Git 的结构不是“另外建立一个总文件夹”，而是：

Mac 上安装一次 Git 程序
        │
        ├── leiflow-website/
        │      ├── .git/          ← 这个项目的版本数据库，隐藏目录
        │      ├── .gitignore     ← 不允许进入 Git 的文件
        │      ├── README.md
        │      └── index.html
        │
        └── leiflow-mini/
               ├── .git/
               ├── .gitignore
               ├── README.md
               └── miniprogram/

每执行一次：

git init

Git 就会在当前项目内部创建一个隐藏的 .git 文件夹。它里面保存：

• 提交历史；
• 分支；
• 文件版本；
• 远端地址；
• 暂存区信息。

.git 相当于这个项目自己的“黑匣子”。删除 .git 不会删除项目文件，但会丢失这个项目的全部 Git 历史。

七、Git 是否必须用终端

不必须。可以使用：

1. GitHub Desktop：最直观，适合入门。
2. VS Code：修改代码时顺手提交。
3. 终端：最清楚、能力最完整。

它们底层调用的都是同一个 Git。

建议：

前两周用 GitHub Desktop 理解流程，同时只学六个终端命令。

git status                 # 查看现在是什么状态
git diff                   # 查看具体改了什么
git add 文件名              # 选择进入本次归档的内容
git commit -m "修改说明"    # 生成一次本地版本
git log --oneline          # 查看历史
git push                   # 上传到 GitHub

GitHub Desktop 是操作面板，终端是直接下命令，两者不会产生两套仓库。

八、本地 Git 和 GitHub 的关系

flowchart LR
    A["本地项目文件夹"] --> B["本地 .git 版本库"]
    B -->|"git push"| C["GitHub 远端仓库"]
    C -->|"git pull"| B
    C --> D["分享、协作、部署、展示"]

即使断网，本地 Git 仍然可以：

• 查看修改；
• 提交版本；
• 建立分支；
• 恢复历史。

只有 push、pull、clone 等操作需要连接 GitHub。

九、leiflowAI 账号下的仓库规划

建议先建立：

github.com/leiflowAI/leiflow-website
github.com/leiflowAI/leiflow-mini

初始都设置为 Private。

leiflow-website

先设为私人，检查完成后可以改为公开。网站可以进一步使用 GitHub Pages 或其他平台部署。

GitHub 可以保存和发布网站源文件，但“GitHub 仓库”和“用户看到的网站”不是一回事：

• 仓库：保存源代码。
• 部署：把源代码生成可访问的网站。

leiflow-mini

保持私人仓库。GitHub 负责保存小程序代码，但不能代替微信小程序后台发布。正式上线仍要经过：

本地开发
→ Git 提交
→ GitHub 备份
→ 微信开发者工具上传
→ 微信后台审核与发布

上传前需要排除：

project.private.config.json
.env
.env.*
密钥、AppSecret、Token
客户资料
云数据库导出文件

十、AI 课程是否适合建立 GitHub 仓库

适合，但 GitHub 应当管理“课程生产工程”，而不是充当完整的卖课平台。

建议建立私人仓库：

leiflow-ai-course

适合放：

leiflow-ai-course/
├── README.md
├── syllabus/             # 课程大纲
├── lessons/              # 每节课程文字稿
├── exercises/            # 练习
├── prompts/              # 提示词模板
├── demos/                # 演示代码
├── slides-source/        # PPT源稿或Markdown
├── checklists/           # 检查清单
└── CHANGELOG.md          # 课程更新记录

不要放：

• 原始视频和大型成片；
• 学员姓名、作业和联系方式；
• 客户案例原始资料；
• 未经授权的书籍、课程材料；
• API Key、账号密码；
• 真实保险和资产资料。

推荐“两库策略”：

• leiflow-ai-course：私人，完整课程生产资料。
• leiflow-ai-course-samples：将来公开，放体验课、公开提示词和示例代码。

视频放网盘、视频平台或课程平台，GitHub 只保存脚本、字幕、代码和版本说明。

十一、Fork、Clone 和 Download ZIP 的区别

Fork：在 GitHub 上复制

假设别人有：

github.com/other/ai-course

点击 Fork 后，GitHub 上会出现：

github.com/leiflowAI/ai-course

这只是复制到自己的 GitHub 账号，尚未下载到 Mac。

类比：

Fork 是把别人的整套作战方案复制到你自己的云端办公室。

Clone：下载成 Git 仓库

要下载到本地，需要执行：

git clone https://github.com/leiflowAI/ai-course.git

或者在 GitHub Desktop 里选择 Clone Repository。

这时 Mac 上才会出现：

ai-course/
├── .git/
├── README.md
└── 其他文件

Clone 会下载项目文件和 Git 历史，并自动建立远端联系。

Download ZIP：只下载文件

点击 Download ZIP：

• 会下载当前文件；
• 不包含 .git 历史；
• 不能直接正常 pull、push；
• 更像拿到一份普通复印件。

因此：

想继续开发就 Clone；只想看文件就 Download ZIP。

十二、Fork 后的完整关系

flowchart TD
    A["原作者 GitHub 仓库"] -->|"Fork"| B["leiflowAI 账号下的仓库"]
    B -->|"Clone"| C["你的 Mac 本地仓库"]
    C -->|"Commit"| C
    C -->|"Push"| B
    B -->|"Pull Request"| A

通常还会有两个远端名称：

origin    你的 Fork：leiflowAI/项目名
upstream  原作者的仓库

• 从 upstream 获取原作者更新。
• 向 origin 上传自己的修改。
• 如果想把修改贡献回去，再提交 Pull Request。

十三、最快上手路线

第一阶段：只在网站项目学习本地 Git

先掌握六个动作：

git status
git diff
git add 文件名
git commit -m "更新首页个人定位文案"
git log --oneline
git restore --staged 文件名

练习任务：

1. 给网站首页改一句介绍。
2. 查看修改前后差异。
3. 提交一次。
4. 再改一次。
5. 查看两次提交历史。
6. 恢复或比较旧版本。

第二阶段：通过 GitHub Desktop 连接私人仓库

1. 添加 leiflow-website 本地仓库。
2. 创建 GitHub 私人仓库。
3. Publish/Push 到 GitHub。
4. 每次修改前 Fetch/Pull，修改后 Commit/Push。

GitHub 官方也以 GitHub Desktop 的“分支—提交—发布—Pull Request”作为入门路线。GitHub Git入门

第三阶段：再学习分支

只有在下面这些场景使用分支：

• 网站大改版；
• 小程序增加新功能；
• 尝试新的文章结构；
• AI 修改范围较大，尚未确认效果。

例如：

git switch -c feature/new-homepage

小改错别字、日常保存文章，不必每次建分支。

十四、当前确定的双路线实操计划

是的：LeiFlow-website 和 LeiFlow-mini 是两个独立项目，建议在 GitHub 上分别建立两个对应仓库。

但它们不是“同时自动出现”的。需要先理解三个独立对象：

flowchart LR
    A["本地普通文件夹"] -->|"git init"| B["本地 Git 仓库"]
    B -->|"git remote add origin"| C["GitHub 远端仓库"]
    B -->|"git push"| C
    C -->|"git pull"| B

三个独立对象

1. 本地普通文件夹：保存网站、小程序或课程的实际文件。
2. 本地 Git 仓库：普通文件夹执行 git init、生成隐藏的 .git 后形成。
3. GitHub 远端仓库：位于 GitHub 服务器上的独立仓库。

本地文件夹和 GitHub 仓库不会因为名称相同就自动产生联系。真正建立联系的是：

git remote add origin GitHub仓库地址

其中：

• remote：远端仓库；
• origin：给这个远端地址取的默认简称；
• GitHub 仓库地址：明确告诉本地 Git 要连接到哪里。

建立连接之后，仍然要通过下面的命令传输已经提交的版本：

git push
git pull

因此，完整逻辑不是“两边同名就自动连接”，而是：

先建立本地 Git 仓库
+
先建立 GitHub 远端仓库
+
用 origin 保存远端地址
+
通过 Push / Pull 传输版本

普通 git push 本身不会凭空创建 GitHub 仓库。使用 GitHub Desktop 的 Publish repository 或 GitHub CLI 时，看起来像是“一步自动创建”，实际仍然是工具先调用 GitHub 创建远端仓库，再建立 origin，最后执行 Push。

两种先后顺序

为了同时理解两个方向，采用以下两条路线各练习一次：

flowchart TD
    A["路线一：GitHub 优先"] --> B["在 GitHub 创建 leiflow-ai-course"]
    B --> C["Clone 到 Mac 本地"]
    C --> D["本地修改、Commit、Push"]

    E["路线二：本地优先"] --> F["本地已有 leiflow-website / leiflow-mini"]
    F --> G["检查 .gitignore 并完成本地 Commit"]
    G --> H["在 GitHub 创建空仓库"]
    H --> I["建立 origin 连接并 Push"]

这两条路线最后得到的结构完全相同：

本地 Git 仓库
↕ Push / Pull
GitHub 远端仓库

区别只在于第一步从哪一端开始。

路线一：AI Course 采用 GitHub 优先

当前选择先做 AI Course。建议 GitHub 仓库名称统一使用小写：

leiflow-ai-course

本地已经存在一个空文件夹：

/Users/yulei/leiflow-ai-course

因为它目前是空的，可以把 GitHub 仓库直接 Clone 到这个位置。

第一步：在 GitHub 创建仓库

登录 leiflowAI，选择 New repository，并填写：

Owner：leiflowAI
Repository name：leiflow-ai-course
Visibility：Private
Add a README file：勾选
.gitignore template：None
License：None

这里可以勾选 README，因为采用的是 GitHub 优先路线。GitHub 会用 README 生成第一次远端提交，随后 Clone 会把这段历史完整下载到本地。

第二步：Clone 到现有空文件夹

GitHub 仓库创建完成后，在终端执行：

git clone https://github.com/leiflowAI/leiflow-ai-course.git /Users/yulei/leiflow-ai-course

Clone 会一次完成：

• 下载 GitHub 上的 README 和提交历史；
• 在本地文件夹中创建 .git；
• 自动把 GitHub 仓库连接为 origin；
• 自动建立本地 main 与远端 main 的关系。

第三步：验证 Clone 结果

cd /Users/yulei/leiflow-ai-course
git status
git remote -v
git log --oneline
ls -la

应当看到：

• git status 显示位于 main 分支；
• git remote -v 显示 leiflowAI/leiflow-ai-course.git；
• git log --oneline 显示创建 README 的第一次提交；
• ls -la 能看到隐藏的 .git 文件夹。

第四步：完成第一次本地修改和 Push

在 README 中补充一段 AI 课程说明，然后执行：

git status
git diff
git add README.md
git commit -m "完善 AI 课程项目说明"
git push

刷新 GitHub 页面，如果能看到新的 README 内容和提交记录，就完成了完整闭环：

GitHub 创建
→ Clone 到本地
→ 本地修改
→ Commit
→ Push 回 GitHub

路线二：网站和小程序采用本地优先

网站当前状态

leiflow-website 当前已经：

• 存在 .git；
• 存在 .gitignore；
• 已有一次本地提交；
• 当前工作区干净；
• 尚未连接 GitHub 远端。

因此，网站不需要再次执行 git init，也不需要重新提交全部文件。后续步骤是：

1. 在 GitHub 创建名为 leiflow-website 的 Private 空仓库。
2. 不要勾选 README、.gitignore 和 License。
3. 在本地建立远端连接并 Push。

cd /Users/yulei/leiflow-website
git remote -v
git remote add origin https://github.com/leiflowAI/leiflow-website.git
git push -u origin main

小程序当前状态

leiflow-mini 当前已经：

• 存在 .git；
• 位于 main 分支；
• 尚无任何 Commit；
• 尚无 GitHub 远端；
• 尚无 .gitignore；
• 所有项目文件都处于未跟踪状态。

因此，小程序的安全顺序是：

先建立 .gitignore
→ 检查配置文件和敏感信息
→ 完成第一次本地 Commit
→ 在 GitHub 创建 Private 空仓库
→ 建立 origin
→ Push

暂时不要在小程序目录直接执行 git add .。

十五、关于 .git 和 .gitignore 的增补说明

1. 为什么有些项目没有 .gitignore

终端执行：

git init

正常情况下只创建 .git 文件夹，不会自动创建 .gitignore。

如果某个项目同时出现了 .gitignore，它通常是之前由以下来源之一创建：

• 项目脚手架或模板；
• GitHub Desktop；
• VS Code 或其他开发工具；
• AI 编程工具；
• 人工创建。

2. 两者的结构区别

项目文件夹
├── .git/          # Git自动创建的版本数据库
├── .gitignore     # 人工制定的“不纳入Git”名单
├── README.md
└── 其他项目文件

.git：

• 由 git init 创建；
• 是一个文件夹；
• 保存提交历史、分支和版本信息；
• 不应该手动编辑里面的内容。

.gitignore：

• 是一个普通文本文件；
• 通常需要自己创建；
• 告诉 Git 哪些文件不要追踪；
• 不会删除被忽略的本地文件。

它们以 . 开头，在 Mac Finder 里属于隐藏文件。可以按：

Command + Shift + .

显示或隐藏。

3. 当前三个项目的实际状态

网站现有的 .gitignore 内容是：

.DS_Store
*.key

含义：

• .DS_Store：忽略 Mac 自动生成的目录信息文件。
• *.key：忽略所有以 .key 结尾的密钥文件。

4. 小程序建议的 .gitignore

# Mac自动生成文件
.DS_Store

# 微信开发者工具私人配置
project.private.config.json

# 环境变量和密钥
.env
.env.*

# 依赖目录
node_modules/
miniprogram_npm/
cloudfunctions/**/node_modules/

# 日志文件
*.log

提交前还要人工检查：

miniprogram/envList.js
project.config.json

确认里面没有 AppSecret、Token、密码或客户数据。

5. Docs 建议的 .gitignore

# Mac自动生成文件
.DS_Store

# 临时文件
*.tmp
*.bak

创建 .gitignore 后，先检查再提交：

git status
git add .
git status

第二次 git status 是为了确认“即将提交的文件”是否正确。确认后才执行：

git commit -m "初始化 LeiFlow 文档库"

6. .gitignore 的时机

.gitignore 最好在第一次 git add 和 git commit 之前建立。

如果某个文件已经被 Git 跟踪，后来再把它写进 .gitignore，Git 不会自动停止跟踪它。当前 Mini 和 Docs 都还没有第一次提交，正是建立 .gitignore 的最佳时机。

十六、项目管理原则（阶段总结）

1. Obsidian 继续做唯一知识中枢，不整体上传 GitHub。
2. 从 leiflow-website 开始学 Git，因为最小、最直观、风险最低。
3. 代码项目一项目一仓库，默认私人。
4. 公众号草稿在 Obsidian，定稿进入内容仓库。
5. 客户资料、真实资产数据、VPN 配置永不进入 GitHub。
6. 视频代码进 Git，原始视频和渲染文件进媒体存储。
7. 避免依赖现有符号链接做 Git 备份：Git 通常只记录链接本身，不会把链接目标中的文章一起上传。
8. GitHub 不是备份全部人生资料的网盘，而是经过筛选的项目版本库。

十七、AI Course 的 GitHub 优先实操复盘

实操日期：2026 年 8 月 20—21 日
GitHub 账号：leiflowAI
仓库：leiflow-ai-course
本地目录：/Users/yulei/leiflow-ai-course

这次实操选择了“GitHub 优先”路线：先在 GitHub 建立远端仓库，再 Clone 到 Mac 本地。

flowchart LR
    A["GitHub 创建私人仓库"] --> B["GitHub 创建 README"]
    B -->|"git clone"| C["Mac 本地仓库"]
    C --> D["修改 README"]
    D --> E["Add + Commit"]
    E -->|"Push"| B

1. 为什么 GitHub 空仓库下会显示两组命令

GitHub 创建一个完全空的仓库后，会给出两类快速设置命令。

第一类是在本地创建新仓库再推送：

echo "# leiflow-ai-course" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/leiflowAI/leiflow-ai-course.git
git push -u origin main

适合：

• 本地已有普通文件夹；
• 本地还没有 .git；
• 准备采用本地优先路线。

第二类是推送已经存在的本地 Git 仓库：

git remote add origin https://github.com/leiflowAI/leiflow-ai-course.git
git branch -M main
git push -u origin main

适合：

• 本地已经执行过 git init；
• 本地已经有 Commit；
• 只是尚未连接 GitHub。

本次目标是练习“GitHub 优先 → Clone”，因此这两组命令都没有采用。实际操作是先在 GitHub 创建 README.md 和第一次提交，再执行 Clone。

2. Clone 到本地

git clone https://github.com/leiflowAI/leiflow-ai-course.git /Users/yulei/leiflow-ai-course

Clone 不只是下载文件，它会一次完成：

• 创建本地项目文件夹；
• 下载远端文件；
• 下载 Git 提交历史；
• 创建隐藏的 .git；
• 自动添加名为 origin 的远端地址；
• 建立本地 main 与远端 origin/main 的跟踪关系。

验证命令：

cd /Users/yulei/leiflow-ai-course
ls -la
git status
git remote -v
git log --oneline

初次 Clone 成功时得到：

本地：main
远端：origin/main
状态：working tree clean
文件：.git、README.md

3. 第一次修改、提交和上传

修改 README 后执行：

git status
git diff
git add README.md
git status
git commit -m "docs: 补充 AI 课程目标"
git log --oneline --decorate -3
git push

各步骤含义：

4. Commit 是叠加历史，不是两份互相冲突的文件

第一次提交添加了初始 README，第二次提交又增加课程目标。GitHub Desktop 点击某条 Commit 时，只显示“这一次增加或删除了什么”，不是显示 README 的最终全文。

第一次提交：增加3行
+
第二次提交：增加4行
=
最新README：共7行

因此，历史列表中的两次提交是前后叠加关系，不是两个账号各有一份互相冲突的 README。

十八、账号登录、提交作者和远端仓库是三件事

这次实操中最重要的认识之一，是 Git 和 GitHub 存在三套彼此独立的身份信息。

flowchart TD
    A["Git提交作者"] --> A1["user.name + user.email"]
    B["GitHub上传权限"] --> B1["HTTPS凭据或SSH密钥"]
    C["上传目标"] --> C1["origin远端地址"]

1. 为什么切换 GitHub Desktop 账号后，旧 Commit 仍显示 yuleiww

Commit 生成时，作者姓名和邮箱已经写入提交对象。之后切换 GitHub Desktop 登录账号，不会自动改写已经存在的 Commit。

当最后一次提交还没有 Push 时，可以安全修正作者：

cd /Users/yulei/leiflow-ai-course
git config user.name "leiflowAI"
git config user.email "leiflow@agent.qq.com"
git commit --amend --reset-author --no-edit
git log -1 --format=fuller

这里不使用 --global，表示身份只应用于当前仓库，避免影响 yuleiww 账号下的其他项目。

参数含义：

• --amend：修改最后一次提交；
• --reset-author：使用当前仓库配置的姓名和邮箱；
• --no-edit：保留原提交说明和文件内容。

Amend 后 Commit 编号改变是正常现象，因为作者信息也是 Commit 内容的一部分。

2. 为什么第一次终端 Push 没有同步

终端停在：

Username for 'https://github.com':

这不是网络速度问题，而是 HTTPS 远端在等待身份验证。此时 Push 尚未完成，本地通常会显示：

main...origin/main [ahead 1]

含义是本地比 GitHub 多一个提交，但尚未上传。GitHub 终端操作不能使用普通网页登录密码，需要 Token、凭据管理器或 SSH。

3. GitHub Desktop 在本次实操中的作用

GitHub Desktop 用图形界面完成了：

• 从 yuleiww 退出；
• 登录 leiflowAI；
• 添加本地 leiflow-ai-course 仓库；
• 识别本地领先一个提交；
• 点击 Push origin 完成上传。

GitHub Desktop 不是必需工具，它只是 Git 的图形操作面板。终端和 GitHub Desktop 操作的是同一个本地 .git。

十九、为 leiflowAI 配置专用 SSH

由于同一台 Mac 同时使用 yuleiww 和 leiflowAI 两个 GitHub 账号，为 leiflowAI 配置了专用 SSH 密钥和账号别名，避免终端误用另一个账号。

flowchart LR
    A["Mac本地仓库"] --> B["SSH别名 github-leiflowai"]
    B --> C["专用私钥 id_ed25519_leiflowAI"]
    C --> D["GitHub账号 leiflowAI"]

1. 已有环境检查

Mac 原来已经存在：

~/.ssh/id_ed25519
~/.ssh/id_ed25519.pub
~/.ssh/config

原密钥归属未确认，因此没有覆盖或复用，而是新建专用密钥。

2. 生成专用密钥

ssh-keygen -t ed25519 -C "leiflow@agent.qq.com" -f ~/.ssh/id_ed25519_leiflowAI

生成：

私钥：~/.ssh/id_ed25519_leiflowAI
公钥：~/.ssh/id_ed25519_leiflowAI.pub

安全规则：

• 私钥绝不上传、复制或发送给任何人；
• 公钥 .pub 可以添加到 GitHub；
• 建议为私钥设置口令；
• 输入口令时终端不显示字符是正常现象。

3. SSH 账号别名配置

在保留原 VPN 配置的基础上，~/.ssh/config 增加：

# GitHub account: leiflowAI
Host github-leiflowai
    HostName github.com
    User git
    AddKeysToAgent yes
    UseKeychain yes
    IdentityFile ~/.ssh/id_ed25519_leiflowAI
    IdentitiesOnly yes

关键配置含义：

• Host github-leiflowai：自定义账号别名；
• HostName github.com：实际仍连接 GitHub；
• IdentityFile：只使用 leiflowAI 专用私钥；
• IdentitiesOnly yes：不尝试其他账号密钥；
• UseKeychain yes：由 Mac 钥匙串保存密钥口令。

4. 把密钥加入 SSH Agent 和 Mac 钥匙串

eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519_leiflowAI
ssh-add -l

Agent pid 12345 中的数字只是进程编号，每次启动都可能不同。例如出现 Agent pid 29906 完全正常。

5. 把公钥添加到 GitHub

复制公钥：

pbcopy < ~/.ssh/id_ed25519_leiflowAI.pub

GitHub 网页路径：

leiflowAI头像
→ Settings
→ SSH and GPG keys
→ New SSH key

填写：

Title：Yulei MacBook Pro - leiflowAI
Key type：Authentication Key
Key：粘贴公钥

粘贴内容应是一整行，以 ssh-ed25519 开头，以密钥注释邮箱结尾。

6. 测试 SSH 身份

ssh -T git@github-leiflowai

成功结果：

Hi leiflowAI! You've successfully authenticated, but GitHub does not provide shell access.

其中：

• Hi leiflowAI!：GitHub识别到正确账号；
• successfully authenticated：身份认证成功；
• does not provide shell access：GitHub只提供Git服务，不提供普通服务器终端，这是正常说明。

7. 把仓库远端从 HTTPS 改成 SSH

原地址：

https://github.com/leiflowAI/leiflow-ai-course.git

修改命令：

cd /Users/yulei/leiflow-ai-course
git remote set-url origin git@github-leiflowai:leiflowAI/leiflow-ai-course.git
git remote -v

修改后：

origin  git@github-leiflowai:leiflowAI/leiflow-ai-course.git (fetch)
origin  git@github-leiflowai:leiflowAI/leiflow-ai-course.git (push)

验证下载与上传通道：

git fetch origin
git status
git push

成功状态：

Your branch is up to date with 'origin/main'.
Everything up-to-date

Everything up-to-date 不是没有执行，而是说明 SSH Push 已成功连接，只是当时没有新的提交需要上传。

二十、AI Course 的 .gitignore 实操

VMark 编辑器在仓库中生成了本地辅助目录：

.vmark/

它不属于课程内容，不应该提交到 GitHub。因此，在项目根目录创建 .gitignore：

# Mac系统文件
.DS_Store

# VMark编辑器本地数据
.vmark/

随后提交并上传：

cd /Users/yulei/leiflow-ai-course
git add .gitignore
git commit -m "chore: 忽略本地编辑器文件"
git push
git status

最终理想状态：

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

二十一、以后是否每个仓库都要重新配置 SSH

不需要。SSH 密钥服务于“一台设备上的一个 GitHub 账号”，不是服务于某一个仓库。

flowchart TD
    A["Mac + leiflowAI：配置一次SSH"] --> B["leiflow-ai-course"]
    A --> C["leiflow-website"]
    A --> D["leiflow-mini"]
    A --> E["未来其他leiflowAI仓库"]

1. GitHub 优先的新仓库

以后在 leiflowAI 下建立远端仓库，直接使用专用别名 Clone：

git clone git@github-leiflowai:leiflowAI/仓库名.git

例如：

git clone git@github-leiflowai:leiflowAI/leiflow-ai-course-samples.git

Clone 会自动建立正确的 SSH origin，不再生成密钥或重新登记公钥。

2. 本地优先的网站仓库

在 GitHub 建立 Private 空仓库后：

cd /Users/yulei/leiflow-website
git remote add origin git@github-leiflowai:leiflowAI/leiflow-website.git
git push -u origin main

以后只需：

git pull --ff-only
git push

3. 本地优先的小程序仓库

小程序应先建立 .gitignore、检查敏感文件并完成第一次本地 Commit，然后连接：

cd /Users/yulei/leiflow-mini
git remote add origin git@github-leiflowai:leiflowAI/leiflow-mini.git
git push -u origin main

不得提交：

• project.private.config.json；
• AppSecret、Token、密码；
• 客户资料；
• 云数据库导出文件；
• .env 和其他敏感环境配置。

二十二、日常最简终端工作流

完成一次性配置后，日常工作不再复杂。

flowchart LR
    A["Pull领取最新版本"] --> B["本地编写和保存"]
    B --> C["Status + Diff检查"]
    C --> D["Add选择文件"]
    D --> E["Commit本地归档"]
    E --> F["Push上传GitHub"]

开始工作前：

cd /Users/yulei/leiflow-ai-course
git pull --ff-only

22.1 带注释的日常安全版命令

下面这组命令适合日常直接对照执行。示例使用 AI 课程仓库；如果操作小程序或网站，只需替换第一行的文件夹名称。

# 1. 进入本地项目文件夹
cd ~/leiflow-ai-course

# 2. 开始工作前，先安全地领取 GitHub 上的最新提交
git pull --ff-only
# 作用：把远端的新提交同步到本地。
# --ff-only 表示“只允许快进更新”；如果本地和远端已经分叉，Git 会停止并提示，而不会擅自合并。
# 注意：它不是“只下载有变化的文件”，也不是上传命令。

# 3. 查看整个仓库目前的状态
git status
# 作用：查看哪些文件被修改、哪些是新文件、哪些已经进入暂存区，以及本地分支是否落后或领先远端。

# 4. 查看还没有放入暂存区的具体修改
git diff
# 作用：逐行检查工作区的变化；绿色通常表示新增，红色通常表示删除。

# 5. 选择这一次准备提交的文件（请把 README.md 换成真实文件名）
git add README.md
# 作用：把指定文件放入暂存区，相当于把它装进“本次归档箱”。
# 初学阶段优先写具体文件名，比直接使用 git add . 更稳妥。

# 6. 检查已经放入暂存区、即将提交的具体内容
git diff --staged
# 作用：预览下一次 Commit 到底会包含什么。

# 7. 再检查一次文件清单
git status
# 作用：确认暂存区里只有这一次真正想提交的文件。

# 8. 创建一个本地版本记录
git commit -m "docs: 补充第一课课程大纲"
# 作用：把暂存区内容保存成一次本地 Commit；引号内写清楚“这次完成了什么”。

# 9. 把本地新 Commit 上传到 GitHub
git push
# 作用：上传尚未推送的 Commit；它不会把所有本地文件重新完整上传一遍。

# 10. 上传后验证结果
git status
# 理想结果：working tree clean，并且本地分支与 origin/main 一致。

git log --oneline --decorate -5
# 作用：查看最近 5 次提交，并确认 main 与 origin/main 是否指向同一个 Commit。

这组命令可以记成一条流水线：

进入仓库 → Pull 领取 → Status 检查 → Diff 审稿
         → Add 装箱 → Diff --staged 验箱 → Commit 本地归档
         → Push 上传 → Status / Log 验收

22.2 常用检查和安全撤销命令

# 查看当前所在分支
git branch --show-current

# 查看本地仓库连接到了哪个 GitHub 仓库
git remote -v

# 查看最近 5 次提交，以及本地和远端分支的位置
git log --oneline --decorate -5

# 把误放进暂存区的文件取出来，但保留文件中的本地修改
git restore --staged README.md

# 查看暂存区是否已经清空，或还剩下哪些文件
git status

其中，git restore --staged README.md 可以理解为“把文件从本次归档箱中拿出来”，不会删除你已经写入文件的内容。取出后可以继续修改，也可以重新选择要提交的文件。

22.3 首次连接仓库时才需要的命令

下面这些不是每天都要执行，而是在新建或首次连接仓库时使用。

GitHub 优先：把 GitHub 上已经存在的仓库第一次下载到本地。

# 只在第一次把仓库下载到本地时执行
git clone git@github-leiflowai:leiflowAI/leiflow-ai-course.git

本地优先：本地项目已经存在，需要第一次连接 GitHub 空仓库。

# 只在当前项目还不是 Git 仓库时执行一次
git init

# 把默认分支统一命名为 main
git branch -M main

# 只添加一次远端连接；请替换为当前项目真实仓库名
git remote add origin git@github-leiflowai:leiflowAI/leiflow-mini.git

# 第一次上传，并让本地 main 记住对应的远端分支
git push -u origin main

第一次成功执行 git push -u origin main 后，日常上传只需运行 git push。

22.4 初学阶段的安全边界

1. 优先使用 git add 具体文件名。只有确认 .gitignore 已经设置好，并且用 git status 检查过全部文件后，才使用 git add .。
2. 如果 git pull --ff-only 拒绝执行，说明本地与远端可能已经分叉。先停止操作并查看 git status，不要直接强制推送。
3. git restore 文件名 会丢弃该文件尚未提交的本地修改，它和 git restore --staged 文件名 不是一回事。
4. git reset --hard 和 git clean -fd 可能直接丢失未提交内容。初学阶段不要自行执行，确有需要时先备份并检查目标。
5. 遇到报错时，先保留终端原始信息，再运行 git status 和 git remote -v，通常就能判断问题发生在文件、分支还是远端连接。

22.5 命令作用速查表

推荐习惯：

1. 开始工作前先 Pull；
2. Commit 前查看 Status 和 Diff；
3. 初学阶段优先 git add 文件名，避免把无关文件一起加入；
4. 一次 Commit 只表达一个明确变化；
5. Commit 说明写“完成了什么”，不要只写“修改”“更新”；
6. 工作结束后 Push；
7. Push 后再次运行 git status，确认本地与远端一致。

GitHub Desktop 可以保留作为查看历史、差异和紧急认证的图形辅助工具，但不是日常上传下载的必经环节。终端已经能够独立完成 Clone、Pull、Commit、Push、分支、合并和故障排查。

二十三、更新后的最终结论

1. Git 的复杂配置主要发生在第一次。 安装、身份、远端和 SSH 配置完成后，日常只有 Pull、修改、Commit、Push。
2. GitHub Desktop 和终端不是两套仓库。 它们操作的是同一个本地 .git，可以交替使用。
3. Commit 作者、GitHub认证账号和 origin 是三件独立的事。 出现账号不一致时分别检查，不能混为一谈。
4. leiflowAI 的专用 SSH 已经是一项可复用基础设施。 网站、小程序、AI课程及未来仓库都复用 github-leiflowai，无需重复生成密钥。
5. GitHub 优先适合新项目，Clone 一次即可。 本地优先适合已经存在的项目，建立空远端后连接 origin。
6. 每个独立项目一个仓库，默认 Private。 需要展示或协作时再有选择地公开。
7. 敏感资料、大型视频和本地密钥不进入 GitHub。 .gitignore 应在第一次 Commit 前建立。
8. LeiFlow 的推荐工作体系保持不变：Obsidian 管思考，Git 管版本，GitHub 管远端项目，敏感资料与大型媒体单独保管。