Metadata-Version: 2.4
Name: atomgit
Version: 1.1.1
Summary: AtomGit模型文件上传下载CLI工具
Home-page: https://atomgit.com/gitcode-ai/atomgit_cli
Author: AtomGit CLI Team
Author-email: sa@atomgit.com
Project-URL: Bug Reports, https://atomgit.com/gitcode-ai/atomgit_cli/issues
Project-URL: Source, https://atomgit.com/gitcode-ai/atomgit_cli
Keywords: transformers huggingface model dataset upload download cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Archiving
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.7
Requires-Dist: requests>=2.31.0
Requires-Dist: tqdm>=4.66.1
Requires-Dist: colorama>=0.4.6
Requires-Dist: tabulate>=0.9.0
Requires-Dist: huggingface-hub==1.1.7
Requires-Dist: datasets==4.4.1
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# AtomGit CLI & SDK

基于Transformers和Hugging Face Hub的AtomGit平台模型文件上传下载CLI工具和Python SDK

## 简介

AtomGit 是一个完整的工具包，提供命令行工具（CLI）和Python SDK两种方式与AtomGit平台交互，支持模型和数据集的上传、下载等操作。类似于huggingface_hub，用户只需安装一个`atomgit`包即可同时使用CLI命令和Python编程接口。工具基于Transformers和Hugging Face Hub SDK开发，并配置为连接AtomGit API端点。

## 功能特性

### CLI功能
- 🔐 用户认证和登录管理
- 🔗 **Git集成**：自动配置Git凭证，支持标准Git命令
- 📁 支持模型和数据集仓库创建
- ⬆️ 文件和目录批量上传
- ⬇️ 仓库内容下载
- 🎨 彩色终端输出
- 📊 上传下载进度显示
- 🔧 配置文件管理

### SDK功能
- 🐍 **Python原生接口**：类似huggingface_hub的API设计
- 🔄 **与CLI共享配置**：使用相同的认证和配置文件
- 📦 **一键安装**：安装atomgit包即可同时使用CLI和SDK
- 🚀 **完整API**：snapshot_download、upload_folder、create_repository等
- 📝 **完善的文档**：详细的使用示例和错误处理

## 系统要求

- **Python 3.8+** (推荐Python 3.11+)
- 支持的操作系统：Windows, macOS, Linux

## 安装

### 从源码安装

```bash
git clone https://atomgit.com/gitcode-ai/atomgit_cli.git
cd atomgit_cli
pip install -e .
```

### 使用pip安装（如果已发布）

```bash
pip install atomgit
```

### 虚拟环境推荐

```bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt
```

## 使用方法

### 快速开始

#### CLI使用
```bash
# 登录
atomgit login

# 下载模型
atomgit download wuyw/Qwen3-Reranker-0.6B-test -d ./models

# 上传文件
atomgit upload ./my-model --repo-id username/my-repo
```

#### SDK使用
```python
# 导入SDK
from atomgit_hub import snapshot_download

# 下载模型到本地目录
snapshot_download("wuyw/Qwen3-Reranker-0.6B-test", local_dir="./Qwen3-Reranker-0.6B-test")
```

### 1. 登录

首先需要登录到AtomGit平台：

```bash
atomgit login
```

系统会提示输入访问令牌（从AtomGit平台获取）。

**🎉 Git集成功能**：登录成功后，工具会自动配置Git凭证助手，这样你就可以直接使用标准的Git命令来操作AtomGit仓库，无需再次输入token。凭证助手会自动从AtomGit API获取你的真实用户名用于Git认证：

```bash
# 登录后，这些Git命令将自动使用保存的token
# 支持两种域名格式
git clone https://atomgit.com/username/repo-name.git
git clone https://hub.atomgit.com/username/repo-name.git
git push origin main
git pull origin main
```




### 2. 上传文件

命令格式：

```bash
atomgit upload <PATH> [PATH_IN_REPO] --repo-id <owner/repo-name> [OPTIONS]
```

上传前请确保目标仓库已在平台上创建，本命令不会自动建仓。`--repo-type` 必须与仓库真实类型一致，否则会按错误的路径请求并报仓库不存在。

