gitingest 如何用 --include-submodules 把 Git 子模块纳入 digest？
【免费下载链接】gitingestReplace 'hub' with 'ingest' in any GitHub URL to get a prompt-friendly extract of a codebase项目地址: https://gitcode.com/GitHub_Trending/gi/gitingest
如果你的仓库用 Git 子模块管理依赖代码，用 gitingest 对它生成 digest 时会遇到一个问题：默认的 digest 只包含主仓库的文件，子模块目录下的内容不会进来。gitingest 提供--include-submodules（CLI）和include_submodules=True（Python API）来改变这个默认行为，把子模块递归地克隆并写进 digest。本文说明安装、执行和验证这条操作路径。
前提与默认行为
- 环境要求：Python 3.8+（见 README.md 的 Requirements 一节）。
- 安装 gitingest，二选一：
pip install gitingest或使用 pipx（首次使用 pipx 先运行pipx ensurepath）：
pipx install gitingest- 子模块相关的关键默认值：CLI 的
--include-submodules是一个is_flag=True, default=False的开关（见 src/gitingest/main.py），CloneConfig中的include_submodules同样默认False（见 src/gitingest/schemas/cloning.py）。也就是说，不加该选项时子模块不会被克隆、不会进入 digest。 - 这个选项作用于远程仓库克隆路径：gitingest 克隆仓库并 checkout 到目标 commit 后，才执行子模块更新（见 src/gitingest/clone.py）。对本地目录作为 source 的场景没有克隆过程，也就没有子模块更新。
CLI 执行步骤
- 用仓库 URL 作为 source，加上
--include-submodules（username/repo-with-submodules换成你实际的仓库）：
gitingest https://github.com/username/repo-with-submodules --include-submodules输出默认写入当前工作目录的
digest.txt。也可以：- 用
--output/-o <filename>指定文件名； - 用
--output/-o -直接输出到 STDOUT，方便管道给其他工具。
- 用
私有仓库需要在命令中携带凭据，二选一（见 README.md 的 "Command line usage"）：
gitingest https://github.com/username/private-repo --token github_pat_... --include-submodulesexport GITHUB_TOKEN=github_pat_... gitingest https://github.com/username/private-repo --include-submodules注意子模块本身的远端仓库也需要可访问，token 会随克隆流程传给 Git 操作。
结果验证
命令成功时的判断依据（均为 src/gitingest/main.py 中实际输出的文本）：
- 写文件模式：终端打印
Analysis complete! Output written to: digest.txt，随后打印\nSummary:和 summary 内容。 - stdout 模式（
-o -）：在 STDERR 打印--- Summary ---…--- End Summary ---和Analysis complete! Output sent to stdout.。
进一步核对 digest 内容：打开digest.txt，检查文件树部分是否出现了子模块目录及其下的文件。README 说明 summary 包含文件与目录结构、extract 大小和 token 数等统计，若 digest 里看不到子模块路径，说明子模块没有被纳入（例如该目录只是普通目录而非.gitmodules中声明的子模块）。
克隆阶段内部的日志也会给出信号：[src/gitingest/clone.py](https://link.gitcode.com/i/da34f52cfaccbfdb862c8dcaf74d2915)中，只有include_submodules为真才会打印Updating submodules，成功后记录Submodules updated successfully。Git 操作失败时抛出RuntimeError: Git operation failed: {exc}，CLI 会以Error: ...形式报出并以非零状态退出。
可选：Python API 方式
在代码里调用时，参数名是include_submodules（见 README.md 的 "Python package usage" 和 src/gitingest/entrypoint.py 的签名）：
from gitingest import ingest # Include repository submodules summary, tree, content = ingest( "https://github.com/username/repo-with-submodules", include_submodules=True, )私有仓库可以传token="github_pat_..."或预先设置环境变量GITHUB_TOKEN。与 CLI 不同，ingest默认不写文件，结果直接以summary, tree, content三元组返回；需要落盘时传output参数（"-"表示 stdout）。Jupyter 场景下ingest_async可以直接await。
内部机制与限制
- 执行顺序（基于 src/gitingest/clone.py）：校验仓库存在 → 解析目标 commit → 以
--single-branch --no-checkout --depth=1浅克隆 → checkout 目标 commit → 若开启子模块，执行git submodule update --init --recursive --depth=1。子模块更新是递归的（--recursive），且同样为深度 1 浅更新；tests/test_clone.py 用断言submodule.assert_called_with("update", "--init", "--recursive", "--depth=1")固定了这一行为。 - 整个克隆操作受
DEFAULT_TIMEOUT超时包裹，超时或克隆失败会抛RuntimeError: Git clone failed: ...。 - 该选项自 v0.2.0（2025-07-26）起提供，见 CHANGELOG.md 中 "Features:
include_submodulesoption" 条目。 - 默认跳过
.gitignore匹配的文件这一行为与子模块无关，但若子模块内的文件被 ignore 规则命中，需要另行加--include-gitignored（CLI）或include_gitignored=True（API）。
【免费下载链接】gitingestReplace 'hub' with 'ingest' in any GitHub URL to get a prompt-friendly extract of a codebase项目地址: https://gitcode.com/GitHub_Trending/gi/gitingest
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
