GitSdk.Core 1.0.6

GitSdk.Core

GitSdk.Core 是一个基于系统 Git CLI 的 .NET 类库，提供轻量、可复用的 Git 执行内核与高层命令封装。

当前能力

底层执行内核

• 通过 GitCommandRequest 描述 Git 子命令、参数、工作目录和超时
• 通过 IGitCommandExecutor 异步执行命令，自动定位系统 Git
• 通过 GitCommandResult / GitCommandResult<TData> 统一返回退出码、标准输出、标准错误和耗时
• 通过 IGitResultParser<TData> 支持结构化解析

高层命令（IGitClient / GitClient）

基础设施

• GitExecutableLocator：定位系统 Git，支持自定义路径解析与可用性探测
• GitProcessRunner：进程生命周期管理，含超时控制与超时进程清理
• 异常体系：GitExecutableNotFoundException、GitCommandStartException、GitCommandTimeoutException

快速开始

前置条件

• 已安装 .NET 10 SDK
• 当前系统可直接调用 git

构建

dotnet build git-sdk-core.csproj

项目启用了 GeneratePackageOnBuild，构建时会同时生成 NuGet 包。

最小示例

底层 API

using GitSdk.Core.Models;
using GitSdk.Core.GitSdk.Core.Services;

var executor = new GitCommandExecutor();
var request = new GitCommandRequest(
    "status",
    new[] { "--short" },
    workingDirectory: "/path/to/repo");

var result = await executor.ExecuteAsync(request);

Console.WriteLine(result.Succeeded);   // true / false
Console.WriteLine(result.StandardOutput);
Console.WriteLine(result.Duration);     // 执行耗时

高层 API（推荐）

直接使用（零配置）

using GitSdk.Core.GitSdk.Core.Services;

var git = new GitClient();

// 初始化仓库
await git.InitAsync("/path/to/new-repo");

// 查看状态
var status = await git.StatusAsync("/path/to/repo");
Console.WriteLine(status.StandardOutput);

// 暂存并提交
await git.AddAsync("/path/to/repo", new[] { "." });
await git.CommitAsync("/path/to/repo", "feat: initial commit");

// 查看分支
await git.BranchAsync("/path/to/repo");

// 查看日志
await git.LogAsync("/path/to/repo", new[] { "--oneline", "-5" });

// 切换分支
await git.CheckoutAsync("/path/to/repo", "main");

// 推送（默认 300s 超时，支持 --force 等额外参数）
await git.PushAsync("/path/to/repo");
await git.PushAsync("/path/to/repo", remote: "origin", branch: "main");
await git.PushAsync("/path/to/repo", remote: "origin", branch: "main", extraArguments: new[] { "--force" });

依赖注入（ASP.NET Core / 泛型主机）

GitSdk.Core 不依赖任何 DI 容器包，但每个核心类都提供无参构造和接口注入构造，可由调用方自由注册：

// Program.cs / Startup — 调用方自行注册，无需库引入 DI 包
using GitSdk.Core.GitSdk.Core.Abstractions;
using GitSdk.Core.GitSdk.Core.Infrastructure;
using GitSdk.Core.GitSdk.Core.Services;

builder.Services.AddSingleton<GitProcessRunner>();
builder.Services.AddSingleton<GitExecutableLocator>();
builder.Services.AddSingleton<IGitCommandExecutor, GitCommandExecutor>();
builder.Services.AddSingleton<IGitClient, GitClient>();

// 消费者中直接注入接口
public class MyService
{
    private readonly IGitClient _git;

    public MyService(IGitClient git) => _git = git;

    public async Task DoWorkAsync()
    {
        await _git.StatusAsync("/path/to/repo");
    }
}

// 需要替换某一层实现（如测试 / mock）时，只需调整注册：
builder.Services.AddSingleton<IGitCommandExecutor, MockGitExecutor>();

当前状态与限制

• 强依赖系统已安装的 Git，不负责下载、分发或凭证交互
• 当前没有独立测试项目；dotnet test 可执行，但仓库里暂无测试用例
• 命名空间仍在整理中，部分实现类型目前位于 GitSdk.Core.GitSdk.Core.*
• 暂不提供流式输出、自动重试或完整 Git 命令封装

项目结构

GitSdk/
  Core/
    Abstractions/    # IGitClient, IGitCommandExecutor, IGitResultParser<T>
    Commands/        # Git 子命令封装 (Init, Add, Commit, Status, Branch, Log, Checkout, Push, Version)
    Exceptions/      # GitExecutableNotFoundException, GitCommandStartException, GitCommandTimeoutException
    Infrastructure/  # GitExecutableLocator, GitProcessRunner
    Models/          # GitCommandRequest, GitCommandResult, GitCommandResult<T>
    Services/        # GitClient, GitCommandExecutor
doc/                 # 补充性中文记录
docs/superpowers/    # 设计文档与实现计划

开发与贡献

常用命令：

dotnet build git-sdk-core.csproj
dotnet test
dotnet pack -c Release git-sdk-core.csproj

提交信息当前采用 Conventional Commits 风格，例如 feat:、docs:、chore:。如果你要扩展公共 API，建议同时更新 README.md、相关设计文档，并补上明确的验证步骤。