#### 上传模型

模型是默认仓库类型（`--repo-type model`），可省略。

```bash
# 目录上传到仓库根目录
atomgit upload ./your-model-dir --repo-id your-username/your-model-name

# 上传到仓库子目录
atomgit upload ./checkpoints ckpt/v1 --repo-id your-username/your-model-name

# 只传权重和配置、排除日志
atomgit upload ./your-model-dir --repo-id your-username/your-model-name \
  --include "*.safetensors" --include "*.json" --exclude "*.log"

# 过滤模式也支持逗号分隔，与重复指定等价
atomgit upload ./your-model-dir --repo-id your-username/your-model-name \
  --include "*.safetensors,*.json" --exclude "*.log,*.tmp"

# 大文件或大数据集：调大超时（默认 300 秒）
atomgit upload ./your-model-dir --repo-id your-username/your-model-name --timeout 1800

# 带提交消息
atomgit upload ./your-model-dir --repo-id your-username/your-model-name \
  --commit-message "init model"

# 上传到指定分支（不指定时为仓库默认分支，通常 main）
atomgit upload ./your-model-dir --repo-id your-username/your-model-name --revision dev
```

#### 上传数据集

数据集仓库必须显式指定 `--repo-type dataset`。

```bash
# 目录上传到数据集仓库根目录
atomgit upload ./your-dataset-dir --repo-id your-username/your-dataset-name \
  --repo-type dataset

# 上传到数据集仓库的 images/ 子目录，只传图片
atomgit upload ./images images --repo-id your-username/your-dataset-name \
  --repo-type dataset --include "*.jpg" --include "*.png"

# 排除临时文件与原始目录
atomgit upload ./your-dataset-dir --repo-id your-username/your-dataset-name \
  --repo-type dataset --exclude "*.tmp" --exclude "raw/*"
```

#### 上传单个文件

`PATH_IN_REPO` 对单文件是**完整目标路径**；以 `/` 结尾时按目录前缀处理，保留本地文件名。模型和数据集仓库都可以传单文件。

```bash
# 落到仓库根目录，沿用本地文件名
atomgit upload ./model.bin --repo-id your-username/your-model-name

# 指定仓库内完整目标路径
atomgit upload ./model.bin models/model.bin --repo-id your-username/your-model-name

# 目标以 / 结尾 -> models/model.bin
atomgit upload ./model.bin models/ --repo-id your-username/your-model-name

# 单文件上传到数据集仓库
atomgit upload ./train.jsonl data/train.jsonl --repo-id your-username/your-dataset-name \
  --repo-type dataset --commit-message "add train split"
```

#### 临时使用其他令牌上传

```bash
atomgit upload ./your-model-dir --repo-id your-username/your-model-name \
  --token "xxx-xxx"
```

`--token` 传入后本次上传优先使用该令牌；若本地已登录，会提示已忽略本地登录凭证，`~/.atomgit/config.json` 中的凭证不会被修改或清除。

#### 参数说明

| 参数 | 简写 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `PATH` | - | str | 必需 | 位置参数，本地文件或目录 |
| `PATH_IN_REPO` | - | str | None | 位置参数，仓库内目标路径。目录：作为目标目录前缀；文件：视为完整目标路径，以 `/` 结尾则作为目录前缀 |
| `--repo-id` | - | str | 必需 | 仓库 ID，格式 `owner/repo-name` |
| `--repo-type` | - | choice | `model` | 仓库类型：`model` 传模型，`dataset` 传数据集 |
| `--include` | - | list | None | 包含的文件 glob 模式，可重复指定或逗号分隔，如 `--include "*.bin"` / `--include "*.bin,*.json"` |
| `--exclude` | - | list | None | 排除的文件 glob 模式，可重复指定或逗号分隔，如 `--exclude "*.log"` |
| `--commit-message` | `-m` | str | `''` | 提交消息，也支持 `--message`；留空时使用默认消息 |
| `--revision` | `-r` | str | None | 上传到指定分支，默认为仓库默认分支（通常 `main`） |
| `--token` | - | str | None | 访问令牌，默认使用已登录凭证；传入后优先使用，并忽略本地登录凭证 |
| `--timeout` | `-t` | float | `300` | 单次请求超时时间（秒），大文件或大数据集建议调大 |

