Git on DK Blog

Git 子模块的核心：不是复制代码，而是固定引用一个仓库

Mon, 15 Jun 2026 00:00:00 +0000

Git 子模块的核心：不是复制代码，而是固定引用一个仓库

我第一次真正注意到 Git 子模块，是在看当前这个博客项目的时候。

项目根目录里有一个 .gitmodules 文件。刚看到它时，很容易以为这只是 Git 的某个额外配置。但继续看目录结构就会发现，它其实说明了一件更重要的事：这个项目里有一部分代码，并不属于主仓库本身，而是来自另一个 Git 仓库。

以博客项目为例，主仓库通常负责这些内容：

文章内容
站点配置
部署脚本
自己写的少量定制代码

但主题、模板或者某个公共组件，可能来自另一个开源仓库。这个时候就会出现一个问题：主项目需要使用那份代码，但又不想真的把那份代码复制进来。

Git 子模块就是为了解决这个问题。

先看一个具体场景

假设我有一个博客项目，仓库叫 myblog。

它的目录大概是这样：

1
2
3
4
5


myblog/
 content/
 config.toml
 themes/blog-theme/
 .gitmodules

其中 content/ 和 config.toml 是我自己的内容，应该直接提交到 myblog。

但 themes/blog-theme/ 不是我从零写的，它来自另一个仓库：

`1`	`https://github.com/example/blog-theme.git`

这里有三种处理方式。

第一种是直接复制主题代码到 themes/blog-theme/。这看起来最简单，但后面会很难维护。因为复制之后，我就很难知道这些代码最初来自哪里，也很难继续合并原作者后续更新。

第二种是每次构建时临时下载主题。这对一些项目可以，但对于博客主题这种需要本地改配置、看源码、偶尔还要定制的东西，不一定方便。

第三种就是 Git 子模块：主项目保留 themes/blog-theme/ 这个目录，但这个目录本身由另一个 Git 仓库提供。

这就是子模块最核心的作用：让一个 Git 仓库把另一个 Git 仓库当作子目录来使用，同时又保留两个仓库各自的边界。

`.gitmodules` 到底记录了什么

当项目使用子模块时，主仓库里会多一个 .gitmodules 文件。

它大概长这样：

1
2
3


[submodule "themes/blog-theme"]
	path = themes/blog-theme
	url = https://github.com/example/blog-theme.git

这个文件只说明两件事：

子模块放在哪个目录
子模块应该从哪个远程仓库拉取

也就是说，.gitmodules 记录的是“地址映射关系”。

但这还不是全部。主仓库还会额外记录这个子模块当前指向哪个提交。

这点很关键。

主仓库并不会把 themes/blog-theme/ 里的每个文件都当成自己的文件来跟踪。它只会记录一句话：

`1`	`themes/blog-theme 当前使用的是 blog-theme 仓库里的某个 commit`

你可以把它理解成一个固定版本号。

比如：

`1`	`myblog 使用 blog-theme@a1b2c3d`

所以 Git 子模块不是“把别人的代码复制进来”，而是“在主仓库里固定引用另一个仓库的某一次提交”。

这就是它的核心。

为什么这件事有价值

还是用博客主题举例。

如果主题仓库今天更新了一个版本，但这个版本有 bug，我不希望我的博客项目自动跟着坏掉。

子模块不会自动追最新版本。它会停在主仓库记录的那个提交上。

这带来了一个很重要的好处：可复现。

别人 clone 我的博客项目时，只要把子模块也初始化下来，他拿到的主题代码就应该和我提交时使用的是同一个版本。

这比“文档里写一句请安装某某主题最新版”可靠得多。因为最新版一直在变，但提交号不会变。

为什么刚 clone 下来时子模块可能是空的

很多人第一次接触子模块时，会遇到一个现象：

`1`	`git clone <repo-url>`

clone 完之后，子模块目录存在，但里面可能是空的，或者没有真正的内容。

这是正常的。

因为主仓库只先拿到了 .gitmodules 和子模块指向的提交号，还没有真正把子模块仓库拉下来。

这时需要执行：

