1.1 简介#

Git submodule 是 git 原生引用和管理第三方资源的方法。

假如你的项目结构如下：

1
Main Project
2
└── src/
3
└── module/
4
  └── module_1/

如果用 Git submodule 实现对 module_1 的管理，那么主项目 Git 仓库显然作为父仓库 (Superproject)，而 module_1 就作为子模块 (Submodule)，父仓库只记录子模块的 Git 仓库地址 和当前的 提交哈希，不会直接存储子模块的代码历史。

1.2 操作步骤#

食用方法也很简单，子模块和父模块都先建立一个单独的 Git 仓库，git add/commit/push 这些我就不细说了，现在假设两者的仓库都已经建立了，接下来就是 git submodule 的操作了：

1. 在父仓库中添加子模块：

1
git submodule add <子模块的仓库地址> <子模块在父模块中的相对路径>

e.g.

1
git submodule add https://github.com/user/module_1.git module/module_1
2

3
# 等价于
4
git submodule add https://github.com/user/module_1.git module/

那么父仓库具体是如何记录这一信息的呢？在执行上述操作后，可以看到在父仓库根目录会生成一个 .gitmodules 文件，内容形如：

1
[submodule "module/module_1"]
2
    path = module/module_1
3
    url = https://github.com/user/module_1.git

也可以通过以下命令查看子模块信息：

1
git submodule status
2
git submodule foreach "git status"

2. 初始化子模块：当协作者或其他用户克隆你的父仓库，即主项目时，默认子模块的目录是空的，需要手动拉取子模块代码：

1
git submodule init
2
git submodule update

当然，Git 也提供了在克隆时就一步到位的选项：

1
git clone --recurse-submodules <父仓库地址>

3. 更新子模块：当子模块仓库有新提交时，你可以进入子模块目录拉取最新代码（当然，回退版本也同理）：

1
cd module/module_1
2
git pull origin main
3

4
# 如果是回退，则执行
5
git checkout <子模块需要回退到的某个commit或分支>

我们前面提到过，两者的提交历史是独立的，父仓库只记录子模块的当前提交哈希，子模块仓库的更新并不会同步到父仓库中，所以父仓库还需要手动提交：

1
cd ../..
2
git add module/module_1
3
git commit -m "Update submodule module_1 to latest version"

这时候，父仓库记录的才是子模块的最新提交哈希。

4. 删除子模块：删除步骤稍复杂，需要手动清理：

1
git submodule deinit -f module/module_1
2
git rm -f module/module_1
3
rm -rf .git/modules/module/module_1

1.3 好处#

Git Submodule 将公共库抽离成单独 Git 仓库，父项目通过 Submodule 管理这些模块，保持版本可控。如需自动拉取子模块代码，也可以在 Github Action 等 CI/CD 工具中执行：

1
git submodule update --init --recursive

从而自动进行构建。

2.1 简介#

Python Package 也是一种常见方式，经常会用到的 Numpy 等就是 Package。这些第三方库能直接通过 pip 安装，分发、复用于各种项目中，虽然你用起来大道至简，但是这是 Package 的维护者在背后为你负重前行，也就是“打包”的过程，具体的打包过程可以从内到外分为三层，下图源自 Python Packaging 的官方文档，非常直观：

1. .py 独立模块（Standalone Modules）：可以直接导入，但无法通过 pip install 方式分发；
2. sdist 源码分发包（Source Distribution Package）：通过 setup.py、pyproject.toml 等安装元数据，打包成压缩文件（.tar.gz、.zip）；
3. wheel 预编译包（Built Distribution Package）：属于 binary package（二进制分发），简单来说就是预编译好的轮子，可以直接安装，例如 pip install my_package.whl ；

2.2 操作步骤#

以下以一个简单的例子为例，简单过一下打包步骤：

假如原始的代码结构如下：

1
my_package/
2
  └── src/
3
    └── module_a/
4
      ├── __init__.py
5
        └── module_a.py
6
    └── module_b/