#### 使用注意

- **仓库类型要匹配**：`model` 仓库不加 `--repo-type`（或写 `model`）；`dataset` 仓库必须写 `--repo-type dataset`。
- **`PATH_IN_REPO` 语义区分文件与目录**：目录是按前缀拼接（`ckpt` → 仓库内 `ckpt/...`），单文件是完整路径（`models/model.bin` → 就是该路径）。单文件的前导 `/` 会被去掉。
- **过滤规则**：`--include` 与 `--exclude` 同时给定时两者取交集；目录上传时排除规则还会与 SDK 内置忽略项（`.git`、`.cache/huggingface` 等）叠加。
- **单文件也会过滤**：单文件上传时 `--include`/`--exclude` 作用于目标路径，未命中会提示「已跳过」并以失败退出。
- **默认提交消息**：未指定 `--commit-message` 时，文件为 `Upload file using atomgit client`，目录为 `Upload folder using atomgit client`。
- **目标分支必须已存在**：`--revision` 指向不存在的分支/标签时，命令会在**上传开始前**直接失败（提示 `目标分支不可用，未开始上传`），不会先把几百 MB 传完才在提交阶段报错。需要新分支时请先在平台上创建。
- **报错会带服务端原文**：401/403/404 会映射为可操作的中文说明，并附上服务端返回的原始错误信息（例如上游的 `get file attributes failed`），便于直接定位问题。
- **目录上传有阶段提示**：本地哈希完成后会打印 `正在提交到 <repo>...`，用于区分「正在计算哈希」与「正在传输」，避免大文件看起来像卡死。
- **内容未变时会跳过整次上传**：目标分支同一路径已存在相同内容（sha256 一致）时，会提示 `内容未变化，已跳过上传` 并直接成功，不产生提交。


### 3. 下载文件

命令格式：

```bash
atomgit download <REPO_ID> [FILES] [-r REVISION] [-d DIRECTORY] [--force]
```

`FILES` 是位置参数，指定要下载的文件，支持**多个文件**，多个用英文逗号分隔；不传则下载整个仓库。

#### 下载整个仓库

```bash
# 下载到当前目录下的 <仓库名>/
atomgit download your-username/your-model-name

# 下载到指定目录
atomgit download your-username/your-model-name -d ./models/
```

#### 下载单个文件

```bash
atomgit download your-username/your-model-name config.json
```

#### 下载多个文件（逗号分隔）

```bash
atomgit download your-username/your-model-name config.json,tokenizer.json,model.safetensors

# 配合目录与版本
atomgit download your-username/your-model-name \
  config.json,tokenizer.json -d ./models/qwen -r main
```

其中任何一个文件下载失败，其余文件仍会继续尝试，命令最终以失败状态退出并列出失败的文件名。

#### 只下载部分文件 / 私有仓库

```bash
# 只下 safetensors 权重和配置，排除日志与优化器状态
atomgit download your-username/your-model-name -d ./models \
  --include "*.safetensors" --include "*.json" --exclude "*.log"

# 私有仓库/私有模型：直接传令牌，无需先 atomgit login
atomgit download your-username/private-model --token "xxx-xxx"

# 下载指定文件时同样可以带令牌
atomgit download your-username/private-model config.json --token "xxx-xxx"
```

`--include` / `--exclude` 采用 glob 语义，支持重复指定或逗号分隔（`--include "*.md,*.json"` 等价于 `--include "*.md" --include "*.json"`），两者同时给定时取交集。它们**仅在整仓下载时生效**；如果和显式文件列表一起用，会给出警告并忽略（显式指定的文件优先）。若过滤后没有任何文件命中，命令会给出提示，避免误以为下载成功。

#### 指定缓存目录

```bash
# 缓存/元数据放到指定目录（下载内容仍写入 -d 指定的位置）
atomgit download your-username/your-model-name -d ./models --cache-dir /data/cache/atomgit
```