`1`	`git submodule update --init --recursive`

如果从一开始就知道项目有子模块，也可以直接：

`1`	`git clone --recurse-submodules <repo-url>`

这条命令的意思是：clone 主仓库时，把它引用的子模块也一起拉下来。

日常更新子模块时，真正更新的是什么

假设主题仓库修了一个 bug，我希望博客项目使用新版本。

直觉上会觉得：进入 themes/blog-theme/，执行 git pull 就完了。

但这只完成了一半。

1
2


cd themes/blog-theme
git pull

这一步只是让子模块目录里的代码更新到了新提交。

接下来必须回到主仓库，再提交一次：

1
2
3


cd ../..
git add themes/blog-theme
git commit -m "chore: update blog theme"

为什么还要提交主仓库？

因为主仓库记录的是“子模块指向哪个提交”。当子模块从 a1b2c3d 更新到 e4f5g6h 时，主仓库也要把这个指针变化记录下来。

所以更新子模块，本质上不是把一堆主题文件提交到主仓库，而是修改主仓库里的这条引用：

`1`	`blog-theme@a1b2c3d -> blog-theme@e4f5g6h`

这也是很多人对 Git 子模块困惑的地方：你看到的是一个目录，但 Git 看到的是另一个仓库的提交号。

如果我想魔改这个主题，应该怎么办

这才是子模块在真实项目里最容易遇到的问题。

一开始我只是引用别人的主题。后来我想改样式、改布局、加自己的逻辑。这时应该怎么处理？

这里有两个方向。

方案一：fork 原仓库，然后让子模块指向自己的 fork

这是我更推荐的方式，尤其适合“我想改，但还希望保留上游更新能力”的情况。

原因很简单：原来的主题仓库不是我的，我没有权限直接往里面推代码。即使我在本地子模块目录里改了代码，这些改动也需要一个地方保存。

最合理的地方就是自己的 fork。

流程大概是这样。

先在 GitHub 或 Gitee 上 fork 原主题仓库。

原来子模块可能指向这里：

1
2
3


[submodule "themes/blog-theme"]
	path = themes/blog-theme
	url = https://github.com/original/blog-theme.git

fork 之后，把它改成自己的仓库：

1
2
3


[submodule "themes/blog-theme"]
	path = themes/blog-theme
	url = https://github.com/yourname/blog-theme.git

然后同步子模块配置：

`1`	`git submodule sync themes/blog-theme`

进入子模块目录，确认远程地址：

1
2


cd themes/blog-theme
git remote -v

如果地址还是旧的，可以改掉：

`1`	`git remote set-url origin https://github.com/yourname/blog-theme.git`

之后，你对子模块的修改就提交到自己的 fork：

1
2
3


git add .
git commit -m "feat: customize blog theme"
git push

最后回到主仓库，把 .gitmodules 的变化和子模块指针一起提交：

1
2
3


cd ../..
git add .gitmodules themes/blog-theme
git commit -m "chore: use forked blog theme"

这样处理之后，关系就变得很清楚：

myblog 仍然是主仓库
blog-theme 仍然是独立仓库
只是主仓库引用的主题仓库，从原作者版本变成了我的 fork

这个方案的好处是，后续还可以同步上游。

比如在自己的 fork 里保留原作者仓库地址：

1
2


git remote add upstream https://github.com/original/blog-theme.git
git fetch upstream

以后原作者修了 bug，我可以选择性合并：

`1`	`git merge upstream/main`

所以方案一的本质是：我接管了这个依赖，但没有抹掉它和上游的关系。

这适合大多数“基于开源项目做定制”的情况。

方案二：把子模块彻底并入主仓库

另一个方向是：不要子模块了，直接把它变成主仓库里的普通目录。

这个方案适合另一种情况：我已经不关心上游更新了，或者这份代码已经被我改得和原项目差异很大，再保留子模块只会增加理解成本。

比如一个主题原本来自开源仓库，但我后来把目录结构、样式、组件、构建方式都改了一遍。这个时候它已经不太像原来的主题了。继续把它当成外部依赖，意义就不大。

这时可以考虑把它并入主仓库。

