# mobile-git-client

**Repository Path**: yzli_dev/mobile-git-client

## Basic Information

- **Project Name**: mobile-git-client
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Mobile Git Client

一个 Android 原生 Git 客户端应用，支持在手机上搜索/克隆 Gitee 仓库，并执行完整的 Git 常用操作。

## 功能特性

### 仓库搜索与克隆
- **搜索仓库**：按关键词搜索 Gitee 仓库，查看仓库详情
- **直接克隆**：粘贴仓库 URL 一键克隆，无需 API 查询
- **克隆进度**：实时显示克隆/拉取进度

### Git 常用操作
- **Git Add / Commit / Push**：暂存、提交并推送更改（一键完成或分步执行）
- **Git Pull**：拉取远程最新更新并合并
- **Git Fetch**：获取远程更新但不合并
- **Git Reset**：`reset --hard HEAD` 丢弃所有未提交更改（带二次确认）
- **Git Stash**：暂存当前更改（stash）和恢复暂存（stash pop）
- **Git Revert**：通过 commit hash 撤销指定提交

### 仓库浏览
- **提交历史**：查看 commit 列表（hash / 作者 / 日期 / 提交信息）
- **文件差异**：工作区与 HEAD 的差异对比，行级 patch 展示（红删 / 绿增）
- **分支管理**：列出所有分支、切换分支、创建新分支、删除分支
- **文件浏览器**：浏览仓库目录结构，查看文件内容

### 本地管理
- **仓库列表**：查看所有已克隆仓库，支持删除
- **存储路径**：可选应用私有目录 / Downloads / Documents / 自定义路径
- **设置**：Gitee Token 配置、Git 作者信息（name / email）

## 技术栈

| 类别 | 技术 |
|------|------|
| 语言 | Kotlin 1.9.22 |
| UI 框架 | Jetpack Compose (BOM 2024.02.00) + Material 3 |
| Git 引擎 | JGit 5.13.0（纯 Java Git 实现，无需系统 git） |
| 架构模式 | MVVM（ViewModel + StateFlow + Repository） |
| 依赖注入 | 手动 DI（AppContainer + AppViewModelFactory） |
| 本地持久化 | DataStore Preferences |
| 导航 | Navigation Compose |
| 网络请求 | Retrofit 2.9 + OkHttp 4.12 + Gson |
| 异步 | Kotlin Coroutines 1.7.3 |
| 构建 | Gradle 8.5 + AGP 8.2.2 |

## 环境要求

- **JDK**：17 或更高（推荐 JDK 21）
- **Android SDK**：compileSdk 34，minSdk 26（Android 8.0+）
- **Gradle**：8.5（项目已内置 gradlew，无需单独安装）
- **Android Studio**：推荐 Hedgehog (2023.1) 或更高版本

## 构建方式

### 1. 配置 SDK 路径

在项目根目录创建 `local.properties` 文件，指定 Android SDK 路径：

```properties
# Windows
sdk.dir=C\:\\Users\\<用户名>\\AppData\\Local\\Android\\Sdk

# macOS
sdk.dir=/Users/<用户名>/Library/Android/sdk

# Linux
sdk.dir=/home/<用户名>/Android/Sdk
```

### 2. 命令行构建

```bash
# Debug APK
./gradlew assembleDebug

# Release APK（需配置签名）
./gradlew assembleRelease
```

构建产物路径：
- Debug：`app/build/outputs/apk/debug/app-debug.apk`
- Release：`app/build/outputs/apk/release/app-release.apk`

### 3. Android Studio 构建

1. 打开 Android Studio → File → Open → 选择项目根目录
2. 等待 Gradle Sync 完成
3. 点击 Build → Build Bundle(s) / APK(s) → Build APK(s)

### 4. 使用系统 Gradle 构建（无 gradlew 场景）

```bash
# 确保系统已安装 Gradle 8.5
gradle -p <项目路径> assembleDebug --no-daemon
```

## 项目结构

