GitLab Tool 🦊

GitLab操作可视化工具，提供便捷的Merge Request创建和管理功能。支持智能分支选择、项目筛选、MR状态查看、文件差异浏览等高级功能。集成专业文件图标，提供直观的代码变更可视化界面。

✨ 功能特性

🚀 核心功能

• 可视化MR创建：通过直观的界面创建GitLab Merge Request
• MR全生命周期管理：查看MR列表、详情、合并状态和冲突信息
• MR审核功能：支持MR同意、拒绝、关闭等操作，具备权限检查机制
• 文件差异浏览：可视化显示代码变更，支持语法高亮和行号对比
• 智能分支选择：自动获取源分支和目标分支列表，支持分支缓存机制
• 标题自动填充：根据源分支最新commit自动填充MR标题
• 实时状态显示：可视化显示分支选择和MR状态
• 智能缓存：项目列表和分支信息缓存机制，减少API调用，提升加载速度
• 项目筛选：支持本地仓库智能筛选和搜索关键字过滤
• 分页加载：可配置的项目分页加载，优化大量项目的显示性能
• 智能文件树：单文件变更时自动隐藏文件树，多文件时支持折叠展开操作
• 专业图标集成：使用Devicon图标库，支持100+种文件类型的专业图标显示
• MR创建后自动刷新：创建MR成功后自动刷新项目列表，提升用户体验
• 视觉反馈增强：MR返回列表闪烁动画，文件数量高亮显示，文件差异编号
• MR评论系统：支持查看和添加MR评论，实现团队协作沟通，评论数量准确显示
• 成员管理功能：支持查看项目成员，配置@提及成员列表
• 权限智能检查：自动检查用户权限，动态显示可用操作按钮
• 多语言代码高亮：支持20+种编程语言的语法高亮显示
• 即时数量显示：MR详情页变更和评论tab数量进入页面时立即显示，无需等待点击加载

🎯 界面特色

• GitLab风格图标：使用GitLab狐狸🦊图标，品牌识别度高
• Tab式导航：MR提交、MR审核、@成员设置三大功能模块，清晰分离
• 简洁直观：纯文字分支显示，界面清爽无干扰
• 智能交互：选择分支后实时显示合并关系
• 状态提示：MR状态显示，创建后可查看合并状态和冲突信息
• 动态按钮：筛选按钮智能显示/隐藏，根据本地仓库状态自动调整
• 权限感知界面：根据用户权限动态显示可用操作按钮
• 实时反馈：配置变更时自动更新界面状态和缓存
• 智能文件树：单文件变更时自动隐藏左侧文件树，直接显示差异内容
• 文件夹交互：支持文件夹折叠展开，箭头图标带悬停效果和过渡动画
• 专业图标：集成Devicon图标库，为不同文件类型显示专业图标
• 文件编号：文件差异列表添加编号，便于快速定位和引用
• 高亮动画：MR返回列表时的闪烁高亮效果，文件数量的高亮样式
• 代码统计：显示文件变更的代码行数统计（+增加/-删除）
• 评论交互：支持实时查看和添加MR评论，提升协作体验
• 成员头像：显示项目成员头像和详细信息，便于团队识别

📦 安装配置

安装插件

1. 下载.vsix文件
2. 在VS Code中按Ctrl+Shift+P打开命令面板
3. 输入Extensions: Install from VSIX...
4. 选择下载的.vsix文件
5. 重启VS Code

配置GitLab连接

1. 打开VS Code设置 (Ctrl+,)
2. 搜索gitlabtool
3. 配置以下设置：
   • GitLab Host URL: 你的GitLab服务器地址（默认：https://gitlab.com）
   • GitLab Personal Access Token: 你的GitLab访问令牌

获取GitLab Token

1. 登录GitLab，进入Settings > Access Tokens
2. 创建新token，权限至少包含：
   • api - 完整API访问权限（必需）
   • read_user - 读取用户信息（必需）
   • read_repository - 读取仓库信息（必需）
   • write_repository - 创建MR权限（必需）
3. 安全提示：Token具有高级权限，请妥善保管，不要分享给他人
4. 有效期：建议设置合理的过期时间，定期更新Token

🚀 使用指南

基本操作流程

MR创建流程

1. 打开插件：点击VS Code左侧活动栏的GitLab狐狸图标🦊
2. 选择项目：从项目列表中点击要创建MR的项目
3. 选择分支：
   • 选择源分支（要合并的分支）- 自动填充MR标题
   • 选择目标分支（合并目标）- 自动检测冲突
