Git Credential Manager 开发指南跨平台构建、调试与 Trace2 追踪实践【免费下载链接】git-credential-managerSecure, cross-platform Git credential storage with authentication to GitHub, Azure Repos, and other popular Git hosting services.项目地址: https://gitcode.com/GitHub_Trending/gi/git-credential-managerGit Credential ManagerGCM是安全、跨平台的 Git 凭据存储与认证工具支持 GitHub、Azure Repos、GitLab、Bitbucket 等主流 Git 托管服务。本文以仓库中的 docs/development.md 为骨架完整讲解从源码构建 GCM、在 IDE 与命令行中调试、利用GCM_TRACE与 Git Trace2 API 收集诊断信息以及生成代码覆盖率报告与文档 linting 的完整开发流程。读完本文你将具备在 macOS、Windows、Linux 三个平台上独立构建、调试和性能分析 GCM 的实战能力。环境准备克隆仓库与安装 .NET SDK开发 GCM 的第一步是从版本库克隆源码然后准备 .NET 开发环境git clone https://github.com/git-ecosystem/git-credential-manager克隆完成后还需要安装 .NET SDK。仓库通过 global.json 锁定了 SDK 版本{ sdk: { rollForward: latestMajor, version: 8.0.100 } }即要求 .NET SDK 8.0.100 及以上版本rollForward: latestMajor允许向前滚动到更新的主版本这与文档中安装最新版 .NET SDK的建议一致。SDK 就绪后即可打开解决方案进行构建。解决方案结构速览GCM 的主解决方案为 Git-Credential-Manager.sln其中定义了按平台与功能划分的多个项目可先用 IDE 打开也可在命令行用dotnet build构建入口程序Git-Credential-Manager包含 Program.cs 入口负责初始化 Dispatcher、注册各 Host ProviderAzureRepos、Bitbucket、GitHub、GitLab 及低优先级的 Generic并运行命令核心库 CoreCore.csproj承载认证、命令、配置、Trace2 追踪、各平台互操作等核心实现托管服务适配层GitHub、GitLab、Microsoft.AzureRepos、Atlassian.Bitbucket测试项目Core.Tests、GitHub.Tests、GitLab.Tests、Microsoft.AzureRepos.Tests、Atlassian.Bitbucket.Tests 以及共享的 TestInfrastructure打包与安装器Installer.Mac、Installer.Windows、Packaging.Linux。三平台构建解决方案配置与产物位置GCM 为每个目标平台提供了独立的解决方案配置IDE 中打开解决方案后需要手动选择对应配置命令行构建时通过-c传入。macOS在 IDE 中构建时务必选择MacDebug或MacRelease配置。命令行构建dotnet build -c MacDebug构建完成后安装器.pkg文件位于out/osx/Installer.Mac/pkg/Debug扁平flat二进制文件位于out/osx/Installer.Mac/pkg/Debug/payload。Windows在 IDE 中选择WindowsDebug或WindowsRelease配置。命令行构建dotnet build -c WindowsDebug构建完成后安装器.exe文件位于out\windows\Installer.Windows\bin\Debug\net472扁平二进制文件位于out\windows\Payload.Windows\bin\Debug\net472\win-x86。LinuxLinux 下可用的两个配置为LinuxDebug与LinuxRelease。命令行构建dotnet build -c LinuxDebug如需针对特定 CPU 架构构建可通过-r参数指定运行时标识符RID支持linux-x64、linux-arm64、linux-armdotnet build -c LinuxDebug -r linux-arm64构建完成后Debian 包.deb位于out/linux/Packaging.Linux/deb/Debug扁平二进制文件位于out/linux/Packaging.Linux/payload/Debug。Linux 的打包细节目录布局、依赖整理等可以进一步查看 src/linux/Packaging.Linux/layout.sh 与 pack.sh。IDE 调试模拟 Git 通过标准输入调用 GCM在 IDE 中调试时需要将启动项目设置为Git-Credential-Manager并在程序参数中指定 GCM 的命令之一get、store或erase。这三个命令对应 Commands 目录下的 GetCommand、StoreCommand、EraseCommand是 Git 凭据助手的核心回调。为了模拟真实场景中 Git 与 GCM 的交互启动程序后还需要在标准输入stdin中按 Git 凭据协议提供如下信息LF表示换行符GCM 同时支持 LF 与 CRLFprotocolhttpLF hostHOSTNAMELF LF LF其中HOSTNAME替换为受支持的域名例如github.com。末尾的两个空行用于结束输入区块。根据测试场景的不同还可以追加以下可选字段usernameUSERNAMELF passwordPASSWORDLF这份输入格式与 Git 的凭据 I/O 协议一致。从 Program.cs 的入口实现可以看到进程启动后即初始化 Trace2context.Trace2.Initialize(startTime)随后写入start/version事件并依次注册各 Host Provider最后执行app.RunAsync(args)并写入exit事件——这一生命周期正是下面各类调试手段所围绕的核心。附加到已运行进程GCM_DEBUG当需要调试 GCM 与 Git 之间的真实交互、且希望由 Git 来拉起 GCM 进程时可以借助GCM_DEBUG环境变量让进程在启动后等待调试器附加export GCM_DEBUG1将GCM_DEBUG设为1或true后GCM 进程会在启动时等待调试器附加附加成功后才继续执行。该行为的底层实现在 ApplicationBase.csRunAsync首先检查Context.Settings.IsDebuggingEnabled若为真则向标准错误输出Waiting for debugger to be attached...并进入WaitForDebuggerAttached()循环轮询Debugger.IsAttached附加成功后调用Debugger.Break()中断同时若调试器已附加还会额外向 Trace 系统注册DebugTraceWriter监听器。对应的开关定义可见 Constants.cs 中的GCM_DEBUG与 Settings.cs 中的IsDebuggingEnabled支持环境变量或credential.debug配置。收集追踪输出GCM_TRACEGCM 内置两套追踪系统一套是 GCM 专属的追踪基于GCM_TRACE另一套则实现了 Git Trace2 API 的部分特性。针对发布版或已安装的 GCM可通过GCM_TRACE环境变量启用 GCM 自带追踪设为1将追踪信息输出到标准错误stderr设为绝对文件路径将追踪信息写入指定文件。例如$ GCM_TRACE1 git-credential-manager version 18:47:56.526712 ...er/Application.cs:69 trace: [RunInternalAsync] Git Credential Manager version 2.0.124-betae1ebbe1517 (macOS, .NET 5.0) version Git Credential Manager version 2.0.124-betae1ebbe1517 (macOS, .NET 5.0)上例输出中的版本号取自文档示例当前仓库 VERSION 记录的版本为 2.9.1.0。从源码看ApplicationBase.cs 中通过GetTracingEnabled读取GCM_TRACE也支持credential.trace配置见 Settings.cs 与 Constants.cs值为真值truthy时追踪到 stderr值为根路径时以追加模式FileMode.Append打开文件写入其他值则输出unknown value for GCM_TRACE ...警告。值得留意的是GCM 还提供了GCM_TRACE_SECRETS启用后追踪可能包含敏感信息启用时会打印显式警告见 ApplicationBase.cs与GCM_TRACE_MSAUTH用于 MSAL 认证库日志两个相关开关详见 Constants.cs。Git 的 Trace2 API三种格式目标与七类事件GCM 实现了 Git Trace2 API 的部分特性可向 stderr 或文件输出调试、性能与遥测信息并支持多种输出格式。支持的格式目标Format TargetNormal Format Target与GCM_TRACE类似输出人类可读的日志最适合调试。可通过环境变量或 Git 配置启用export GIT_TRACE21或git config --global trace2.normalTarget ~/log.normalPerformance Format Target基于列的格式面向开发与测试阶段的性能分析。启用方式export GIT_TRACE2_PERF1或git config --global trace2.perfTarget ~/log.perfEvent Format Target基于 JSON 的格式面向大规模数据采集与高级分析。启用方式export GIT_TRACE2_EVENT1或git config --global trace2.eventTarget ~/log.event这三类目标的配置键trace2.normalTarget、trace2.perfTarget、trace2.eventTarget及环境变量GIT_TRACE2、GIT_TRACE2_PERF、GIT_TRACE2_EVENT都能在 Constants.cs 与 GitConfiguration.Trace2 中找到对应定义。GCM 在启动时会解析这些设置Settings.GetTrace2Settings()见 Settings.cs逐项读取三个格式目标组装成Trace2Settings随后 Trace2.cs 的InitializeWriters根据目标值分派写入方式值形如af_unix:*POSIX或\\.\pipe\*///./pipe/Windows的命名管道/套接字使用Trace2CollectorWriter连接对管道名的解析逻辑TryGetPipeName有专门的单元测试覆盖见 Trace2Tests.cs值为真值的使用Trace2StreamWriter写入 stderr值为绝对路径的使用Trace2FileWriter写入文件失败时向 stderr 打印警告。支持的事件类型Trace2 系统目前支持的事件及其含义高级别描述如下version当前可执行文件GCM 或某个 helper exe的版本start当前可执行文件Main()方法收到的完整 argvexit当前可执行文件的退出码child_start描述即将派生的子进程child_exit描述子进程退出时的状态region_enter进入某个区域例如对一段感兴趣代码的计时时触发region_leave离开区域时触发。从 Trace2.cs 源码看事件枚举Trace2Event除上述七类外还包含Error事件第 5 项用于记录错误消息Trace2ProcessClassNone / UIHelper / Git / Other则用于对 GCM 派生的子进程进行分类。进程在 Program.cs 中创建会话 IDProcessManager.CreateSid()、写入 start/version 事件、执行完命令后写入 exit 事件并停止追踪每个事件消息都携带 sid、时间戳、线程名、源文件与行号、相对启动的耗时以及进程深度等信息。区域计时通过Region类见 Trace2.cs实现构造时记录region_enter释放时自动计算耗时并写入region_leave。代码覆盖率度量若需要生成代码覆盖率指标可以从命令行执行dotnet test --collect:XPlat Code Coverage --settings./.code-coverage/coverlet.settings.xml或在 VSCode 的 Terminal/Run Task 中运行预置任务test with coverageHTML 格式的报告可通过 ReportGenerator 生成该工具会在构建过程中安装。命令行方式POSIX shelldotnet ~/.nuget/packages/reportgenerator/*/*/net10.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverageWindows PowerShell 下路径写法略有不同dotnet {$env:USERPROFILE}/.nuget/packages/reportgenerator/*/*/net10.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverage同样也可使用 VSCode 预置任务report coverage - nix或report coverage - win仓库各测试项目如 Core.Tests、GitHub.Tests 等与测试基建 TestInfrastructure 共同构成了覆盖率度量的对象--collect:XPlat Code Coverage会为每个测试程序集产出 Cobertura 格式的coverage.cobertura.xml再交由 ReportGenerator 汇总为 HTML 报告。文档 Lintingmarkdownlint 与 lychee仓库的文档采用两套工具进行质量把关markdownlint负责 Markdown 语法与风格检查可作为 NPM 的 CLI 工具安装也可在 VSCode 中作为扩展使用其配置存放于仓库根目录的.markdownlint.jsonclychee负责校验文档中的链接有效性可按平台选择多种安装方式部分 URL 会按照忽略清单排除在检查之外。延伸阅读项目整体介绍与安装方式见 README.md更多开发相关细节可参考 docs/development.md 同目录下的其他文档索引 docs/README.md常见问题排查见 docs/faq.md环境变量与配置说明见 docs/environment.md 与 docs/configuration.md。【免费下载链接】git-credential-managerSecure, cross-platform Git credential storage with authentication to GitHub, Azure Repos, and other popular Git hosting services.项目地址: https://gitcode.com/GitHub_Trending/gi/git-credential-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Git Credential Manager 开发指南：跨平台构建、调试与 Trace2 追踪实践
Git Credential Manager 开发指南跨平台构建、调试与 Trace2 追踪实践【免费下载链接】git-credential-managerSecure, cross-platform Git credential storage with authentication to GitHub, Azure Repos, and other popular Git hosting services.项目地址: https://gitcode.com/GitHub_Trending/gi/git-credential-managerGit Credential ManagerGCM是安全、跨平台的 Git 凭据存储与认证工具支持 GitHub、Azure Repos、GitLab、Bitbucket 等主流 Git 托管服务。本文以仓库中的 docs/development.md 为骨架完整讲解从源码构建 GCM、在 IDE 与命令行中调试、利用GCM_TRACE与 Git Trace2 API 收集诊断信息以及生成代码覆盖率报告与文档 linting 的完整开发流程。读完本文你将具备在 macOS、Windows、Linux 三个平台上独立构建、调试和性能分析 GCM 的实战能力。环境准备克隆仓库与安装 .NET SDK开发 GCM 的第一步是从版本库克隆源码然后准备 .NET 开发环境git clone https://github.com/git-ecosystem/git-credential-manager克隆完成后还需要安装 .NET SDK。仓库通过 global.json 锁定了 SDK 版本{ sdk: { rollForward: latestMajor, version: 8.0.100 } }即要求 .NET SDK 8.0.100 及以上版本rollForward: latestMajor允许向前滚动到更新的主版本这与文档中安装最新版 .NET SDK的建议一致。SDK 就绪后即可打开解决方案进行构建。解决方案结构速览GCM 的主解决方案为 Git-Credential-Manager.sln其中定义了按平台与功能划分的多个项目可先用 IDE 打开也可在命令行用dotnet build构建入口程序Git-Credential-Manager包含 Program.cs 入口负责初始化 Dispatcher、注册各 Host ProviderAzureRepos、Bitbucket、GitHub、GitLab 及低优先级的 Generic并运行命令核心库 CoreCore.csproj承载认证、命令、配置、Trace2 追踪、各平台互操作等核心实现托管服务适配层GitHub、GitLab、Microsoft.AzureRepos、Atlassian.Bitbucket测试项目Core.Tests、GitHub.Tests、GitLab.Tests、Microsoft.AzureRepos.Tests、Atlassian.Bitbucket.Tests 以及共享的 TestInfrastructure打包与安装器Installer.Mac、Installer.Windows、Packaging.Linux。三平台构建解决方案配置与产物位置GCM 为每个目标平台提供了独立的解决方案配置IDE 中打开解决方案后需要手动选择对应配置命令行构建时通过-c传入。macOS在 IDE 中构建时务必选择MacDebug或MacRelease配置。命令行构建dotnet build -c MacDebug构建完成后安装器.pkg文件位于out/osx/Installer.Mac/pkg/Debug扁平flat二进制文件位于out/osx/Installer.Mac/pkg/Debug/payload。Windows在 IDE 中选择WindowsDebug或WindowsRelease配置。命令行构建dotnet build -c WindowsDebug构建完成后安装器.exe文件位于out\windows\Installer.Windows\bin\Debug\net472扁平二进制文件位于out\windows\Payload.Windows\bin\Debug\net472\win-x86。LinuxLinux 下可用的两个配置为LinuxDebug与LinuxRelease。命令行构建dotnet build -c LinuxDebug如需针对特定 CPU 架构构建可通过-r参数指定运行时标识符RID支持linux-x64、linux-arm64、linux-armdotnet build -c LinuxDebug -r linux-arm64构建完成后Debian 包.deb位于out/linux/Packaging.Linux/deb/Debug扁平二进制文件位于out/linux/Packaging.Linux/payload/Debug。Linux 的打包细节目录布局、依赖整理等可以进一步查看 src/linux/Packaging.Linux/layout.sh 与 pack.sh。IDE 调试模拟 Git 通过标准输入调用 GCM在 IDE 中调试时需要将启动项目设置为Git-Credential-Manager并在程序参数中指定 GCM 的命令之一get、store或erase。这三个命令对应 Commands 目录下的 GetCommand、StoreCommand、EraseCommand是 Git 凭据助手的核心回调。为了模拟真实场景中 Git 与 GCM 的交互启动程序后还需要在标准输入stdin中按 Git 凭据协议提供如下信息LF表示换行符GCM 同时支持 LF 与 CRLFprotocolhttpLF hostHOSTNAMELF LF LF其中HOSTNAME替换为受支持的域名例如github.com。末尾的两个空行用于结束输入区块。根据测试场景的不同还可以追加以下可选字段usernameUSERNAMELF passwordPASSWORDLF这份输入格式与 Git 的凭据 I/O 协议一致。从 Program.cs 的入口实现可以看到进程启动后即初始化 Trace2context.Trace2.Initialize(startTime)随后写入start/version事件并依次注册各 Host Provider最后执行app.RunAsync(args)并写入exit事件——这一生命周期正是下面各类调试手段所围绕的核心。附加到已运行进程GCM_DEBUG当需要调试 GCM 与 Git 之间的真实交互、且希望由 Git 来拉起 GCM 进程时可以借助GCM_DEBUG环境变量让进程在启动后等待调试器附加export GCM_DEBUG1将GCM_DEBUG设为1或true后GCM 进程会在启动时等待调试器附加附加成功后才继续执行。该行为的底层实现在 ApplicationBase.csRunAsync首先检查Context.Settings.IsDebuggingEnabled若为真则向标准错误输出Waiting for debugger to be attached...并进入WaitForDebuggerAttached()循环轮询Debugger.IsAttached附加成功后调用Debugger.Break()中断同时若调试器已附加还会额外向 Trace 系统注册DebugTraceWriter监听器。对应的开关定义可见 Constants.cs 中的GCM_DEBUG与 Settings.cs 中的IsDebuggingEnabled支持环境变量或credential.debug配置。收集追踪输出GCM_TRACEGCM 内置两套追踪系统一套是 GCM 专属的追踪基于GCM_TRACE另一套则实现了 Git Trace2 API 的部分特性。针对发布版或已安装的 GCM可通过GCM_TRACE环境变量启用 GCM 自带追踪设为1将追踪信息输出到标准错误stderr设为绝对文件路径将追踪信息写入指定文件。例如$ GCM_TRACE1 git-credential-manager version 18:47:56.526712 ...er/Application.cs:69 trace: [RunInternalAsync] Git Credential Manager version 2.0.124-betae1ebbe1517 (macOS, .NET 5.0) version Git Credential Manager version 2.0.124-betae1ebbe1517 (macOS, .NET 5.0)上例输出中的版本号取自文档示例当前仓库 VERSION 记录的版本为 2.9.1.0。从源码看ApplicationBase.cs 中通过GetTracingEnabled读取GCM_TRACE也支持credential.trace配置见 Settings.cs 与 Constants.cs值为真值truthy时追踪到 stderr值为根路径时以追加模式FileMode.Append打开文件写入其他值则输出unknown value for GCM_TRACE ...警告。值得留意的是GCM 还提供了GCM_TRACE_SECRETS启用后追踪可能包含敏感信息启用时会打印显式警告见 ApplicationBase.cs与GCM_TRACE_MSAUTH用于 MSAL 认证库日志两个相关开关详见 Constants.cs。Git 的 Trace2 API三种格式目标与七类事件GCM 实现了 Git Trace2 API 的部分特性可向 stderr 或文件输出调试、性能与遥测信息并支持多种输出格式。支持的格式目标Format TargetNormal Format Target与GCM_TRACE类似输出人类可读的日志最适合调试。可通过环境变量或 Git 配置启用export GIT_TRACE21或git config --global trace2.normalTarget ~/log.normalPerformance Format Target基于列的格式面向开发与测试阶段的性能分析。启用方式export GIT_TRACE2_PERF1或git config --global trace2.perfTarget ~/log.perfEvent Format Target基于 JSON 的格式面向大规模数据采集与高级分析。启用方式export GIT_TRACE2_EVENT1或git config --global trace2.eventTarget ~/log.event这三类目标的配置键trace2.normalTarget、trace2.perfTarget、trace2.eventTarget及环境变量GIT_TRACE2、GIT_TRACE2_PERF、GIT_TRACE2_EVENT都能在 Constants.cs 与 GitConfiguration.Trace2 中找到对应定义。GCM 在启动时会解析这些设置Settings.GetTrace2Settings()见 Settings.cs逐项读取三个格式目标组装成Trace2Settings随后 Trace2.cs 的InitializeWriters根据目标值分派写入方式值形如af_unix:*POSIX或\\.\pipe\*///./pipe/Windows的命名管道/套接字使用Trace2CollectorWriter连接对管道名的解析逻辑TryGetPipeName有专门的单元测试覆盖见 Trace2Tests.cs值为真值的使用Trace2StreamWriter写入 stderr值为绝对路径的使用Trace2FileWriter写入文件失败时向 stderr 打印警告。支持的事件类型Trace2 系统目前支持的事件及其含义高级别描述如下version当前可执行文件GCM 或某个 helper exe的版本start当前可执行文件Main()方法收到的完整 argvexit当前可执行文件的退出码child_start描述即将派生的子进程child_exit描述子进程退出时的状态region_enter进入某个区域例如对一段感兴趣代码的计时时触发region_leave离开区域时触发。从 Trace2.cs 源码看事件枚举Trace2Event除上述七类外还包含Error事件第 5 项用于记录错误消息Trace2ProcessClassNone / UIHelper / Git / Other则用于对 GCM 派生的子进程进行分类。进程在 Program.cs 中创建会话 IDProcessManager.CreateSid()、写入 start/version 事件、执行完命令后写入 exit 事件并停止追踪每个事件消息都携带 sid、时间戳、线程名、源文件与行号、相对启动的耗时以及进程深度等信息。区域计时通过Region类见 Trace2.cs实现构造时记录region_enter释放时自动计算耗时并写入region_leave。代码覆盖率度量若需要生成代码覆盖率指标可以从命令行执行dotnet test --collect:XPlat Code Coverage --settings./.code-coverage/coverlet.settings.xml或在 VSCode 的 Terminal/Run Task 中运行预置任务test with coverageHTML 格式的报告可通过 ReportGenerator 生成该工具会在构建过程中安装。命令行方式POSIX shelldotnet ~/.nuget/packages/reportgenerator/*/*/net10.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverageWindows PowerShell 下路径写法略有不同dotnet {$env:USERPROFILE}/.nuget/packages/reportgenerator/*/*/net10.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverage同样也可使用 VSCode 预置任务report coverage - nix或report coverage - win仓库各测试项目如 Core.Tests、GitHub.Tests 等与测试基建 TestInfrastructure 共同构成了覆盖率度量的对象--collect:XPlat Code Coverage会为每个测试程序集产出 Cobertura 格式的coverage.cobertura.xml再交由 ReportGenerator 汇总为 HTML 报告。文档 Lintingmarkdownlint 与 lychee仓库的文档采用两套工具进行质量把关markdownlint负责 Markdown 语法与风格检查可作为 NPM 的 CLI 工具安装也可在 VSCode 中作为扩展使用其配置存放于仓库根目录的.markdownlint.jsonclychee负责校验文档中的链接有效性可按平台选择多种安装方式部分 URL 会按照忽略清单排除在检查之外。延伸阅读项目整体介绍与安装方式见 README.md更多开发相关细节可参考 docs/development.md 同目录下的其他文档索引 docs/README.md常见问题排查见 docs/faq.md环境变量与配置说明见 docs/environment.md 与 docs/configuration.md。【免费下载链接】git-credential-managerSecure, cross-platform Git credential storage with authentication to GitHub, Azure Repos, and other popular Git hosting services.项目地址: https://gitcode.com/GitHub_Trending/gi/git-credential-manager创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考