Flutter Git操作插件 git2dart 的使用指南

git2dart 是一个用于在 Dart/Flutter 应用中使用 libgit2 的插件。它提供了丰富的 API 来管理 Git 仓库，包括读写对象（提交、标签、树和 blob）、遍历树、访问暂存区、管理配置等。

开始使用

安装

1. 在 pubspec.yaml 文件中添加依赖：

   dependencies:
     git2dart: ^<version>
   

2. 导入包：

   import 'package:git2dart/git2dart.dart';
   

3. 验证安装是否成功（应返回包含 libgit2 版本的字符串）：

   print(Libgit2.version);
   

   注意：如果你是在 Dart 应用程序中使用该插件，则需要运行以下命令来确保库正确加载。Flutter 应用会在构建时自动捆绑 libgit2 库。

示例 Demo

以下是一个完整的示例，演示了如何使用 git2dart 进行基本的 Git 操作，如初始化仓库、添加文件、提交更改、查看历史记录等。

import 'dart:io';

import 'package:git2dart/git2dart.dart';
import 'package:path/path.dart' as path;

void main() {
  // 准备一个空目录作为仓库
  final tmpDir = Directory.systemTemp.createTempSync('example_repo');

  // 初始化仓库
  final repo = initRepo(tmpDir.path);

  // 设置用户名和邮箱
  setupNameAndEmail(repo);

  // 添加未跟踪的文件到暂存区
  const fileName = 'file.txt';
  final filePath = path.join(repo.workdir, fileName);
  File(filePath).createSync();
  stageUntracked(repo: repo, filePath: fileName);

  // 提交更改
  commitChanges(repo, fileName);

  // 查看提交历史
  viewHistory(repo);

  // 清理
  tmpDir.deleteSync(recursive: true);
}

/// 初始化仓库
Repository initRepo(String path) {
  final repo = Repository.init(path: path);
  stdout.writeln('Initialized empty Git repository in ${repo.path}');
  return repo;
}

/// 设置用户名和邮箱
void setupNameAndEmail(Repository repo) {
  final config = repo.config;
  config['user.name'] = 'User Name';
  config['user.email'] = 'user@email.com';
  stdout.writeln('\nSetup user name and email:');
  stdout.writeln('user.name=${config['user.name'].value}');
  stdout.writeln('user.email=${config['user.email'].value}');
}

/// 将未跟踪的文件添加到暂存区
void stageUntracked({required Repository repo, required String filePath}) {
  final index = repo.index;
  index.add(filePath);
  index.write();
  stdout.writeln('\nStaged previously untracked file $filePath');
}

/// 提交更改
void commitChanges(Repository repo, String fileName) {
  final signature = repo.defaultSignature;
  const commitMessage = 'initial commit\n';

  repo.index.write();

  final oid = Commit.create(
    repo: repo,
    updateRef: 'refs/heads/master',
    author: signature,
    committer: signature,
    message: commitMessage,
    tree: Tree.lookup(repo: repo, oid: repo.index.writeTree()),
    parents: [],
  );

  stdout.writeln(
    '\n[${repo.head.shorthand} (root-commit) ${oid.sha.substring(0, 7)}] '
    '$commitMessage',
  );
}

/// 查看提交历史
void viewHistory(Repository repo) {
  final commits = repo.log(oid: repo.head.target);

  for (final commit in commits) {
    stdout.writeln('\ncommit ${commit.oid.sha}');
    stdout.writeln('Author: ${commit.author.name} <${commit.author.email}>');
    stdout.writeln(
      'Date:   ${DateTime.fromMillisecondsSinceEpoch(commit.time * 1000)} '
      '${commit.timeOffset}',
    );
    stdout.writeln('\n\t${commit.message}');
  }
}

更多功能

git2dart 提供了许多其他功能，下面是一些常见的 Git 操作示例：

创建新分支

void createBranch(Repository repo, String branchName) {
  Branch.create(repo: repo, name: branchName, target: repo.head.target);
  stdout.writeln('Created new branch $branchName');
}

查看所有分支

void listBranches(Repository repo) {
  final branches = repo.branches;
  for (final branch in branches) {
    stdout.writeln(branch.name);
  }
}

合并分支

void mergeBranches(Repository repo, String branchName) {
  final theirHead = Branch.lookup(repo: repo, name: branchName).target;
  Merge.commit(repo: repo, commit: AnnotatedCommit.lookup(repo: repo, oid: theirHead));
  stdout.writeln('Merged branch $branchName into HEAD');
}

删除分支

void deleteBranch(Repository repo, String branchName) {
  Branch.delete(repo: repo, name: branchName);
  stdout.writeln('Deleted branch $branchName');
}

添加远程仓库

void addRemote(Repository repo, String remoteName, String url) {
  Remote.create(repo: repo, name: remoteName, url: url);
  stdout.writeln('Added remote $remoteName with URL $url');
}

查看远程仓库 URL

void viewRemoteUrls(Repository repo) {
  for (final remoteName in repo.remotes) {
    final remote = Remote.lookup(repo: repo, name: remoteName);
    stdout.writeln('${remote.name}: ${remote.url}');
  }
}

推送更改到远程仓库

void pushChanges(Repository repo, String remoteName, String refspec) {
  final remote = Remote.lookup(repo: repo, name: remoteName);
  remote.push(refspecs: [refspec]);
  stdout.writeln('Pushed changes to remote $remoteName');
}