但要注意，这不是简单地删除 .gitmodules 就结束了。

子模块在 Git 里有自己的记录。要把它变成普通目录，需要做几件事：

确认子模块代码已经完整拉下来
从主仓库索引里移除子模块引用
删除 .gitmodules 里的对应配置
去掉子模块目录里的 Git 元信息
重新把这些文件作为普通文件加入主仓库

以 themes/blog-theme 为例，先确认代码完整：

`1`	`git submodule update --init --recursive themes/blog-theme`

然后从主仓库索引里移除它的子模块身份，但尽量保留工作区文件：

`1`	`git rm --cached themes/blog-theme`

接着删除 .gitmodules 里对应的这一段：

1
2
3


[submodule "themes/blog-theme"]
	path = themes/blog-theme
	url = https://github.com/example/blog-theme.git

然后检查 themes/blog-theme/ 里是否还有 .git 文件或目录。如果有，就删除它。否则 Git 仍然会把它当成一个嵌套仓库，而不是普通目录。

最后重新加入主仓库：

1
2


git add .gitmodules themes/blog-theme
git commit -m "chore: vendor blog theme into repository"

完成之后，themes/blog-theme/ 就和 content/ 一样，成为主仓库直接管理的普通目录。

这个方案的好处是简单：以后 clone 项目不用再初始化子模块，改主题也不用在两个仓库之间来回切。

但代价也很明确：你基本放弃了和原主题仓库的自然同步能力。以后原作者更新了代码，你不能再像子模块那样直接拉取某个上游提交，只能手工对比和合并。

所以方案二的本质是：我不再把它当外部依赖，而是正式把它收进当前项目。

两个方案怎么选

我会按这个标准判断。

如果这份代码还像一个独立项目，只是我需要在它基础上做一些定制，选方案一。

比如主题还是主题，组件库还是组件库，只是我要改几个样式、加几个功能。这时 fork 一份，然后继续作为子模块引用，最稳。

如果这份代码已经变成当前项目的一部分，不再准备跟随上游，选方案二。

比如主题已经被改得面目全非，继续保留上游关系反而没有价值。那就把它并入主仓库，降低维护复杂度。

如果暂时不确定，优先选方案一。

因为 fork + 子模块保留了退路。后面如果真的不需要上游了，再并入主仓库也不迟。反过来，如果一开始就并入主仓库，后面再想恢复清晰的上游同步关系，会麻烦很多。

回到当前项目

所以，当前项目里出现 .gitmodules，我现在会这样理解：

它不是一个可有可无的配置文件，而是在告诉我：

1
2
3


这个项目有一部分内容来自另一个仓库。
主仓库不直接管理那部分文件。
主仓库只记录它应该使用那个仓库的哪一次提交。

这就是 Git 子模块真正要表达的东西。

它解决的不是“怎么把目录嵌套起来”的问题，而是“主项目如何稳定引用另一个独立项目”的问题。

对于博客项目来说，这个独立项目常常是主题。

对于其他工程来说，它可能是 SDK、公共组件、算法库、插件、文档模板，或者任何需要独立维护、但又必须放进主项目一起使用的代码。

总结

Git 子模块的核心可以压缩成一句话：

主仓库不保存子模块的全部代码历史，只保存子模块的来源、路径，以及当前指向的提交。

理解了这句话，很多现象就都说得通了：

为什么 clone 后还要初始化子模块
为什么更新子模块后主仓库也有变化
为什么直接在子模块里改代码不等于主仓库已经保存了这些改动
为什么 fork 后再改，是更适合二次开发的方式
为什么彻底并入主仓库，会失去和上游自然同步的能力

所以看到 .gitmodules 时，不要只把它当成一个 Git 配置文件。

它其实是在说明这个项目的依赖边界。

参考资料

已经 push 到远程的文件，再加入 .gitignore 还会生效吗？

Mon, 08 Jun 2026 20:54:07 +0800

问题背景

有时候我们会把某个本来不应该提交的文件 commit 并 push 到远程仓库，比如：

