Metadata-Version: 2.4
Name: gitinsight-cli
Version: 0.1.1
Summary: A powerful collection of Git repository analysis tools and visualizations.
Project-URL: Homepage, https://github.com/Rain-kl/GitInsight
Project-URL: Bug Tracker, https://github.com/Rain-kl/GitInsight/issues
Author-email: Ryan <ryan@arctel.net>
License-Expression: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Requires-Dist: loguru>=0.7.3
Requires-Dist: pandas>=3.0.0
Requires-Dist: pyecharts>=2.0.0
Requires-Dist: tqdm>=4.67.3
Description-Content-Type: text/markdown

# GitInsight

GitRepository Analysis and Visualization Tool / Git 仓库分析与可视化工具

<!-- PROJECT SHIELDS -->

[![MIT License][license-shield]][license-url]
[![PyPI Version][pypi-version]][pypi-url]
[![Python Versions][python-version]][pypi-url]
[![Release][release-shield]][release-url]

---

## 目录

- [GitInsight](#gitinsight)
  - [目录](#目录)
    - [上手指南](#上手指南)
          - [开发前的配置要求](#开发前的配置要求)
          - [**安装步骤**](#安装步骤)
    - [文件目录说明](#文件目录说明)
    - [开发的架构](#开发的架构)
    - [部署](#部署)
    - [发布新版本](#发布新版本)
    - [使用到的框架](#使用到的框架)
    - [贡献者](#贡献者)
      - [如何参与开源项目](#如何参与开源项目)

### 上手指南

###### 开发前的配置要求

1. Python >= 3.12
2. uv (推荐使用 uv 进行包管理) 或 pip

###### **安装步骤**

1. Clone the repo

```sh
git clone https://github.com/Rain-kl/GitInsight.git
cd GitInsight
```

2. Install as a command-line tool

```sh
# Install from PyPI
uv tool install gitinsight-cli

# Install from the current checkout
uv tool install .

# Or install directly from GitHub
uv tool install git+https://github.com/Rain-kl/GitInsight.git
```

3. Run the tool

```sh
gitinsight /path/to/git/repository
```

Upgrade or uninstall the tool:

```sh
uv tool upgrade gitinsight-cli
uv tool uninstall gitinsight-cli
```

For local development:

```sh
uv sync
uv run gitinsight /path/to/git/repository
```

### 文件目录说明

```
GitInsight
├── .github/             # GitHub 配置
├── gitinsight/          # 源代码目录
│   ├── __init__.py
│   ├── __main__.py      # 程序入口
│   ├── analysis.py      # 分析逻辑 (Pandas)
│   ├── charts.py        # 图表绘制 (Pyecharts)
│   ├── dashboard.py     # 仪表盘展示
│   ├── git_reader.py    # Git日志读取
│   └── report.py        # 报告生成
├── .gitignore
├── pyproject.toml       # 项目配置与依赖
├── uv.lock              # 依赖锁定文件
└── README.md            # 项目说明
```

### 开发的架构

本项目主要由数据读取、数据分析、图表生成和仪表盘展示四个部分组成。
- `git_reader.py`: 负责读取 Git 仓库的提交日志。
- `analysis.py`: 使用 Pandas 对日志数据进行清洗和统计分析。
- `charts.py`: 使用 Pyecharts 生成各类可视化图表。
- `dashboard.py`: 整合图表生成 HTML 仪表盘。

请阅读架构文档(如有)查阅为该项目的架构。

### 部署

本项目作为 Python 命令行工具发布到
[PyPI](https://pypi.org/project/gitinsight-cli/)，安装后的命令名为
`gitinsight`。

### 发布新版本

1. 更新 `pyproject.toml` 中的版本并刷新锁文件：

```sh
uv version 0.2.0
uv lock
```

2. 提交版本变更，然后创建并推送同版本标签：

```sh
git tag -a v0.2.0 -m "v0.2.0"
git push GitInsight main
git push GitInsight v0.2.0
```

`v*` 标签会触发 GitHub Actions。工作流会校验标签与项目版本一致，
构建 wheel 和源码包、创建 GitHub Release，并通过 PyPI Trusted
Publishing 发布，无需配置长期 PyPI Token。

### 使用到的框架

- [Pandas](https://pandas.pydata.org/) - Data structures and analysis tools
- [Pyecharts](https://github.com/pyecharts/pyecharts) - Python Echarts Plotting Library
- [Loguru](https://github.com/Delgan/loguru) - Python logging made (stupidly) simple
- [Hatchling](https://hatch.pypa.io/latest/) - Modern, extensible Python build backend

### 贡献者

请阅读**CONTRIBUTING.md** 查阅为该项目做出贡献的开发者。

#### 如何参与开源项目

贡献使开源社区成为一个学习、激励和创造的绝佳场所。你所作的任何贡献都是**非常感谢**的。

1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

<!-- links -->
[license-shield]: https://img.shields.io/github/license/shaojintian/Best_README_template.svg?style=flat-square
[license-url]: https://github.com/Rain-kl/GitInsight/blob/main/LICENSE
[pypi-version]: https://img.shields.io/pypi/v/gitinsight-cli
[pypi-url]: https://pypi.org/project/gitinsight-cli/
[python-version]: https://img.shields.io/pypi/pyversions/gitinsight-cli
[release-shield]: https://github.com/Rain-kl/GitInsight/actions/workflows/release.yml/badge.svg
[release-url]: https://github.com/Rain-kl/GitInsight/actions/workflows/release.yml
