# gitlabanalyzer

**Repository Path**: cubeiic-hanxuan/gitlabanalyzer

## Basic Information

- **Project Name**: gitlabanalyzer
- **Description**: 自动化多维统计：支持从代码提交量、变更文件数、注释占比、任务分支关联度等维度生成分析数据；
一键导出 Excel 报表：内置标准化报表模板，可快速输出可视化统计结果，满足研发进度追踪、资源分配优化等管理场景；
低代码配置：通过图形化界面灵活设置统计规则，避免重复编写脚本，显著提升研发效能管理效率。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-03-16
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GitLabAnalyzer

一个基于 PySide6 的 GitLab 代码贡献分析工具。它会遍历你有权限访问的 GitLab 项目与分支，在指定时间范围内统计提交次数与代码变更行数，并导出为 Excel 报表（含用户/项目/分支汇总）。

## 功能概览

- 扫描可访问的所有项目（支持排除指定项目）
- 扫描每个项目的所有分支，拉取提交（with_stats）并统计：
  - 提交次数
  - 增加行数 / 删除行数 / 总变更行数
  - 日均提交次数 / 日均变更行数
  - 首次提交日期 / 最后提交日期
- GUI 配置：GitLab 地址、Token、时间范围、输出目录、文件名、并发线程数
- 导出 Excel：`用户统计` + `用户汇总`/`项目汇总`/`分支汇总`

## 项目结构

- [gitlabAnalyzer.py](gitlabanalyzer/gitlabAnalyzer.py)：GUI 主程序（入口在 `main()`）
- [gitlab_code_analyzer.py](gitlabanalyzer/gitlab_code_analyzer.py)：核心分析逻辑与 Excel 写入器
- [requirements.txt](gitlabanalyzer/requirements.txt)：依赖列表
- [app.sh](gitlabanalyzer/app.sh)：macOS 打包脚本（Nuitka + create-dmg）
- [build-exe.bat](gitlabanalyzer/build-exe.bat)：Windows 打包脚本（当前脚本内容可能与本仓库入口不一致）
- [LICENSE](gitlabanalyzer/LICENSE)：MIT License

## 环境要求

- Python 3（建议使用较新的版本）
- 网络可访问 GitLab 实例
- 一个具备 API 权限的 GitLab Personal Access Token（通常需要 `api` scope）

依赖见 [requirements.txt](gitlabanalyzer/requirements.txt)，核心包括：PySide6、python-gitlab、xlsxwriter、pyqtdarktheme。

## 安装

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

## 运行（GUI）

```bash
python gitlabAnalyzer.py
```

在界面中填写：

- GitLab地址：例如 `https://gitlab.example.com`
- Private Token：例如 `glpat-...`
- 开始日期 / 结束日期：统计时间范围
- 排除项目：用逗号分隔的项目名（按 `project.name` 精确匹配）
- 输出目录：报表输出目录
- Excel文件名：默认为 `gitlab_comprehensive_analysis_report.xlsx`
- 并发线程数：按“项目维度”并发分析（默认 5，范围 1–20）

点击“开始分析”，完成后会弹出结果窗口，并可再次导出 Excel。

## 报表说明

Excel 输出路径：`<输出目录>/<Excel文件名>`

工作表：

- `用户统计`：按人员汇总的主表
- `用户汇总`：从主表抽取关键字段并按提交次数排序
- `项目汇总`：按项目聚合统计
- `分支汇总`：按“项目:分支”聚合统计

`用户统计`主要字段（以当前实现为准）：

- 基本信息：`姓名`、`用户名`、`邮箱`
- 参与范围：`参与项目数`、`参与分支数`、`参与项目列表`、`参与分支列表`
- 提交与变更：`提交次数`、`日均提交次数`、`增加行数`、`删除行数`、`总变更行数`、`日均变更行数`
- 其它：`变更度(%)`（增加行数 / 总变更行数 * 100）、`首次提交日期`、`最后提交日期`、`是否活跃`

## 统计口径与限制（重要）

- 时间过滤：提交时间使用 ISO 字符串解析为“无时区 datetime”后，与开始/结束日期比较。
- 合并提交：如果检测到 `parent_ids` 多于 1 个，会跳过该提交（视为 merge commit）。
- 分支范围：会拉取项目的所有分支并逐一统计。
- 人员口径：当前实现只会把 `access_level_name == "Contributor"` 的用户写入主表。
  - 项目成员列表中的用户通常会被标记为 `Guest/Reporter/Developer/...`，因此可能不会出现在最终 `用户统计` 中。
  - 只有当用户信息来自提交作者（缺少成员权限信息）时，才会被标记为 `Contributor` 并纳入统计。
  - 如果你希望统计所有成员/所有提交作者，需要调整 [calculate_comprehensive_metrics](gitlabanalyzer/gitlab_code_analyzer.py#L564-L671) 中的过滤逻辑。

## 作为库使用（脚本调用）

核心分析类在 [GitLabCodeAnalyzer](gitlabanalyzer/gitlab_code_analyzer.py#L223)：

```python
from gitlab_code_analyzer import GitLabCodeAnalyzer

analyzer = GitLabCodeAnalyzer(
    url="https://gitlab.example.com",
    token="glpat-xxxxxxxxxxxxxxxxxxxx",
    start_date="2026-01-01",
    end_date="2026-01-31",
    excluded_projects=["demo-project"],
    max_workers=5,
)

analyzer.analyze_all_projects()
analyzer.generate_report(output_dir="report", filename="gitlab_report.xlsx")
```

## 打包

- macOS：参考 [app.sh](gitlabanalyzer/app.sh)（Nuitka 打包并生成 dmg）
- Windows：参考 [build-exe.bat](gitlabanalyzer/build-exe.bat)（该脚本当前引用的入口文件名可能需要按本仓库实际入口调整）

## 安全提示

- GUI 会用 `QSettings` 记住你填写的配置，其中包含 Private Token；请确保你的系统账户与配置存储位置安全。
- “导出配置”会把 Token 以明文写入 JSON 文件；请不要把该文件提交到版本库或分享给无关人员。

## License

MIT License，见 [LICENSE](gitlabanalyzer/LICENSE)。