本地配置文件：application-local.yml
IDE 配置文件：.idea/workspace.xml
临时生成文件：debug.log
编译产物：dist/、target/
机器相关文件：.env.local

等发现问题时，第一反应通常是：把这个文件写进 .gitignore，然后再提交一次 .gitignore，是不是远程仓库里的那个文件就不会有了？

答案是：不会。

.gitignore 只对还没有被 Git 跟踪的文件生效。只要某个文件已经被 commit 过，它就是 tracked file。即使后来把它加入 .gitignore，Git 仍然会继续跟踪它。

直接结论

如果文件已经被 commit 并 push 到远程：

只修改 .gitignore，远程仓库里的文件不会自动删除
只修改 .gitignore，本地文件也不会停止被 Git 跟踪
后续继续修改这个文件，git status 里仍然可能看到它

想让 Git 以后不再跟踪它，常见做法是：

把文件路径加入 .gitignore
用 git rm --cached 把它从 Git 索引中移除，但保留本地文件
commit 并 push 这次变更

正确处理方式：远程删除，本地保留

假设误提交的文件是：

`1`	`config/local.yml`

先把它加入 .gitignore：

`1`	`config/local.yml`

然后执行：

`1`	`git rm --cached config/local.yml`

这个命令的意思是：

从 Git 索引中删除这个文件
不删除你本地工作区里的真实文件

接着提交并推送：

1
2
3


git add .gitignore
git commit -m "stop tracking local config file"
git push

推送完成后，结果是：

远程仓库中这个文件会在新提交里被删除
本地的 config/local.yml 仍然存在
因为 .gitignore 已经包含它，后续 Git 不会再把它作为未跟踪文件提示出来

如果是目录怎么办？

如果误提交的是整个目录，比如：

logs/

.gitignore 中写：

logs/

然后执行：

1
2
3
4


git rm --cached -r logs/
git add .gitignore
git commit -m "stop tracking logs directory"
git push

这里需要加 -r，因为 logs/ 是目录。

为什么 .gitignore 不会影响已跟踪文件？

Git 判断一个文件是否要纳入版本管理，大致可以分成两类：

已经被 Git 跟踪的文件
还没有被 Git 跟踪的文件

.gitignore 管的是第二类，也就是 untracked file。

比如你新建了一个 debug.log，它还没有被 git add，这时 .gitignore 里写了：

`1`	`debug.log`

那么 git status 就不会再提示这个文件。

但如果 debug.log 之前已经被提交过，Git 的索引里已经有它了。此时 .gitignore 不会让 Git 自动忘记它。你必须显式告诉 Git：

`1`	`git rm --cached debug.log`

也就是把它从索引里移除。

如何判断文件是否已经被 Git 跟踪？

可以用：

`1`	`git ls-files config/local.yml`

如果有输出，说明它已经被 Git 跟踪。

也可以查看当前状态：

`1`	`git status`

如果某个文件修改后显示在 Changes not staged for commit 里，通常说明它已经是 tracked file。

如果显示在 Untracked files 里，说明它还没被跟踪，这时 .gitignore 才能直接让它消失在状态列表中。

常见误区

误区一：提交 .gitignore 后，远程文件会自动消失

不会。

.gitignore 只是忽略规则，不是删除命令。远程文件是否删除，取决于后续提交里有没有把这个文件从 Git 索引中移除。

需要配合：

`1`	`git rm --cached 文件路径`

误区二：git rm –cached 会删除本地文件

不会。

git rm 文件路径 会删除本地文件，并把删除动作加入索引。

git rm --cached 文件路径 只从索引中移除文件，本地工作区文件会保留。

这也是处理本地配置文件时最常用的方式。

误区三：.gitignore 能阻止所有人提交这个文件

不完全能。

.gitignore 能让正常情况下的 git add . 不再添加这个文件，但别人仍然可以强制添加：

`1`	`git add -f config/local.yml`

所以如果是敏感文件，比如密钥、token、数据库密码，不能只依赖 .gitignore，还要配合权限控制、密钥扫描、CI 检查等手段。

如果已经把敏感信息 push 出去了怎么办？

