Rust Git仓库操作库binstalk-git-repo-api使用指南

binstalk-git-repo-api 是一个用于高效管理Git仓库的Rust库，提供了简洁的API接口和工具集，方便开发者在Rust项目中执行各种Git操作。

主要特性

• 提供Git仓库的克隆、拉取、推送等基本操作
• 支持分支管理和标签操作
• 可执行Git命令并获取输出
• 提供便捷的仓库状态检查功能
• 支持多种认证方式

安装方法

在Cargo.toml中添加依赖：

[dependencies]
binstalk-git-repo-api = "0.1"

基础用法示例

1. 克隆仓库

use binstalk_git_repo_api::GitRepo;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let repo = GitRepo::clone("https://github.com/example/repo.git", "./local_path")?;
    println!("仓库克隆成功: {:?}", repo.path());
    Ok(())
}

2. 打开本地仓库

use binstalk_git_repo_api::GitRepo;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let repo = GitRepo::open("./existing_repo")?;
    println!("仓库已打开: {:?}", repo.path());
    Ok(())
}

3. 拉取最新更改

use binstalk_git_repo_api::GitRepo;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let repo = GitRepo::open("./my_repo")?;
    repo.pull()?;
    println!("仓库更新完成");
    Ok(())
}

4. 创建并切换分支

use binstalk_git_repo_api::GitRepo;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let repo = GitRepo::open("./my_repo")?;
    repo.create_branch("new-feature")?;
    repo.checkout("new-feature")?;
    println!("已创建并切换到分支: new-feature");
    Ok(())
}

高级功能示例

1. 使用SSH密钥认证

use binstalk_git_repo_api::{GitRepo, SshKey};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = SshKey::new("path/to/private_key")?;
    let repo = GitRepo::clone_with_ssh(
        "git@github.com:example/repo.git",
        "./local_path",
        &key,
    )?;
    println!("使用SSH密钥克隆成功");
    Ok(())
}

2. 获取仓库状态

use binstalk_git_repo_api::GitRepo;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let repo = GitRepo::open("./my_repo")?;
    let status = repo.status()?;
    
    println!("当前分支: {}", status.branch);
    println!("是否有未提交更改: {}", status.has_changes);
    println!("是否有未推送提交: {}", status.ahead_of_remote);
    
    Ok(())
}

3. 执行自定义Git命令

use binstalk_git_repo_api::GitRepo;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let repo = GitRepo::open("./my_repo")?;
    let output = repo.execute_git_command(&["log", "--oneline", "-n", "5"])?;
    
    println!("最近5次提交:");
    println!("{}", output);
    
    Ok(())
}

错误处理

该库提供了详细的错误类型，建议使用Rust的?操作符进行错误传播，或使用match进行详细处理：

use binstalk_git_repo_api::{GitRepo, GitError};

fn main() {
    match GitRepo::open("./nonexistent") {
        Ok(repo) => println!("仓库打开成功"),
        Err(GitError::NotFound) => eprintln!("仓库不存在"),
        Err(e) => eprintln!("其他错误: {}", e),
    }
}

性能提示

1. 对于频繁操作，建议保持GitRepo实例而不是重复打开
2. 批量操作使用execute_git_command直接执行多个Git命令
3. 对于大型仓库，考虑使用浅克隆(--depth参数)

binstalk-git-repo-api 提供了简洁的API接口，使得在Rust项目中集成Git操作变得非常简单。根据实际需求选择合适的方法，可以高效地管理Git仓库。

完整示例代码

下面是一个整合了多个功能的完整示例：

use binstalk_git_repo_api::{GitRepo, SshKey, GitError};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 示例1：克隆仓库
    println!("=== 示例1：克隆仓库 ===");
    let repo = GitRepo::clone("https://github.com/example/repo.git", "./example_repo")?;
    println!("仓库克隆成功: {:?}", repo.path());
    
    // 示例2：打开本地仓库
    println!("\n=== 示例2：打开本地仓库 ===");
    let repo = GitRepo::open("./example_repo")?;
    println!("仓库已打开: {:?}", repo.path());
    
    // 示例3：拉取最新更改
    println!("\n=== 示例3：拉取最新更改 ===");
    repo.pull()?;
    println!("仓库更新完成");
    
    // 示例4：创建并切换分支
    println!("\n=== 示例4：创建并切换分支 ===");
    repo.create_branch("new-feature")?;
    repo.checkout("new-feature")?;
    println!("已创建并切换到分支: new-feature");
    
    // 高级示例1：使用SSH密钥认证
    println!("\n=== 高级示例1：使用SSH密钥认证 ===");
    let key = SshKey::new("path/to/private_key")?;
    let ssh_repo = GitRepo::clone_with_ssh(
        "git@github.com:example/repo.git",
        "./ssh_repo",
        &key,
    )?;
    println!("使用SSH密钥克隆成功");
    
    // 高级示例2：获取仓库状态
    println!("\n=== 高级示例2：获取仓库状态 ===");
    let status = repo.status()?;
    println!("当前分支: {}", status.branch);
    println!("是否有未提交更改: {}", status.has_changes);
    println!("是否有未推送提交: {}", status.ahead_of_remote);
    
    // 高级示例3：执行自定义Git命令
    println!("\n=== 高级示例3：执行自定义Git命令 ===");
    let output = repo.execute_git_command(&["log", "--oneline", "-n", "3"])?;
    println!("最近3次提交:");
    println!("{}", output);
    
    // 错误处理示例
    println!("\n=== 错误处理示例 ===");
    match GitRepo::open("./nonexistent") {
        Ok(_) => println!("仓库打开成功"),
        Err(GitError::NotFound) => eprintln!("错误：仓库不存在"),
        Err(e) => eprintln!("其他错误: {}", e),
    }
    
    Ok(())
}

这个完整示例演示了如何：

1. 克隆一个Git仓库
2. 打开已存在的本地仓库
3. 拉取最新更改
4. 创建并切换分支
5. 使用SSH密钥进行认证
6. 检查仓库状态
7. 执行自定义Git命令
8. 处理可能出现的错误

您可以根据实际需求选择使用其中的部分功能或全部功能。