`--cache-dir` 控制 Hugging Face 的缓存与元数据目录（默认 `~/.cache/atomgit`）。指定后可以复用该缓存里已存在的文件，避免重复下载。

#### 强制覆盖已存在文件

```bash
# 加 --force 会覆盖本地已存在的同名文件
atomgit download your-username/your-model-name -d ./models --force
```

整仓模式**不加** `--force` 时按断点续传处理：已存在且未变化的文件会被跳过，只有缺失或被修改的文件才会重新下载。

#### 用逗号分隔的过滤模式

```bash
# 等价于 --include "*.md" --include "*.json" --include "*.cff"
atomgit download your-username/your-model-name -d ./models \
  --include "*.md,*.json,*.cff"

# 只下文档与配置，排除权重和缓存
atomgit download your-username/your-model-name -d ./models \
  --include "*.md,*.json,*.cff" --exclude "*.safetensors,*.bin"
```

#### 参数说明

| 参数 | 简写 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| `REPO_ID` | - | str | 必需 | 位置参数，仓库 ID，支持 `owner/repo` 与三层格式 |
| `FILES` | - | str | None | 位置参数，要下载的文件，多个用英文逗号分隔；留空则下载整个仓库 |
| `--revision` | `-r` | str | None | 版本/分支/标签，默认仓库默认分支 |
| `--directory` | `-d` | path | 见下 | 下载目录。整仓模式默认 `./<仓库名>`，指定文件模式默认当前目录 |
| `--include` | - | list | None | 包含的文件 glob 模式，可重复指定或逗号分隔。仅整仓下载生效 |
| `--exclude` | - | list | None | 排除的文件 glob 模式，可重复指定或逗号分隔。仅整仓下载生效 |
| `--token` | - | str | None | 访问令牌（私有模型/仓库需要），优先于本地登录凭证 |
| `--cache-dir` | - | path | `~/.cache/atomgit` | 缓存与元数据目录，支持 `~` 展开 |
| `--force` | - | flag | False | 强制覆盖已存在文件。整仓模式不加此参数时按断点续传处理 |

### 4. 其他命令

#### 退出登录

```bash
atomgit logout
```

#### 显示配置信息

```bash
atomgit config-show
```

## SDK使用方法

AtomGit除了提供CLI工具外，还提供了类似huggingface_hub的Python SDK接口，让您可以在Python代码中直接使用AtomGit的功能。

### SDK功能特性

- 🐍 **Python原生接口**：类似huggingface_hub的API设计
- 🔄 **与CLI共享配置**：使用相同的认证和配置文件
- 📦 **一键安装**：安装atomgit包即可同时使用CLI和SDK
- 🚀 **功能齐全**：支持上传、下载、仓库管理等完整功能

### 1. SDK导入

```python
# 推荐方式：直接从atomgit_hub导入
from atomgit_hub import snapshot_download

# 或者从atomgit包导入
from atomgit import snapshot_download

# 导入多个功能
from atomgit_hub import (
    snapshot_download,    # 下载整个仓库
    download_file,       # 下载单个文件
    upload_folder,       # 上传文件
    create_repository    # 创建仓库
)
```

### 2. SDK下载功能

#### 下载整个仓库（推荐用法）

```python
from atomgit_hub import snapshot_download

# 基本用法：下载到指定目录
snapshot_download(
    "wuyw/Qwen3-Reranker-0.6B-test", 
    local_dir="./Qwen3-Reranker-0.6B-test"
)

# 高级用法：更多参数控制
snapshot_download(
    repo_id="username/model-name",
    local_dir="./models/my-model",
    cache_dir="/data/cache/atomgit",  # 缓存/元数据目录，默认 ~/.cache/atomgit
    revision="main",              # 指定分支/标签
    force_download=False,         # 是否强制重新下载
    allow_patterns=["*.py", "*.md"],  # 只下载特定文件
    ignore_patterns=["*.bin"],    # 忽略特定文件
)
```

#### 下载单个文件

```python
from atomgit_hub import download_file

# 下载单个文件
file_path = download_file(
    repo_id="username/repo-name",
    filename="README.md",
    local_dir="./downloads",
    cache_dir="/data/cache/atomgit",  # 缓存/元数据目录，默认 ~/.cache/atomgit
)
print(f"文件下载到: {file_path}")
```