如果误提交的是普通文件，比如日志、编译产物、本地配置模板，用 git rm --cached 通常就够了。

但如果误提交的是敏感信息，比如：

API token
SSH 私钥
数据库密码
云厂商访问密钥
生产环境配置

那就不能只删除文件了，因为敏感内容仍然存在于 Git 历史提交中。

正确处理顺序应该是：

立刻废弃或轮换已经泄露的密钥
从当前版本中删除敏感文件
把敏感文件加入 .gitignore
如有必要，使用 git filter-repo 或 BFG 清理历史记录
强制推送清理后的历史
通知所有协作者重新拉取或重新 clone 仓库

也就是说：删除当前版本里的文件，不等于删除历史里的泄露内容。

如果我想远程保留，本地以后不提交改动呢？

这是另一种需求。

比如仓库里有一个默认配置文件：

`1`	`config/dev.yml`

团队希望远程继续保留这个文件，但你本地会根据自己的环境改它，而且不想每次都在 git status 里看到它。

这种情况不适合靠 .gitignore，因为文件已经是 tracked file。

可以考虑：

`1`	`git update-index --skip-worktree config/dev.yml`

恢复跟踪时执行：

`1`	`git update-index --no-skip-worktree config/dev.yml`

还有一个类似命令：

`1`	`git update-index --assume-unchanged config/dev.yml`

两者区别可以简单理解为：

assume-unchanged 更偏性能优化，告诉 Git 暂时假设这个文件没变
skip-worktree 更偏本地覆盖场景，告诉 Git 尽量不要关心工作区里的这个文件

日常如果是“仓库保留默认配置，本地想长期改成自己的配置”，一般优先考虑 skip-worktree。

不过这个方案只影响你本地，不会影响其他人，也不会改变远程仓库。

总结

已经 commit 或 push 过的文件，再加入 .gitignore 并不会自动停止跟踪。

如果你的目标是“远程删除，本地保留，以后不再跟踪”，使用：

1
2
3
4


git rm --cached 文件路径
git add .gitignore
git commit -m "stop tracking ignored file"
git push

如果是目录，加上 -r：

`1`	`git rm --cached -r 目录路径`

如果是敏感信息泄露，要先轮换密钥，再考虑清理 Git 历史。

记住一句话就够了：.gitignore 只负责忽略未跟踪文件，不能让 Git 自动忘记已经跟踪过的文件。

Git rebase 和 merge：我在项目里怎么取舍

Tue, 03 Feb 2026 22:16:00 +0800

我以前对 rebase 和 merge 的态度比较摇摆。

刚开始写项目的时候，看到提交历史里一堆 Merge branch 'main' into feature/xxx 会觉得很乱，于是就偏向 rebase。后来在团队分支上踩过几次坑，又开始觉得 merge 稳一点。

现在我的习惯比较简单：自己的开发分支可以 rebase，已经给别人用了的分支尽量不要 rebase；合入主干时按项目约定来，不强行追求一种方式。

这件事我现在不再按“哪个更高级”来判断。rebase 和 merge 的区别不是水平高低，而是你愿不愿意改写历史、你需不需要保留分支关系、团队能不能接受这种历史形态。

merge 保留真实合并关系

merge 的特点是保留分支真实的合并关系。

1
2
3
4
5
6


git checkout main
git pull origin main

git checkout -b feature/login
git commit -m "add login api"
git commit -m "add login middleware"

这时 main 上别人也提交了东西，我想把最新 main 合进来：

1
2
3


git checkout feature/login
git fetch origin
git merge origin/main

如果两个分支都有新提交，通常会产生一个 merge commit。这个 merge commit 有时候看起来碍眼，但它也有价值：它明确记录了“这个分支是在这里和 main 合过一次”。

我一般会在这些场景用 merge：

