repository_module.md

Repository 模块 (coderepoindex.repository)

1. 概述

repository 模块是 CodeRepoIndex 项目的数据源获取层。它的核心职责是提供一个统一、可靠的接口，用于从各种不同的来源获取代码仓库，并将其准备为本地文件系统上的一个目录，以供后续的 parsers 模块进行处理。

该模块将复杂的获取逻辑（如Git克隆、分支处理、ZIP解压等）封装起来，为上层模块提供了一个简单的、配置驱动的调用方式。

2. 核心组件

2.1. RepoSource (Enum)

这是一个枚举类，定义了支持的代码仓库来源类型：

• GIT: 表示代码仓库来源于一个 Git URL。
• LOCAL: 表示代码仓库是一个本地文件系统上的目录。
• ZIP: 表示代码仓库是一个 .zip 压缩文件。

2.2. RepoConfig (Dataclass)

这是一个数据类，用于封装获取一个代码仓库所需的所有配置信息。它是与 RepositoryFetcher 交互的主要数据结构。

核心属性:

• source: RepoSource 枚举成员，指定仓库来源。
• path: 仓库的路径。根据 source 的不同，它可以是一个 Git URL、一个本地文件夹路径或一个 ZIP 文件路径。
• branch, tag, commit: 当 source 为 GIT 时，可以指定要检出的分支、标签或特定的提交哈希。
• target_dir: (可选) 指定一个目录用于存放获取的代码。如果不指定，模块会自动在当前工作目录下的 .coderepo/ 文件夹中创建一个以仓库名和版本信息命名的缓存目录。
• auth_token: (可选) 用于访问私有 Git 仓库的认证令牌。

2.3. RepositoryFetcher (Class)

这是本模块的核心实现类，负责执行实际的代码获取操作。

• 职责:
  • 统一接口: 提供一个 fetch(config: RepoConfig) 方法，根据传入的配置自动选择并执行相应的获取逻辑。
  • Git 操作: 如果来源是 GIT，它会使用 GitPython 库来执行 git clone 操作。它还能够智能地处理分支、标签和提交，并自动创建缓存目录，避免对同一版本的仓库进行重复克隆。
  • 本地路径处理: 如果来源是 LOCAL，它会验证路径是否存在并直接返回该路径。
  • ZIP 文件处理: 如果来源是 ZIP，它会自动将 ZIP 文件解压到一个临时目录中。
  • 上下文管理与清理: RepositoryFetcher 实现了上下文管理器协议 (__enter__, __exit__)，可以在使用完毕后自动清理所有下载的临时文件和目录，确保不留垃圾文件。

2.4. 便捷函数

为了简化 RepoConfig 对象的创建，模块提供了一系列工厂函数：

• create_git_config(...)
• create_local_config(...)
• create_zip_config(...)

3. 工作流程

graph TD
    A[Upstream Module, e.g., CodeIndexer] --> B{Creates RepoConfig};
    B --> C[RepositoryFetcher];
    C -- Calls --> D{fetch(config)};
    
    subgraph "RepositoryFetcher Logic"
        D -- Reads config.source --> E{Switch};
        E -- GIT --> F[Fetch from Git];
        E -- LOCAL --> G[Use Local Path];
        E -- ZIP --> H[Extract from ZIP];
    end

    F --> I[Returns Local Path to Cloned Repo];
    G --> I;
    H --> I;

    I --> A;

    style C fill:#f9f,stroke:#333,stroke-width:2px

Loading

典型使用:

from coderepoindex.repository import RepositoryFetcher, create_git_config

# 1. 创建一个 Git 仓库的配置，指定克隆 master 分支
git_config = create_git_config(
    repo_url="https://github.com/user/repo.git",
    branch="master"
)

# 2. 使用上下文管理器来获取仓库并自动清理
with RepositoryFetcher() as fetcher:
    # fetcher 会克隆仓库并返回其在本地的存储路径
    local_repo_path = fetcher.fetch(git_config)
    
    print(f"仓库已获取到: {local_repo_path}")
    
    # 在这里可以对 local_repo_path 进行解析、索引等操作
    # ...

# 退出 with 代码块后，所有临时下载的文件都会被自动删除
print("Fetcher 已清理临时文件。")