约定式提交#

约定式提交规定了一套编写 git 提交信息的规范, 方便写出清晰, 突出重点, 分类明确的提交信息, 尤其在团队协作时十分必要.

本文中介绍的规范有别于标准的 约定式提交规范, 在一些方面做了让步, 方便新手编写.

概述#

一个提交应由以下几部分组成

<类型>: <描述>

[正文]

类型 字段见下文 类型 一章.

描述 应当是对提交的一句话总结, 力求简洁清楚, 重点分明. 对于描述部分的详细解释, 可以写在 正文 部分. 正文并非必要, 最好只在提交十分复杂, 或是包含了多个不同修改时编写.

要使用约定式提交, 需要对提交本身进行规范:

• 拆分不同文件的修改.
  例如文档的修改与源代码的修改应该分开提交; 配置文件, 测试代码, 编译脚本等等都应该尽量分离. 可以阅读 类型 一章, 了解哪些修改应该单独提交. 拆分提交的方法在 这里.
• 尽量更细致地进行提交, 一次提交一个功能的修改.
  也就是说, 不要一股脑将全部文件的修改送入版本库. 例如在某一源代码文件中, 既修改了数据的展示方式, 又修改了某 API 的实现, 那它们应该被拆分为两个提交.
• 避免过于细小的提交.
  某些微小又不重要的提交, 例如文档中某个拼写或代码某处符号后的空格, 可以等后面修改此文件时一并提交.

描述与正文部分尽量使用 markdown 语言标记. 特别地, 提到文件名时应使用反引号 ` 括起. 在正文中陈列多条修改时使用 markdown 的列表语法.

当修改过多以至于无法细致提交时, 可以在描述处写 多次提交, 转而在正文处陈列. 但是强烈建议涉及业务功能的修改不要这样, 以免淹没在不重要的琐碎提交中.

git 子模块#

git 子模块 (submodule) 是挂于某 git 仓库下的子仓库. 当父仓库想使用第三方或者是与主业务分离的模块时, 可以通过将其注册为子模块来增加灵活性.

添加子模块#

通过在父仓库使用

git submodule add <url> <path>

可以在 <path> 地址处添加一个子模块.

其中, url 可以为远程仓库地址, 也可以是本地仓库地址. 例如, 要把下面的 new_repo 仓库添加为 repo 的子模块, 可以使用命令:
git submodule add ./3rd/new_repo 3rd/new_repo
其中 ./3rd/new_repo 即为本地仓库的 url. 需要注意的是本地 url 前面的 ./ 或 ../ 是必须的, <path> 也不能省略.

repo
├─ .git
└─ 3rd
    └─ new_repo
        └─ .git

另外一个远程仓库的例子. 若想把 github.com/user/new_repo.git 仓库添加为 repo 的子模块, 并要求 new_repo 放置在 3rd 文件夹内, 可以使用命令:
git submodule add github.com/user/new_repo 3rd
如果不指定后面的路径 3rd, 则会直接把 new_repo 克隆到父仓库目录下.

关于知识库框架结构的一些想法#

因为我的各种文档或笔记过于分散凌乱, 非常需要进行统一管理. 但是使用的技术栈千差万别, 有纯文字用 markdown 写的, 有使用 jupyter 笔记本内嵌代码的, 有使用 mathematica 的, 有用 typst 和 latex 写更专业的出版级文档的, 也有主要写代码附文说明的. 现有的知识库框架不可能支持如此多种类的文件管理, 事实上传统的知识库软件仅能做到管理文字内容, 并且也很难做到与其他编辑器的通用. 例如编写代码另附文档的情况, 势必要在其他编辑器处进行代码的编辑, 也当然希望在那里就完成文档的修改, 而不必打开特定的知识库管理或文档软件.

我想通过 git submodule 与 obsidian 协同构建一个包罗万象的知识库框架, 力图让专业的软件做专业的事, 而不必让知识库管理它能力范围之外的文件, 例如源代码啊, 交互式笔记本啊什么的.

obsidian 与 git submodule#

obsidian 本质上还是文字编辑软件, 在不加插件的前提下, 只有基础的文字编辑功能 (依托 markdown 标记语言). 因此我们只让 obsidian 管理博文和各类文档, 并辅以 git 进行版本控制.

项目结构如下:

.
├─ Blog
└─ Work
    ├─ A
    └─ B
    ...

其中 Blog 是记录日常或简单知识的文章; 而偏知识向或更专业的, 以及不使用 markdown 语言写的内容都放置于 Work 目录下, 每组另外再分目录.

Git Tips#

文件管理#

工作区#

工作区 即整个工作空间的根目录, 也就是 .git 目录存在的那一级目录. 对每个文件的修改都在这里进行.

特殊地, 被 .gitignore 排除的文件或目录不属于工作区. 这些文件将被彻底排除出 git 的管理, 对他们的操作也无法使用 git 回退或恢复.

暂存区#

当在工作区进行操作后, 使用 git add 命令将修改的文件 添加 (add) 到 暂存区. 暂存区可以继续添加或移除文件, 直到使用 git commit 命令将区内的文件一次性 提交 (commit) 到版本库中.

文件状态#

被 git 管理的文件有以下几种状态:

• U, untrack: 未跟踪
  这是新创建的文件, 此前在工作区从未出现. 例如在工作区新建某一源代码文件, 并且写入部分内容, 这个文件就处于未跟踪状态.
• M, modified: 已修改
  这是之前已被提交过的文件, 但是经过了一些修改, 使其与之前不同了. 例如在更改某一方法的实现等等.
• staged: 已暂存
  当把工作区的文件添加到暂存区后, 其状态就变为已暂存.
• committed: 已提交
  当把暂存区的文件提交到仓库后, 其状态就变为已提交.

快速操作#

为 git 设置代理#

git config --global http.proxy "http://127.0.0.1:7890" # 端口待定
git config --global https.proxy "https://127.0.0.1:7890"

查看提交历史#

git log

或以 ascii 图形的方式展示树状分支结构: