Git Cola 鸿蒙 PC 版适配全记录：从 Qt 桌面工具到 ArkTS 原生应用

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

适配开源地址：ohos_git-cola

一、为什么选择适配 Git Cola

Git Cola 是一款成熟的 Git 图形客户端。原项目以 Python 和 Qt 为主要技术栈，界面克制、操作路径短，尤其适合希望保留 Git 命令语义、又不愿频繁在终端中切换的开发者。与功能庞杂的项目管理平台相比，它更像一把专注于仓库日常维护的工具：查看工作区、暂存文件、提交变更、切换分支以及处理远端同步。

鸿蒙 PC 逐步进入开发和生产场景之后，系统需要的不只是编辑器和终端，也需要一批符合桌面操作习惯的基础开发工具。选择 Git Cola 作为适配对象，一方面是因为它的功能边界清晰，便于验证鸿蒙 PC 上完整的 Git 工作流；另一方面，原项目已经形成稳定的交互模型，可以把适配重点放在系统能力、文件权限和命令执行链路上，而不是重新发明一套 Git 客户端。

这次适配并没有把 Python/Qt 运行时整体搬进应用，而是在保留 Git Cola 核心使用习惯的基础上，采用 ArkTS 重建界面与状态管理，以 C++ N-API 承接 Git 命令执行，再通过 HNP 随应用分发 Git 和 OpenSSH。这样的实现更贴近鸿蒙 PC 的应用模型，也为后续权限治理、窗口适配和系统能力接入留下了空间。

二、适配目标与技术路线

适配工作的目标不是机械复刻每一个菜单，而是先打通开发者最常用、也最能检验底层能力的一条闭环：获取仓库、识别仓库状态、查看差异、暂存或恢复文件、创建提交、管理分支，并能够与远端仓库交互。

工程中的鸿蒙实现位于 ohos/ 目录，和原有 Python/Qt 源码保持相对独立。整体可以分为四层：

层次	主要职责	实现方式
界面层	首页、仓库详情、差异、历史、分支和远端操作	ArkUI / ArkTS
业务层	仓库状态、操作编排、任务调度、页面状态刷新	ArkTS、TaskPool
桥接层	目录切换、命令调用、输出回传、路径处理	C++ N-API
工具层	Git 操作、SSH 认证和远端通信	Git HNP、OpenSSH HNP

这种分层有一个直接好处：页面不需要理解 Git 的进程细节，N-API 层也不负责决定界面状态。耗时命令由任务池执行，完成后只把结构化结果交回页面，避免扫描大型仓库或访问远端时阻塞主线程。

三、先把"仓库入口"做得可靠

应用启动后会检查 Git 的全局用户名和邮箱配置。配置完整时进入仓库首页；缺少必要信息时，则先引导用户完成基础配置。首页提供打开本地仓库、创建仓库和克隆仓库三个入口，并保存最近使用的仓库，减少重复选择目录的操作。

下面的画面来自 HAD-W32 鸿蒙 PC 真机，应用以最大化窗口运行，分辨率为 3120×2080。首页保留了桌面工具应有的留白，三个入口承担明确职责，没有把低频操作堆到首屏。

鸿蒙应用通过文件选择器获得的通常是 URI，而 Git 需要真实可访问的目录路径。这里不能只做一次字符串转换：应用还需要申请目录读写权限、持久化授权结果，并在下次启动时重新激活授权。实现中会保存 URI 与仓库路径之间的映射；用户从"最近仓库"重新进入时，先恢复权限，再检查 .git 目录，避免出现页面记录仍在、实际仓库却无法访问的情况。

克隆同样沿用系统目录选择器。用户选择目标目录并填写远端地址后，后台任务执行克隆，成功后把新仓库加入最近列表并直接进入详情页。为了验证这条链路，真机从 AtomGit 实际克隆了本项目；页面中的远端地址、当前分支和工作区状态均由仓库实时读取，不是演示数据。

四、把命令行结果转化为稳定的桌面交互

Git 客户端看似只是调用命令，真正困难的是把连续变化的文本结果转成用户可以信任的界面状态。仓库详情页需要同时处理已暂存、未暂存、未跟踪和冲突文件；一次暂存操作完成后，文件可能从一个分组移动到另一个分组，差异内容和提交按钮状态也必须同步刷新。

适配中将仓库扫描、暂存、恢复和提交等操作封装成独立任务。C++ 层负责进入目标仓库、执行命令并解析输出，ArkTS 层负责更新页面。命令执行结束后统一触发状态重扫，减少多个局部状态互相覆盖的问题。对于尚未产生首个提交的新仓库，也不能假设 HEAD 一定存在，需要为初始分支和空历史提供单独处理。

提交历史采用按仓库实时读取的方式，展示提交摘要、作者、时间和提交标识。真机克隆完成后读取到了 AtomGit 仓库中的实际提交记录，点击条目可以继续查看对应变更。

五、分支、差异与日常开发闭环

分支功能是 Git GUI 的高频入口，也是命令执行和页面状态联动最明显的部分。创建分支时，应用先校验名称和基准分支，再执行创建与切换；操作成功后刷新仓库信息，使标题栏、分支菜单和后续提交都落在新的分支上。测试中以 main 为基准创建了 feature/harmony-ui，真机提示成功后立即显示新分支为当前分支。

