git-text-tree 0.1.1

A tool to generate text-based representations of git repositories.

Git Text Tree

Git Text Tree 是一款用于扫描 Git 仓库目录并以树状结构展示的命令行工具。它不仅支持 .gitignore 过滤规则，还提供文件后缀过滤、跳过大文件、搜索指定字符串等功能，可在文本或 JSON 格式下输出结果，方便进行二次处理与数据分析。

功能特性

1. .gitignore 过滤
   自动读取仓库根目录下的 .gitignore 文件，跳过匹配的文件或目录。

2. 文本文件读取

   • 仅对 text/* 类型文件进行内容读取（可选）。
   • 支持限定读取最大字符数，避免处理超大文本文件。

3. 后缀过滤

   • --include-ext：仅处理特定后缀的文件（如 .py,.txt）。
   • --exclude-ext：排除指定后缀的文件。

   若同时指定，默认逻辑为：优先考虑 include-ext，若为空再判断 exclude-ext。

4. 跳过大文件

   • --skip-size <MB>：当文件大于指定体积时直接跳过。

5. 文本搜索

   • --search-text "SOMESTRING"：检索指定字符串，并记录其在文件中的所有行号。
   • 同时支持简单的子串匹配，未来可扩展为正则表达式搜索。

6. 输出格式可选

   • --format text：以类似 Unix tree 命令的形式打印结果（默认）。
   • --format json：以 JSON 格式输出，便于做二次处理或数据分析。
   • 未来可扩展支持 Markdown、HTML、CSV 等输出格式。

7. 输出到文件

   • --output-file <FILENAME>：将结果保存为文本或 JSON 文件。

8. 扫描统计（Summary）

   • 打印或返回扫描过程中的统计信息，包括目录数、文件数、忽略数、大文件跳过数、搜索命中数等。

安装

1. 直接下载脚本

将 git_text_tree.py 下载到本地，然后安装依赖：

pip install pathspec

在脚本目录下即可直接使用：

python git_text_tree.py --help

2. 安装为 CLI 工具（推荐）

若希望使用 git-text-tree 命令，可创建如下的 setup.py：

from setuptools import setup, find_packages

setup(
    name='git-text-tree',
    version='0.2.0',
    packages=find_packages(),  # 自动查找 git_text_tree 包（确保目录中含 __init__.py 文件）
    install_requires=[
        'pathspec'
    ],
    entry_points={
        'console_scripts': [
            'git-text-tree=git_text_tree.cli:main',
        ],
    },
)

然后在项目根目录下执行：

pip install -e .

安装完成后即可在终端使用：

git-text-tree --help

使用示例

基本用法

python git_text_tree.py --repo /path/to/your/git/repo

或（若已安装为 CLI 工具）：

git-text-tree --repo /path/to/your/git/repo

该命令将以树状文本方式输出仓库中未被忽略的所有文件和目录结构。

显示文件内容并进行搜索

git-text-tree \
    --repo /path/to/your/git/repo \
    --show-content \
    --search-text "TODO"

• 仅对 text/* 类型文件进行内容读取；
• 同时在文件内容中搜索 TODO 字符串，并记录匹配的行号。

跳过大文件、只处理指定后缀、输出 JSON

git-text-tree \
    --repo /path/to/your/git/repo \
    --include-ext .py,.md \
    --skip-size 5 \
    --format json

• 仅处理 .py 与 .md 文件；
• 若文件大于 5MB 则跳过；
• 以 JSON 格式输出扫描结果（包含文件树和统计信息）。

将结果保存到文件

git-text-tree \
    --repo /path/to/your/git/repo \
    --format json \
    --output-file result.json

• 将扫描结果以 JSON 格式保存到 result.json 文件，终端不直接输出。

参数说明

参数	说明	默认值
--repo	必填，指定要扫描的 Git 仓库目录	无
--show-content	是否读取并保存文本文件内容（仅 text/*）	False
--max-length	限制读取文本的最大字符数	0（不限制）
--skip-size	跳过超过指定 MB 大小的文件	0（不跳过）
--search-text	在文本文件中检索此字符串，记录匹配行号	无
--include-ext	仅处理指定后缀文件（如 .py,.txt）	空
--exclude-ext	排除指定后缀文件（如 .png,.jpg）	空
--format	输出格式，支持 text 或 json	text
--output-file	若指定，则将结果写入该文件（文本或 JSON 格式）	空（不输出）

当 --include-ext 不为空时，将忽略 --exclude-ext 的设置。

输出说明

文本模式 (--format text)

• 以树形结构打印仓库文件和目录，如下所示：

  ├── src/
  │   ├── main.py
  │   └── utils.py
  ├── README.md
  └── requirements.txt
  

• 之后打印扫描统计信息，例如：

  === Summary ===
  Directories:          5
  Files:                12
  Ignored (.gitignore): 3
  Skipped large files:  1
  Matched search text:  2
  

JSON 模式 (--format json)

• 输出一个包含 tree 和 summary 两部分的 JSON 对象：

  {
    "tree": {
      "src": {
        "type": "dir",
        "children": {
          "main.py": {
            "type": "file",
            "content": "...",
            "search_hits": []
          },
          "utils.py": {
            "type": "file",
            "content": null,
            "search_hits": []
          }
        }
      },
      "README.md": {
        "type": "file",
        "content": "# Project\n...",
        "search_hits": [2, 10]
      }
    },
    "summary": {
      "dirs": 5,
      "files": 12,
      "ignored": 3,
      "skipped_large": 1,
      "matched_search": 2
    }
  }
  

• 若指定 --show-content，则 content 字段会包含部分或全部文件内容；若指定 --search-text，则 search_hits 字段表示匹配的行号。

开源许可

本项目以 MIT License 开放源代码，欢迎自由使用与二次开发。

贡献

如有建议或问题，欢迎提 Issue 或发起 Pull Request。感谢对本项目的关注与贡献！

---

使用 Git Text Tree，你可以轻松扫描和分析 Git 仓库结构，结合忽略规则、高级过滤与文本搜索，让项目管理和调试更加便捷！未来版本将不断扩展更多功能，敬请期待！