#### 参数说明

`atomgit_hub.snapshot_download`（整仓下载）：

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `repo_id` | str | 必需 | 仓库 ID，支持 `owner/repo` 与三层格式 |
| `local_dir` | str/Path | None | 下载到本地的目录 |
| `cache_dir` | str/Path | `~/.cache/atomgit` | 缓存与元数据目录，等价 CLI 的 `--cache-dir` |
| `revision` | str | None | 版本/分支/标签，默认仓库默认分支 |
| `token` | str | None | 访问令牌，默认使用 CLI 登录凭证；等价 CLI 的 `--token` |
| `allow_patterns` | list/str | None | 包含的文件 glob 模式，等价 CLI 的 `--include` |
| `ignore_patterns` | list/str | None | 排除的文件 glob 模式，等价 CLI 的 `--exclude` |
| `force_download` | bool | False | 强制重新下载 |
| `max_workers` | int | 8 | 并发下载线程数（CLI 未暴露，固定 8） |

`atomgit_hub.download_file`（单文件下载）：

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `repo_id` | str | 必需 | 仓库 ID |
| `filename` | str | 必需 | 文件在仓库内的路径，单文件无需 glob 过滤 |
| `local_dir` | str/Path | None | 下载到本地的目录 |
| `cache_dir` | str/Path | `~/.cache/atomgit` | 缓存与元数据目录 |
| `revision` | str | None | 版本/分支/标签，默认仓库默认分支 |
| `token` | str | None | 访问令牌，默认使用 CLI 登录凭证 |
| `force_download` | bool | False | 强制重新下载 |

#### 获取文件下载URL

```python
from atomgit_hub import hub_download_url

# 获取文件直接下载链接
url = hub_download_url(
    repo_id="username/repo-name",
    filename="model.bin",
    revision="main"
)
print(f"下载链接: {url}")
```

### 3. SDK上传功能

SDK 有两条上传路径，能力不同：

| 接口 | 适用场景 | 说明 |
|---|---|---|
| `atomgit_hub.upload_folder` | 目录上传 | huggingface_hub 风格，**只接受目录**，传入文件会抛 `NotADirectoryError` |
| `atomgit.api.upload_folder` / `atomgit.api.upload_directory` | 单文件 / 目录 | CLI 使用的同层接口，支持全部上传参数（见下表） |

#### 上传目录（atomgit_hub）

```python
from atomgit_hub import upload_folder

# 上传到仓库根目录
upload_folder(
    folder_path="./my-model",
    repo_id="username/repo-name",
    commit_message="上传模型",
)

# 上传到仓库子目录 models/
upload_folder(
    folder_path="./my-model",
    repo_id="username/repo-name",
    path_in_repo="models/",
    commit_message="上传模型到 models/",
    upload_timeout=1200.0,   # 大目录调大超时
)
```

`atomgit_hub.upload_folder` 参数：

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `folder_path` | str/Path | 必需 | 本地目录，**必须是目录**，传文件会抛 `NotADirectoryError` |
| `repo_id` | str | 必需 | 仓库 ID，支持 `owner/repo` 与三层格式 |
| `token` | str | None | 访问令牌，默认使用 CLI 登录凭证 |
| `repo_type` | str | None | 仓库类型：`model` / `dataset` |
| `revision` | str | None | 目标分支或标签 |
| `commit_message` | str | None | 提交消息，默认 `Upload folder <目录名>` |
| `path_in_repo` | str | `"./"` | 仓库内目标目录前缀 |
| `ignore_patterns` | list | None | 排除的文件 glob 模式 |
| `upload_timeout` | float | `300.0` | 单次请求超时（秒），调用结束后自动还原 |

上传数据集、过滤文件：

```python
upload_folder(
    folder_path="./my-dataset",
    repo_id="username/my-dataset",
    repo_type="dataset",
    ignore_patterns=["*.tmp", "raw/*"],
)
```

> 单文件上传请使用下面的 `atomgit.api.upload_folder`，本函数只处理目录。