工作区差异采用文件列表与内容面板并排的布局。开发者可以先从已暂存、未暂存等分组中定位文件，再查看具体增删行；状态颜色只承担辅助作用，文件分组和文本标记仍能给出明确语义。下图是在真机仓库中修改说明文件并新增测试文件后的实际结果：左侧显示两个未暂存文件，右侧展示所选文件的真实差异。

在这条基础闭环之外，当前工程还实现了提交修订与 Signed-off-by、分支切换和重置、远端新增与编辑、Fetch、上游分支设置、Pull、Push、Merge、Cherry-pick，以及冲突状态下的继续或中止操作。远端交互由随包部署的 Git 和 OpenSSH 完成；涉及凭据、主机指纹和网络错误时，页面会把底层结果转换为可操作的提示，而不是只显示一段未经处理的终端输出。

六、适配过程中遇到的几个关键问题

1. 原桌面技术栈无法直接套用

原项目依赖 Python、Qt 及其桌面运行环境。即使能够把解释器和依赖一并打包，窗口、文件访问、进程调用和应用签名仍然需要大量额外兼容工作，最终包体和维护成本也会显著增加。因此本次选择重建 ArkUI 界面，只保留经过验证的交互逻辑和 Git 工作流。代价是部分界面需要重新实现，但运行边界更清晰，系统权限也能按鸿蒙应用规范管理。

2. Git 不是简单的单次命令调用

应用需要在目标仓库目录中运行命令，还要设置用户配置、处理 Git 路径、为 Git 与 OpenSSH 准备运行环境，并将标准输出和错误信息可靠地传回 ArkTS。长耗时操作采用异步执行和线程安全回调，轻量查询提供同步接口，避免所有操作都走同一种调用方式。应用首次启动时还会完成必要目录的权限调整，并设置路径显示相关配置，保证包含中文的文件名能够正常展示。

3. 路径、引号与输出解析容易形成隐蔽故障

仓库目录、分支名和提交信息都可能包含空格或非 ASCII 字符。若直接拼接 Shell 命令，轻则执行失败，重则可能把参数误解为另一条命令。桥接层对参数进行统一引用和校验，对 Git 输出中的转义路径进行解码；远端名称等有明确语法的字段还会单独检查。状态解析也不能依赖界面语言，需要使用稳定的机器可读格式建立文件分组。

4. 文件授权需要跨启动周期保持

通过系统选择器打开目录，只代表当前流程拿到了访问入口，并不等于以后都可以直接访问。适配中将目录授权、路径映射和最近仓库记录作为同一套数据维护。重新打开仓库时，如果持久授权失效或目录已被移动，应用会回到选择或错误提示流程，而不是继续使用失效路径。

5. 合并和拣选不是"一次成功或失败"

Merge 与 Cherry-pick 可能进入中间状态。应用通过仓库中的状态文件识别当前操作，显示冲突文件，并提供继续和中止入口。这样即使用户关闭弹窗或重新进入仓库，也能从仓库事实恢复页面状态，不会因为内存中的临时标志丢失而把冲突误报成普通修改。

七、构建与真机运行

工程目标 SDK 为 HarmonyOS 5.0.5 (17)，设备类型为 2in1。使用 DevEco Studio 打开 ohos/ 目录后，需要先按本机环境配置 SDK 与签名。Git 和 OpenSSH 以 HNP 依赖声明在 Entry 模块中，构建时应确认对应架构的包已经准备完整。

命令行构建可使用工程自带的 Hvigor Wrapper：

bash 复制代码

cd ohos
./hvigorw assembleHap --mode module \
  -p product=default \
  -p module=entry@default

生成签名 HAP 后，可以通过 HDC 安装并启动：

bash 复制代码

hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start \
  -a EntryAbility \
  -b com.develop.opensource.ohos_git_cola \
  -m entry

如果换用新的开发机或证书，需要重新配置签名信息，不应直接复用其他环境中的证书路径。首次运行建议依次验证全局用户名和邮箱、目录授权、本地仓库打开以及远端克隆，再继续测试提交和同步操作，这样更容易定位问题发生在权限层、工具层还是网络层。

八、当前能力边界

目前版本已经覆盖单仓库日常开发的主要操作，但它仍然是一款处于演进阶段的鸿蒙 PC 客户端。当前仅面向 2in1 设备；提交历史以列表为主，尚未提供独立的 DAG 图；也没有实现多仓库同时管理、代码评审、项目管理和编辑器集成。SSH 私钥权限、代理网络以及复杂认证环境仍建议在目标设备上单独验证。

明确这些边界并不影响基础工作流的完整性。相反，它让后续迭代可以围绕真实使用频率展开：先提升大型仓库扫描与差异渲染性能，再补充历史图、凭据管理和多仓库能力，而不是一次性堆叠大量缺乏验证的入口。

九、总结

Git Cola 的鸿蒙 PC 适配，核心并不是把一套桌面界面换一种语言重写，而是建立一条符合鸿蒙应用模型的 Git 执行链：系统选择器负责目录入口和持久授权，ArkTS 负责桌面交互与任务编排，C++ N-API 负责可靠执行与结果解析，HNP 则保证 Git 和 OpenSSH 能随应用交付。

从真机验证结果看，应用已经能够完成 AtomGit 仓库克隆、仓库状态读取、提交历史查看、分支创建和差异展示等核心流程。这条闭环打通之后，提交、远端同步与冲突处理便有了稳定的基础，也证明传统开源开发工具可以在鸿蒙 PC 上以更原生、更可维护的方式延续下来。