公共分支，比如 main、develop、release/*。
多个人一起开发的长期 feature 分支。
需要保留上下文的功能分支。
项目本身要求使用 merge commit 保留 PR 合入记录。

缺点也明显：如果一个分支开发时间很长，又频繁 merge main，提交历史会比较吵。

`1`	`git log --oneline --graph --decorate --all`

所以我现在不会无脑 merge。短分支没必要反复 merge main，真有需要再同步。

rebase 适合整理自己的分支

rebase 更像是把当前分支上的提交“挪到”另一个基底后面。

1
2
3


git checkout feature/login
git fetch origin
git rebase origin/main

这样历史会更线性：

1
2
3


main: A---B---C
feature before: \---D---E
feature after: \---D'---E'

注意这里的 D'、E' 不是原来的提交了。内容可能一样，但提交哈希会变，因为父提交变了。

我一般会在这些场景用 rebase：

只有我自己在用的本地分支。
PR 提交前整理提交历史。
把多个临时提交 squash 成更容易 review 的提交。
避免 feature 分支里出现一堆没意义的同步主干 merge commit。

比如整理最近 3 个提交：

`1`	`git rebase -i HEAD~3`

可以把一些 pick 改成 squash 或 fixup。这对代码评审会友好很多。

但 rebase 的代价也在这里：它让历史更好看，同时也改变了提交身份。只要这个分支已经被别人拉走，改写历史就不再只是你自己的事。

我的实际取舍

第一，本地分支优先 rebase。

1
2
3


git checkout feature/foo
git fetch origin
git rebase origin/main

如果冲突不多，rebase 后历史干净，后面提 PR 也舒服。

第二，公共分支不要随便 rebase。

比如一个分支已经推上去了，而且别人也基于它提交了代码，这时候 rebase 会改写历史。你本地看着清爽了，别人那边可能就开始分叉、冲突、重复提交。

这种情况我更倾向于：

1
2
3


git checkout shared/feature
git fetch origin
git merge origin/main

第三，合主干看团队约定。

有的项目喜欢 merge commit，因为能看出每个 PR 的边界；有的项目喜欢 squash merge，让主干历史每个提交都对应一个完整变更；也有项目要求 rebase 后 fast-forward。

Git 历史是给人协作和排查问题用的，不是拿来展示洁癖的。

我见过比较舒服的团队约定是：

1
2
3
4


个人 feature 分支：允许 rebase，提 PR 前整理
多人共享分支：使用 merge，同步主干时不改写历史
主干合入：小 PR squash，大 PR 保留 merge commit
release 分支：尽量保留真实历史，方便追溯

这不是标准答案，但比“所有情况都 rebase”或“所有情况都 merge”更接近实际协作。

冲突和 force push

merge 冲突时：

1
2
3
4
5


git merge origin/main

git status
git add .
git commit

如果发现合错了：

`1`	`git merge --abort`

rebase 冲突时：

1
2
3
4
5


git rebase origin/main

git status
git add .
git rebase --continue

如果不想继续：

`1`	`git rebase --abort`

rebase 可能会让你连续处理多次冲突，因为它是按提交逐个重放。merge 通常是在一次合并里处理最终结果。

rebase 之后，如果这个分支之前已经 push 到远端，再 push 通常会失败：

`1`	`git push origin feature/login`

如果确认这个分支只有自己在用，我会用：

`1`	`git push --force-with-lease origin feature/login`

我基本不用 git push --force。--force-with-lease 会多做一层检查：如果远端分支已经被别人更新过，它不会直接覆盖。

风险提醒写直白一点：

不要 rebase main。
不要 rebase 别人正在基于它开发的分支。
不要在没看 git log、git status 的情况下 force push。
rebase 前如果心里没底，可以先打个临时备份分支。

`1`	`git branch backup/feature-login-before-rebase`

我的取舍并不复杂：想保留分支合并上下文，用 merge；想整理自己的提交历史，用 rebase；分支已经共享出去，就谨慎 rebase。

最后再补一句：Git 历史清爽当然好，但它首先要可恢复。每次准备 rebase 已经 push 过的分支前，我都会先确认 git status 是干净的，再看一眼 git log --oneline --graph。这两个动作比任何工作流口号都有用。

参考资料

Git LFS 大文件管理指南

Tue, 15 Jul 2025 10:29:29 +0800

Git LFS 完全指南：轻松管理 Git 仓库中的大文件

在日常开发中，你是否遇到过这样的问题：Git 仓库因为几张设计图、一个安装包而体积暴增，克隆代码需要几十分钟，git status 命令卡顿严重？如果你正在被大文件拖累 Git 仓库性能，那么 Git LFS 就是你的救星。

什么是 Git LFS？

Git LFS（Large File Storage，大文件存储）是 Git 的一个扩展工具，专门为解决 Git 对大文件支持不足的问题而设计。它的核心思路是：用轻量的「指针文件」替代实际大文件存储在 Git 仓库中，而真正的大文件则单独存储在 LFS 服务器，从而避免 Git 仓库体积膨胀，提升操作效率。

为什么需要 Git LFS？

Git 本身的设计更适合管理文本文件（如代码、配置文件），因为文本文件体积小，且 Git 能通过「差异对比」（只记录修改部分）高效存储版本历史。但面对图片、视频、安装包等大文件时，Git 会暴露明显缺陷：

仓库体积爆炸：Git 会完整保存大文件的每一个版本，几次修改后仓库可能从 MB 级膨胀到 GB 级，克隆/拉取速度极慢。
操作卡顿：git status、git commit 等命令需要扫描文件，大文件会显著拖慢这些操作。
存储浪费：重复存储大文件的多个版本，占用大量本地和远程存储空间。

而 Git LFS 正是为解决这些问题而生——它让 Git 既能管理大文件的版本，又不用承受大文件带来的性能负担。

Git LFS 工作原理

Git LFS 的核心是「分离存储」，简单来说分为三步：

用指针替代大文件
当你用 LFS 跟踪大文件时，Git 不会把实际文件存入仓库，而是生成一个几百字节的「指针文件」（包含大文件的唯一哈希和大小），指针文件会被正常提交到 Git 仓库。
大文件单独存储
实际的大文件会被上传到 LFS 服务器（如 GitHub、GitLab 的 LFS 服务），并通过哈希值与指针文件关联。
按需下载大文件
其他人克隆仓库时，先下载轻量的指针文件，再通过 LFS 工具自动从服务器下载对应的实际大文件（仅在需要时下载）。

Git LFS 安装与初始化

1. 安装 Git LFS

Windows：从 Git LFS 官网下载安装包，或通过包管理器：
1

choco install git-lfs # Chocolatey
macOS：使用 Homebrew：
1

brew install git-lfs

Linux：通过系统包管理器：

1
2
3
4


# Debian/Ubuntu
sudo apt-get install git-lfs
# CentOS/RHEL
sudo yum install git-lfs

2. 初始化 Git LFS

安装后，需要在仓库中初始化 LFS（每个仓库只需执行一次）：

`1`	`git lfs install`

执行成功后，会看到类似输出：
Git LFS initialized.

Git LFS 核心操作指南

1. 跟踪大文件

Git LFS 不会自动识别大文件，需要手动配置「跟踪规则」（通过文件类型或路径匹配）。

跟踪特定类型的文件（如所有 .zip 压缩包）：
1

git lfs track "*.zip"
跟踪指定目录下的文件（如 assets/ 目录下的所有 .png 图片）：
1

git lfs track "assets/*.png"
跟踪单个特定文件（如 installer.exe）：
1

git lfs track "installer.exe"

执行上述命令后，仓库会生成/更新 .gitattributes 文件，其中记录了 LFS 跟踪规则（需提交到仓库，确保团队成员同步配置）。

2. 查看跟踪规则

检查当前 LFS 跟踪的文件类型：

`1`	`git lfs track`

示例输出：

1
2
3


assets/*.png (.gitattributes)
*.zip (.gitattributes)
installer.exe (.gitattributes)

3. 取消跟踪文件

如果需要取消对某类文件的跟踪（仅移除规则，不影响历史提交）：

1

git lfs untrack "*.zip"

4. 正常提交与推送

配置跟踪规则后，日常操作与普通 Git 完全一致：

1
2
3
4
5
6


# 添加文件（LFS 会自动处理跟踪的大文件）
git add 大文件.zip
# 提交
git commit -m "添加大文件"
# 推送（LFS 会自动上传实际大文件到 LFS 服务器）
git push

5. 拉取 LFS 跟踪的文件

克隆仓库后，指针文件会被正常下载，但实际大文件需要手动拉取：

1
2
3
4
5


# 克隆仓库
git clone <仓库地址>
cd <仓库目录>
# 拉取 LFS 跟踪的实际文件
git lfs pull

如果希望克隆时自动拉取 LFS 文件，可以直接使用：

`1`	`git lfs clone <仓库地址>`

6. 查看 LFS 跟踪的文件列表

检查当前仓库中被 LFS 跟踪的文件：

`1`	`git lfs ls-files`

示例输出（哈希值为文件唯一标识）：

1
2


abc12345 * 大文件.zip
def67890 * assets/image.png

常见问题与解决方案

1. 拉取后大文件变成 100-200B 的小文件？

这是因为拉取的是 LFS 指针文件（而非实际文件），执行 git lfs pull 即可下载实际内容。

2. 推送时提示 LFS 文件未上传？

可能是本地 LFS 未初始化，或推送时网络问题。解决方案：

1
2
3
4


# 重新初始化 LFS
git lfs install
# 手动上传 LFS 文件
git lfs push --all origin main

3. 如何迁移已存在的大文件到 LFS？

如果仓库历史中已有大文件，可以用 git lfs migrate 命令迁移（谨慎操作，会改写历史）：

1
2


# 将所有 .zip 文件迁移到 LFS（针对 master 分支）
git lfs migrate import --include="*.zip" --everything

总结

Git LFS 是管理大文件的利器，它通过「指针-实际文件分离存储」的设计，解决了 Git 仓库因大文件导致的体积膨胀、操作卡顿等问题。只需简单配置跟踪规则，就能在不改变原有 Git 工作流的前提下，高效管理图片、视频、安装包等大文件。

如果你经常在项目中处理大文件，不妨尝试 Git LFS——让你的 Git 仓库保持轻盈，操作如丝般顺滑。

Git on DK Blog

Git 子模块的核心：不是复制代码，而是固定引用一个仓库

Git 子模块的核心：不是复制代码，而是固定引用一个仓库

先看一个具体场景

.gitmodules 到底记录了什么

为什么这件事有价值

为什么刚 clone 下来时子模块可能是空的

日常更新子模块时，真正更新的是什么

如果我想魔改这个主题，应该怎么办

方案一：fork 原仓库，然后让子模块指向自己的 fork

方案二：把子模块彻底并入主仓库

两个方案怎么选

回到当前项目

总结

参考资料

已经 push 到远程的文件，再加入 .gitignore 还会生效吗？

问题背景

直接结论

正确处理方式：远程删除，本地保留

如果是目录怎么办？

为什么 .gitignore 不会影响已跟踪文件？

如何判断文件是否已经被 Git 跟踪？

常见误区

误区一：提交 .gitignore 后，远程文件会自动消失

误区二：git rm –cached 会删除本地文件

误区三：.gitignore 能阻止所有人提交这个文件

如果已经把敏感信息 push 出去了怎么办？

如果我想远程保留，本地以后不提交改动呢？

推荐实践

总结

Git rebase 和 merge：我在项目里怎么取舍

merge 保留真实合并关系

rebase 适合整理自己的分支

我的实际取舍

冲突和 force push

参考资料

Git LFS 大文件管理指南

Git LFS 完全指南：轻松管理 Git 仓库中的大文件

什么是 Git LFS？

为什么需要 Git LFS？

Git LFS 工作原理

Git LFS 安装与初始化

1. 安装 Git LFS

2. 初始化 Git LFS

Git LFS 核心操作指南

1. 跟踪大文件

2. 查看跟踪规则

3. 取消跟踪文件

4. 正常提交与推送

5. 拉取 LFS 跟踪的文件

6. 查看 LFS 跟踪的文件列表

常见问题与解决方案

1. 拉取后大文件变成 100-200B 的小文件？

2. 推送时提示 LFS 文件未上传？

3. 如何迁移已存在的大文件到 LFS？

总结

`.gitmodules` 到底记录了什么