#### 上传单个文件 / 带参数的目录上传（atomgit.api）

```python
from pathlib import Path
from atomgit import api

# 单文件上传：remote_path 是仓库内的完整目标路径
api.upload_folder(
    Path("./model.bin"),
    "username/repo-name",
    remote_path="models/model.bin",
    message="上传模型文件",
)

# 目录上传：只传权重、排除日志，放到仓库 ckpt/ 子目录
api.upload_directory(
    Path("./my-model"),
    "username/repo-name",
    path_in_repo="ckpt",
    message="上传模型",
    repo_type="model",
    include=["*.safetensors"],
    exclude=["*.log"],
)

# 上传到数据集仓库
api.upload_directory(
    Path("./my-dataset"),
    "username/my-dataset",
    repo_type="dataset",
    message="上传数据集",
)
```

这两个方法返回 `True`/`False`，失败时会打印具体原因。参数与 CLI 一一对应：

| SDK 参数 | CLI 参数 | 说明 |
|---|---|---|
| `repo_id` | `--repo-id` | 仓库 ID |
| `remote_path`（`upload_folder`） | `PATH_IN_REPO` | 单文件的目标路径 |
| `path_in_repo`（`upload_directory`） | `PATH_IN_REPO` | 目录的目标前缀 |
| `message` | `-m` / `--message` / `--commit-message` | 提交消息 |
| `revision` | `--revision` | 上传的目标分支，默认仓库默认分支 |
| `repo_type` | `--repo-type` | `model` / `dataset` |
| `include` | `--include` | 包含的 glob 列表 |
| `exclude` | `--exclude` | 排除的 glob 列表 |
| `token` | `--token` | 访问令牌，传入后优先使用并忽略登录凭证 |
| `upload_timeout` | `--timeout` | 单次请求超时（秒），调用结束后自动还原 |

#### 批量上传（使用CLI）

批量上传也可以直接调用 CLI，便于复用登录态与参数校验：

```python
import subprocess

result = subprocess.run([
    "atomgit", "upload", "./model-directory",
    "--repo-id", "username/repo-name",
    "--commit-message", "上传完整模型"
], capture_output=True, text=True)

if result.returncode == 0:
    print("上传成功")
else:
    print(f"上传失败: {result.stderr}")
```

### 4. 仓库管理

#### 创建新仓库

```python
from atomgit_hub import create_repository

# 创建公开仓库
repo_url = create_repository(
    repo_id="username/new-repo",
    private=False,
    repo_type="model"  # 或 "dataset"
)
print(f"仓库创建成功: {repo_url}")

# 创建私有仓库
create_repository(
    repo_id="username/private-repo",
    private=True,
    exist_ok=True  # 如果已存在不报错
)
```

### 5. 认证管理

SDK与CLI共享相同的认证配置：

```python
# 方法1：使用CLI登录（推荐）
# 在终端运行：atomgit login

# 方法2：在代码中直接提供token
from atomgit_hub import snapshot_download

snapshot_download(
    "username/repo-name",
    local_dir="./model",
    token="your-access-token"  # 直接传入token
)
```

### 6. 错误处理

```python
from atomgit_hub import snapshot_download

try:
    path = snapshot_download(
        "username/repo-name",
        local_dir="./model"
    )
    print(f"下载成功: {path}")
except Exception as e:
    if "401" in str(e) or "403" in str(e):
        print("认证失败，请先使用 'atomgit login' 登录")
    elif "404" in str(e):
        print("仓库不存在，请检查仓库名称")
    else:
        print(f"下载失败: {e}")
```

### 7. 完整示例