```
mobile-git-client/
├── app/
│   ├── src/main/
│   │   ├── java/com/mobilegit/client/
│   │   │   ├── data/
│   │   │   │   ├── api/              # Gitee API 接口与 DTO
│   │   │   │   ├── local/            # DataStore 本地存储
│   │   │   │   └── repository/       # Repository 层
│   │   │   ├── di/                   # 手动依赖注入
│   │   │   ├── domain/
│   │   │   │   └── model/            # 领域数据模型
│   │   │   ├── git/                  # JGit 封装（GitManager）
│   │   │   ├── ui/
│   │   │   │   ├── components/       # 通用 UI 组件
│   │   │   │   ├── navigation/       # 路由导航
│   │   │   │   ├── screens/          # 页面
│   │   │   │   │   ├── search/       # 搜索页
│   │   │   │   │   ├── detail/       # 仓库详情页
│   │   │   │   │   ├── clone/        # 克隆进度页
│   │   │   │   │   ├── local/        # 本地仓库列表页
│   │   │   │   │   ├── git_ops/      # Git 操作仪表盘
│   │   │   │   │   ├── commit_log/   # 提交历史页
│   │   │   │   │   ├── branch_manager/ # 分支管理页
│   │   │   │   │   ├── diff/         # 文件差异页
│   │   │   │   │   ├── file_browser/ # 文件浏览器页
│   │   │   │   │   └── settings/     # 设置页
│   │   │   │   └── theme/            # Material 3 主题
│   │   │   ├── util/                 # 工具类
│   │   │   ├── MainActivity.kt
│   │   │   └── MobileGitApplication.kt
│   │   ├── res/                      # 资源文件
│   │   └── AndroidManifest.xml
│   └── build.gradle.kts
├── gradle/wrapper/
├── build.gradle.kts
├── settings.gradle.kts
├── gradle.properties
├── gradlew / gradlew.bat
└── local.properties                  # SDK 路径（需自行创建）
```

## 导航路由

| 路由 | 页面 | 说明 |
|------|------|------|
| `search` | SearchScreen | 搜索 Gitee 仓库（底部 Tab） |
| `local` | LocalReposScreen | 本地仓库列表（底部 Tab） |
| `settings` | SettingsScreen | 设置页（底部 Tab） |
| `detail/{owner}/{repo}` | RepoDetailScreen | 仓库详情 |
| `clone/{repoId}` | CloneProgressScreen | 克隆进度 |
| `git_ops/{repoId}` | GitOpsScreen | Git 操作仪表盘 |
| `commit_log/{repoId}` | CommitLogScreen | 提交历史 |
| `branch_manager/{repoId}` | BranchManagerScreen | 分支管理 |
| `diff/{repoId}` | DiffScreen | 文件差异 |
| `file_browser/{repoId}` | FileBrowserScreen | 文件浏览 |

## 权限说明

| 权限 | 用途 |
|------|------|
| `INTERNET` | 访问 Gitee API、远程 Git 操作 |
| `ACCESS_NETWORK_STATE` | 检测网络连接状态 |
| `WRITE_EXTERNAL_STORAGE` | 写入仓库到外部存储（API ≤ 29） |
| `READ_EXTERNAL_STORAGE` | 读取外部存储中的仓库（API ≤ 32） |
| `MANAGE_EXTERNAL_STORAGE` | 管理外部存储（可选存储路径时需要） |

## 使用指南

1. **安装 APK**：将 `app-debug.apk` 传输到手机安装
2. **配置 Token**：打开应用 → 切换到「我的」→ 填入 Gitee 私人访问 Token
3. **配置作者**：在同一页面设置 Git 作者姓名和邮箱
4. **选择存储路径**：选择仓库克隆的存储位置
5. **搜索并克隆**：在「搜索」页搜索仓库或直接粘贴 URL 克隆
6. **Git 操作**：在「仓库」页点击仓库的 Git 操作图标，进入操作仪表盘

## License

MIT