7
      ├── __init__.py
8
          └── module_b.py

1. 准备项目信息：如果 Package 想要发布，还需要添加一些基本的信息，一般通过 setup.py 或 pyproject.toml ；

1
my_project/
2
├── LICENSE   # 授权
3
├── setup.py   # 安装设定
4
├── pyproject.toml   # 安装设定
5
├── README.md
6
├── src/   # 包源码
7
    └── my_package/
8
        ├── __init__.py
9
        └── ...
10
└── test/   # 测试程序

2. 编写元数据：一个基本的 setup.py 和 pyproject.toml 示例如下：

1
from setuptools import setup, find_packages
2

3
setup(
4
    name="my_package",
5
    version="0.1.0",
6
    description="A useful Python package",
7
    author="Your Name",
8
    author_email="you@example.com",
9
    packages=find_packages(where="src"),
10
    package_dir={"": "src"},
11
    install_requires=[
12
        "numpy>=1.19.0",
13
        "requests"
14
    ],
15
    python_requires='>=3.7',
16
)

1
[build-system]
2
requires = ["setuptools>=61.0"]
3
build-backend = "setuptools.build_meta"
4

5
[project]
6
name = "my_package"
7
version = "0.1.0"
8
authors = [
9
  { name="Your Name", email="you@example.com" },
10
]
11
description = "A useful Python package"
12
readme = "README.md"
13
requires-python = ">=3.7"
14
classifiers = [
15
    "Programming Language :: Python :: 3",
16
    "License :: OSI Approved :: MIT License",
17
    "Operating System :: OS Independent",
18
]

基本要素是类似的，也可以混用，现代打包一般采用后者，当然也有很多其他工具，这两种属于是最主流的了。

3. 构建包：这一步是可选的，但是一般如果想要发布都会进行 build，提供更快速的安装；

1
python -m build

2.3 发布到 PyPI#

PyPI，即 Python Package Index，是 Python 官方的第三方软件存储库，账号注册就不赘述了，下面简单讲一下上传步骤：

1
pip install twine
2
twine upload dist/*

上传成功后，别人就可以直接使用 pip install my_package 来安装你发布的 Package 了。

很多 Package 一般都自动构建并上传，你可以随便找一个开源项目并在里面看到：

1
.github/
2
└── workflows/
3
    └── publish.yml

完全可以学学它们的 publish.yml 以及项目结构，这里给出一个简单的示例：

1
name: Publish Python Package
2

3
on:
4
  push:
5
    tags:
6
      - 'v*'   # 当你创建 v1.0.0 这种 tag 时自动触发
7

8
jobs:
9
  build-and-publish:
10
    runs-on: ubuntu-latest
11

12
    steps:
13
    - name: Checkout code
14
      uses: actions/checkout@v4
15

16
    - name: Set up Python
17
      uses: actions/setup-python@v5
18
      with:
19
        python-version: '3.11'
20

21
    - name: Install build dependencies
22
      run: |
23
        python -m pip install --upgrade pip
24
        pip install build twine
25

26
    - name: Build package
27
      run: python -m build
28

29
    - name: Publish to PyPI
30
      env:
31
        TWINE_USERNAME: ${{ secrets.PYPI_USERNAME }}
32
        TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
33
      run: |
34
        twine upload dist/*

Token 需要你自行在 PyPI 中获取并在 Github 中的项目仓库 $\rightarrow$ Settings $\rightarrow$ Secrets and variables $\rightarrow$ Actions $\rightarrow$ 点击 New repository secret ，创建 PYPI_USERNAME 和 PYPI_PASSWORD，注意千万不要显式写在工作流中！

完成后，当提交代码并推送 Tag 时：

1
git tag v1.0.0
2
git push origin v1.0.0

GitHub Actions 会自动运行 workflow，构建 wheel 和 sdist 包，并上传到 PyPI。

也可以替换为：

1
on:
2
  release:
3
    types: [published]

这样就是在发布 Release 后自动触发。