4. 创建MR：点击"确认创建 Merge Request"按钮创建合并请求
5. 查看状态：MR创建成功后可查看合并状态和冲突信息

MR审核流程

1. 切换到MR审核Tab：在项目界面中点击"MR审核"标签页
2. 浏览MR列表：查看项目中的所有MR，支持分页浏览
3. 查看MR详情：点击MR项目查看详细信息、文件变更和评论
4. 审核操作：根据权限进行同意、拒绝或关闭MR操作
5. 添加评论：在MR详情页面添加审核意见和建议

成员管理流程

1. 切换到@成员设置Tab：在项目界面中点击"@成员设置"标签页
2. 查看项目成员：浏览项目所有成员列表，包含头像和详细信息
3. 配置提及列表：选择常用的@提及成员，便于快速引用

快速上手技巧

• 首次使用：确保已配置GitLab Token和Host URL
• 项目筛选：在Git仓库中使用时，筛选按钮会自动显示
• 搜索项目：使用searchKeyword配置快速定位项目
• 性能优化：调整perPage和maxPages参数控制加载项目数量

缓存和刷新功能

• 多层缓存：项目列表和分支信息在插件运行期间永久缓存，避免频繁API调用
• 强制刷新：点击视图标题栏的刷新按钮🔄可立即更新项目列表并清除所有缓存
• 智能刷新：配置变更时会自动清除相关缓存并重新加载
• 分支缓存：分支信息永久缓存，提升分支选择响应速度
• 插件重启：重新打开插件时会自动清除缓存，获取最新数据

智能筛选功能

• 智能显示: 筛选按钮仅在本地Git仓库存在于GitLab项目列表中时显示
• 自动检测: 插件会自动检测本地仓库是否匹配远程GitLab项目
• 动态隐藏: 如果本地仓库不在远程项目列表中，筛选按钮将自动隐藏，只显示全部项目
• 实时更新: 当项目列表或配置发生变化时，自动更新筛选按钮的可见性
• 搜索过滤: 支持通过搜索关键字过滤项目，支持正则表达式匹配
• 分页控制: 可配置每页项目数量和最大页数，优化大量项目的加载性能

界面说明

Tab导航界面

┌─────────────────────────────────────────────────────────┐
│ 🦊 MR管理系统 - ProjectName                              │
├─────────────────────────────────────────────────────────┤
│ [MR提交] [MR审核] [@成员设置]                            │
└─────────────────────────────────────────────────────────┘

MR提交界面

源分支选择 ↓
┌─────────────────┐    ┌─────────────────┐
│ 选择源分支      │    │ 选择目标分支    │
└─────────────────┘    └─────────────────┘

    feature/login  →合并到→  master

┌─────────────────────────────────────────┐
│ MR标题（自动填充最新commit信息）        │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│ 📝 填写MR标题和描述信息                 │
└─────────────────────────────────────────┘

        ┌─────────────────────┐
        │ 确认创建 Merge Request │
        └─────────────────────┘

MR审核界面