```python
from atomgit_hub import (
    snapshot_download, 
    upload_folder, 
    create_repository
)

def download_and_modify_model():
    """下载模型，修改后重新上传的完整示例"""
    
    # 1. 下载模型
    print("正在下载模型...")
    model_path = snapshot_download(
        "source-user/original-model",
        local_dir="./downloaded-model"
    )
    
    # 2. 创建新仓库
    print("创建新仓库...")
    create_repository(
        repo_id="my-user/modified-model",
        repo_type="model",
        exist_ok=True
    )
    
    # 3. 修改模型文件（示例）
    import os
    readme_path = os.path.join(model_path, "README.md")
    with open(readme_path, "a") as f:
        f.write("\n\n## 修改说明\n\n这是基于原模型的修改版本。")
    
    # 4. 上传修改后的文件
    print("上传修改后的文件...")
    upload_folder(
        folder_path=readme_path,
        path_in_repo="README.md",
        repo_id="my-user/modified-model",
        commit_message="更新README文档"
    )
    
    print("完成！")

# 运行示例
if __name__ == "__main__":
    download_and_modify_model()
```

## 配置文件

配置文件保存在 `~/.atomgit/config.json`，包含用户认证信息和其他设置。

## API端点配置

工具已预配置为连接AtomGit平台API端点：
- **API端点**：`https://hub.atomgit.com`
- **环境变量**：`HF_ENDPOINT=https://hub.atomgit.com`

此配置在程序启动时自动设置，用户无需手动配置。

## Git集成功能详解

### 自动配置

当你使用 `atomgit login` 登录成功后，工具会自动配置Git凭证，让你可以直接使用标准Git命令操作AtomGit仓库。

### 支持的Git操作

登录后，你可以直接使用以下Git命令，无需手动输入token：

```bash
# 克隆仓库（支持两种域名格式）
git clone https://atomgit.com/username/repo-name.git
git clone https://hub.atomgit.com/username/repo-name.git

# 推送代码
git push origin main

# 拉取更新
git pull origin main

# 添加远程仓库
git remote add origin https://atomgit.com/username/repo-name.git
```

### 安全性

- 凭证配置仅对 `atomgit.com` 和 `hub.atomgit.com` 域名生效
- token 安全存储在本地配置文件中
- 不影响其他Git仓库的认证配置
- `atomgit logout` 时自动清除凭证配置

### 注意事项

- 支持的URL格式：`https://atomgit.com/...` 或 `https://hub.atomgit.com/...`
- 如果Git命令仍需要输入密码，请重新登录：`atomgit logout` 然后 `atomgit login`

## 错误处理

- 如果遇到网络错误，工具会自动重试
- 上传大文件时会显示进度条
- 所有操作都有详细的错误信息提示

## 支持的文件类型

- 支持所有文件类型的上传和下载
- 自动处理目录结构
- 支持大文件传输

## 开发

### 项目结构

```
atomgit/
├── __init__.py          # 包初始化，导出SDK接口
├── __main__.py          # 主入口
├── cli.py               # CLI命令定义
├── api.py               # Hugging Face Hub API客户端
├── config.py            # 配置管理
├── utils.py             # 工具函数
├── atomgit_hub.py       # Python SDK接口
├── requirements.txt     # 依赖包
├── setup.py             # 包安装配置
└── README.md           # 说明文档
```

### 本地开发

```bash
# 克隆项目
git clone https://atomgit.com/gitcode-ai/atomgit_cli.git
cd atomgit_cli

# 安装依赖
pip install -r requirements.txt

# 开发模式安装
pip install -e .

# 测试CLI功能
atomgit --help

# 测试SDK功能
python -c "from atomgit_hub import snapshot_download; print('SDK导入成功')"

# 运行测试
python -m pytest tests/
```

## Python版本兼容性

本项目支持Python 3.8+版本，包括：

- ✅ Python 3.8
- ✅ Python 3.9  
- ✅ Python 3.10
- ✅ Python 3.11
- ✅ Python 3.12
- ✅ Python 3.13

### 兼容性测试

运行兼容性测试：

```bash
python test_compatibility.py
```

详细兼容性信息请参考 [PYTHON_COMPATIBILITY.md](PYTHON_COMPATIBILITY.md)

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！

### 贡献指南

在贡献代码时，请确保：

1. 代码兼容Python 3.8+
2. 运行兼容性测试
3. 更新相关文档

## 联系我们

- 邮箱：support@atomgit.com
- 项目地址：https://atomgit.com/gitcode-ai/atomgit_cli
- 问题报告：https://atomgit.com/gitcode-ai/atomgit_cli/issues 