┌─────────────────────────────────────────┐
│ MR列表 (分页浏览)                       │
├─────────────────────────────────────────┤
│ 📋 MR [#123](https://github.com/json/gitlabtool/issues/123): 添加用户登录功能            │
│    状态: 待审核 | 文件: 5个 | 冲突: 无   │
│    [查看详情] [同意] [拒绝]             │
├─────────────────────────────────────────┤
│ 📋 MR [#122](https://github.com/json/gitlabtool/issues/122): 修复登录bug                 │
│    状态: 已合并 | 文件: 2个             │
└─────────────────────────────────────────┘

成员管理界面

┌─────────────────────────────────────────┐
│ 项目成员列表                            │
├─────────────────────────────────────────┤
│ 👤 张三 (@zhangsan)                     │
│    权限: Developer | ✅ 已选择          │
├─────────────────────────────────────────┤
│ 👤 李四 (@lisi)                         │
│    权限: Maintainer | ☐ 未选择         │
└─────────────────────────────────────────┘

高级配置

分页配置优化

• perPage: 控制单次API请求的项目数量，建议值：10-20
• maxPages: 控制总加载页数，建议值：1-3
• 总项目数: perPage × maxPages，建议不超过100个项目

搜索过滤配置

• searchKeyword: 支持普通文本和正则表达式
• 示例: ^my-project.* 匹配以"my-project"开头的项目
• 注意: 仅在全部列表模式下生效，筛选模式下不生效

⚙️ 配置选项

GitLab Tool 设置

🔧 开发信息

技术栈

• 框架: VS Code Extension API
• 语言: TypeScript
• 构建: Webpack
• GitLab API: @gitbeaker/rest
• 图标库: Devicon - 支持100+种文件类型的专业开发图标
• 代码高亮: Highlight.js - 支持20+种编程语言语法高亮
• 打包工具: @vscode/vsce
• UI组件: 自定义WebView组件，支持Tab导航、文件树、差异显示、动画效果
• 状态管理: VS Code GlobalState - 用于缓存和配置持久化

架构组件

• GitLabService: GitLab API服务层，负责项目、分支、MR、评论、成员等数据获取
• WebViewManager: WebView界面管理，处理Tab导航、MR创建、审核、成员管理等界面交互
• MRViewProvider: TreeView数据提供者，管理项目列表显示和筛选
• GitUtils: Git工具类，处理本地Git仓库相关操作
• 缓存系统: 多层缓存机制，包括项目列表缓存和分支信息缓存
• 权限管理: 动态权限检查，根据用户权限控制界面功能可用性
• 状态持久化: 基于VS Code GlobalState的配置和状态保存机制

📋 更新日志

[1.0.3] - 当前版本

• 🐛 MR详情页评论数量显示修复 - 修复MR详情页评论tab显示数量与实际用户评论数量不匹配的问题
• ✨ MR详情页即时数量显示 - 优化MR详情页变更和评论tab数量显示逻辑，进入页面时立即显示数量
• 🔧 评论加载机制优化 - 添加评论数据加载失败后的重试机制，确保系统健壮性
• 🔧 版本号更新 - 更新插件版本号至1.0.3

[1.0.2]

• ✨ MR状态筛选功能 - 添加MR状态标签页筛选功能，支持按状态查看MR列表
• ✨ 状态标签页数据缓存 - 优化MR状态标签页的数据缓存机制，提升加载性能
• ✨ MR详情增强显示 - 添加MR详情页变更和评论数量显示功能，提供更丰富的信息
• ✨ 版本号显示功能 - 在界面中添加插件版本号显示，便于版本管理
• 🐛 修复MR管理页面布局 - 解决MR管理页面滚动和布局问题，优化用户体验
• 🔧 版本号更新 - 更新插件版本号至1.0.2

[1.0.1]

• 🚀 MR权限检查优化 - 重构MR权限检查逻辑，支持按分支保护设置判断权限
• ✨ 权限预加载功能 - 优化MR权限检查流程，添加预加载功能提升响应速度
• 🐛 修复MR合并状态显示 - 解决MR列表有时未显示合并状态的问题
• 🎨 优化MR标题显示 - 移除MR标题链接并添加无文件变更提示，提升用户体验
• 🐛 修复webview通知显示问题 - 替换alert弹窗为自定义通知系统，解决VSCode webview环境下alert不显示的问题
• 🔧 版本号更新 - 更新插件版本号至1.0.1

[1.0.0]

• ✨ Tab式导航界面 - 全新的三Tab设计：MR提交、MR审核、@成员设置
• ✨ MR全生命周期管理 - 支持MR创建、审核、同意、拒绝、关闭等完整流程
• ✨ MR评论系统 - 支持查看和添加MR评论，实现团队协作沟通
• ✨ 成员管理功能 - 查看项目成员列表，配置@提及成员，支持头像显示
• ✨ 权限智能检查 - 自动检查用户权限，动态显示可用操作按钮
• ✨ 多语言代码高亮 - 集成Highlight.js，支持20+种编程语言语法高亮
• ✨ 项目列表分页配置 - 支持自定义每页显示数量和最大页数
• ✨ MR创建后自动刷新 - 创建MR成功后自动刷新列表，提升用户体验
• ✨ 智能文件树显示 - 单文件变更时隐藏文件树，直接显示差异内容
• ✨ 文件差异编号 - 文件差异列表添加文件编号，便于快速定位
• ✨ 文件夹交互优化 - 更新文件夹展开图标样式，添加悬停效果和过渡动画
• ✨ 文件树折叠展开 - 支持文件夹的折叠和展开操作，提升大项目浏览体验
• ✨ Devicon图标集成 - 使用Devicon替换文件图标，支持更多文件类型的专业图标显示
• ✨ MR返回列表闪烁动画 - 从MR详情返回列表时，对应MR项添加高亮闪烁效果
• ✨ 文件数量高亮样式 - 文件变更数量使用高亮样式显示，包含代码行数统计
• ✨ 项目筛选功能 - 支持按关键字筛选项目列表
• ✨ 智能缓存系统 - 多层缓存机制，提升加载性能
• ✨ 动态按钮状态 - 根据表单填写状态动态调整按钮可用性
• ✨ 实时反馈机制 - 提供操作状态的实时视觉反馈
• ✨ 状态持久化 - 基于VS Code GlobalState的配置和状态保存
• 🐛 修复MR操作缺少projectId - 解决MR操作中项目ID缺失问题
• 🎨 界面样式优化 - 文件夹图标、文件名显示、详情页头部等多项界面改进

[0.0.9]

• 🎨 文件树样式优化
• 🎨 详情页头部样式改进
• 🐛 修复界面显示问题

[0.1.6]

• 🚀 合并冲突检测: 创建MR前自动检测代码合并冲突
• 🦊 GitLab品牌图标: 使用GitLab风格的狐狸图标
• 🎯 分支显示增强: 可视化显示选中的分支关系
• 📝 界面优化: 简化加载文案，纯文字分支显示

[0.1.5]

• ✨ MR标题自动填充: 根据源分支最新commit自动填充标题
• 🔧 API增强: 新增分支commit信息获取功能

[0.1.4]

• 🏗️ HTML文件分离: 提取HTML代码到独立文件
• 🐛 分支选择优化: 修复目标分支自动选择问题

🔧 故障排除

常见问题

1. 项目列表为空或加载失败

• 检查Token权限：确保Token包含api、read_user、read_repository权限
• 检查网络连接：确保能够访问GitLab服务器
• 检查Host配置：确认GitLab Host URL配置正确
• 调整分页参数：尝试增加perPage或maxPages值

2. 筛选按钮不显示

• 确认Git仓库：当前目录必须是Git仓库
• 检查远程仓库：本地仓库必须与GitLab项目匹配
• 强制刷新：点击刷新按钮更新项目列表

3. 分支加载失败

• 检查项目权限：确保对项目有读取权限
• 清除缓存：使用强制刷新清除分支缓存
• 检查分支存在性：确认分支在远程仓库中存在

4. MR创建失败

• 检查写入权限：确保Token包含write_repository权限
• 检查分支状态：确认源分支和目标分支都存在且可访问
• 查看MR状态：MR创建成功后可在GitLab中查看合并状态和冲突信息

5. MR审核功能不可用

• 检查用户权限：确保用户在项目中具有Developer或更高权限
• 确认Token权限：Token需要包含api和write_repository权限
• 刷新权限状态：切换Tab或刷新页面重新检查权限

6. 成员列表为空

• 检查项目权限：确保对项目有成员查看权限
• 验证Token权限：Token需要包含read_user权限
• 检查项目类型：私有项目可能需要更高权限才能查看成员

7. 评论功能异常

• 检查API权限：确保Token包含完整的api权限
• 验证MR状态：已关闭或合并的MR可能限制评论功能
• 网络连接：确保与GitLab服务器连接正常

8. 评论数量显示不准确

• 刷新页面：重新进入MR详情页面，系统会自动重新计算评论数量
• 检查评论类型：系统评论不计入显示数量，只统计用户评论
• 重试加载：如果数量为0但实际有评论，点击评论tab会触发重新加载
• 清除缓存：使用强制刷新清除评论数据缓存

最佳实践

性能优化

• 合理设置分页：perPage=20, maxPages=2 适合大多数场景
• 使用搜索过滤：通过searchKeyword快速定位项目
• 定期清理缓存：使用强制刷新保持数据最新
• Tab切换优化：避免频繁切换Tab，减少不必要的API调用

安全建议

• Token管理：定期更新GitLab Token，设置合理过期时间
• 权限最小化：只授予必要的API权限
• 环境隔离：生产和测试环境使用不同的Token
• 敏感信息保护：避免在评论中包含敏感信息

协作建议

• 规范MR标题：使用清晰的MR标题，便于团队理解
• 及时添加评论：在审核过程中提供具体的反馈意见
• 合理配置@成员：选择相关的团队成员进行@提及
• 权限分级管理：根据团队角色合理分配GitLab项目权限

🤝 支持

如果遇到问题或有功能建议，请通过以下方式联系：

• 提交Issue到项目仓库
• 内部反馈渠道
• 查看详细技术文档：GitLab-Tool-技术文档.md

📄 许可证

本项目采用MIT许可证，仅供内部使用。

享受高效的GitLab工作流程！ 🚀🦊

💡 提示：首次使用建议先阅读FEATURE_GUIDE.md了解详细功能说明