チャプター ▾ 第2版

A2.3 付録B: アプリケーションにGitを埋め込む - JGit

JGit

Javaプログラム内からGitを使いたい場合、JGitと呼ばれるフル機能のGitライブラリがあります。JGitはJavaでネイティブに書かれた比較的にフル機能のGit実装であり、Javaコミュニティで広く使われています。JGitプロジェクトはEclipseの傘下にあり、その本拠地はhttps://www.eclipse.org/jgit/にあります。

セットアップ

JGitとプロジェクトを接続し、コードを書き始める方法はいくつかあります。おそらく最も簡単なのはMavenを使うことです。統合は、pom.xmlファイルの<dependencies>タグに以下のスニペットを追加することで実現されます。

<dependency>
    <groupId>org.eclipse.jgit</groupId>
    <artifactId>org.eclipse.jgit</artifactId>
    <version>3.5.0.201409260305-r</version>
</dependency>

このドキュメントを読んでいる頃には、versionは進んでいる可能性が高いです。最新のリポジトリ情報はhttps://mvnrepository.com/artifact/org.eclipse.jgit/org.eclipse.jgitで確認してください。このステップが完了すると、Mavenは必要なJGitライブラリを自動的に取得して使用します。

バイナリ依存関係を自分で管理したい場合は、事前にビルドされたJGitバイナリがhttps://www.eclipse.org/jgit/downloadから入手できます。次のようなコマンドを実行してプロジェクトにビルドすることができます。

javac -cp .:org.eclipse.jgit-3.5.0.201409260305-r.jar App.java
java -cp .:org.eclipse.jgit-3.5.0.201409260305-r.jar App

配管 (Plumbing)

JGitには、配管（Plumbing）と磁器（Porcelain）の2つの基本的なAPIレベルがあります。これらの用語はGit自体に由来しており、JGitもほぼ同じ種類の領域に分かれています。磁器APIは、一般的なユーザーレベルのアクション（通常のユーザーがGitコマンドラインツールを使うようなもの）のための使いやすいフロントエンドであり、配管APIは、低レベルのリポジトリオブジェクトと直接対話するためのものです。

ほとんどのJGitセッションの開始点はRepositoryクラスであり、最初にインスタンスを作成する必要があります。ファイルシステムベースのリポジトリ（はい、JGitは他のストレージモデルも許可しています）の場合、これはFileRepositoryBuilderを使って実現されます。

// Create a new repository
Repository newlyCreatedRepo = FileRepositoryBuilder.create(
    new File("/tmp/new_repo/.git"));
newlyCreatedRepo.create();

// Open an existing repository
Repository existingRepo = new FileRepositoryBuilder()
    .setGitDir(new File("my_repo/.git"))
    .build();

ビルダーは、プログラムが正確な場所を知っているかどうかに関わらず、Gitリポジトリを見つけるために必要なすべてのものを提供する流暢なAPIを持っています。環境変数を使用したり(.readEnvironment())、作業ディレクトリ内の場所から検索を開始したり(.setWorkTree(…).findGitDir())、あるいは上記のように既知の.gitディレクトリを開いたりすることができます。

Repositoryインスタンスがあれば、さまざまな操作を行うことができます。いくつか例を挙げましょう。

// Get a reference
Ref master = repo.getRef("master");

// Get the object the reference points to
ObjectId masterTip = master.getObjectId();

// Rev-parse
ObjectId obj = repo.resolve("HEAD^{tree}");

// Load raw object contents
ObjectLoader loader = repo.open(masterTip);
loader.copyTo(System.out);

// Create a branch
RefUpdate createBranch1 = repo.updateRef("refs/heads/branch1");
createBranch1.setNewObjectId(masterTip);
createBranch1.update();

// Delete a branch
RefUpdate deleteBranch1 = repo.updateRef("refs/heads/branch1");
deleteBranch1.setForceUpdate(true);
deleteBranch1.delete();

// Config
Config cfg = repo.getConfig();
String name = cfg.getString("user", null, "name");

ここではたくさんのことが起こっているので、一つずつ見ていきましょう。

最初の行は、masterリファレンスへのポインタを取得します。JGitは、refs/heads/masterにある実際のmasterリファレンスを自動的に取得し、そのリファレンスに関する情報を取得できるオブジェクトを返します。名前 (.getName()) を取得したり、ダイレクトリファレンスのターゲットオブジェクト (.getObjectId()) やシンボリックリファレンスが指すリファレンス (.getTarget()) を取得したりできます。Refオブジェクトはタグのリファレンスやオブジェクトを表すためにも使用されるため、タグが「剥がされている（peeled）」かどうか、つまりタグオブジェクトの（潜在的に長い）文字列の最終ターゲットを指しているかどうかを尋ねることができます。

2行目はmasterリファレンスのターゲットを取得し、ObjectIdインスタンスとして返されます。ObjectIdはオブジェクトのSHA-1ハッシュを表し、Gitのオブジェクトデータベースに存在する場合としない場合があります。3行目も同様ですが、JGitがrev-parse構文をどのように処理するかを示しています（これについてはブランチリファレンスを参照してください）。Gitが理解する任意のオブジェクト指定子を渡すことができ、JGitはそのオブジェクトの有効なObjectIdまたはnullを返します。

次の2行は、オブジェクトの生のコンテンツをロードする方法を示しています。この例では、ObjectLoader.copyTo()を呼び出してオブジェクトのコンテンツを直接標準出力にストリーミングしていますが、ObjectLoaderにはオブジェクトのタイプとサイズを読み取るメソッドや、バイト配列として返すメソッドもあります。大きなオブジェクト（.isLarge()がtrueを返す場合）の場合、.openStream()を呼び出して、生のオブジェクトデータをすべて一度にメモリに読み込むことなく読み取れるInputStreamのようなオブジェクトを取得できます。

次の数行は、新しいブランチを作成するために必要なものを示しています。RefUpdateインスタンスを作成し、いくつかのパラメータを設定し、.update()を呼び出して変更をトリガーします。これに続いて、同じブランチを削除するコードがあります。これには.setForceUpdate(true)が必要であることに注意してください。そうしないと、.delete()呼び出しはREJECTEDを返し、何も起こりません。

最後の例は、Git設定ファイルからuser.nameの値を取得する方法を示しています。このConfigインスタンスは、以前に開いたリポジトリをローカル設定に使用しますが、グローバルおよびシステム設定ファイルを自動的に検出し、そこからも値を読み取ります。

これはフル機能の配管APIのほんの一部にすぎません。他にも多くのメソッドやクラスが利用可能です。また、JGitがエラーを処理する方法、つまり例外を使用する方法はここでは示されていません。JGit APIは、標準的なJava例外（IOExceptionなど）をスローすることがありますが、JGit固有の例外タイプも多数提供されています（NoRemoteRepositoryException、CorruptObjectException、NoMergeBaseExceptionなど）。

磁器 (Porcelain)

配管APIは非常に完全ですが、インデックスにファイルを追加したり、新しいコミットを作成したりするような一般的な目標を達成するためにそれらを連結するのは煩雑になる可能性があります。JGitは、これを助けるためのより高レベルなAPIセットを提供しており、これらのAPIへのエントリーポイントはGitクラスです。

Repository repo;
// construct repo...
Git git = new Git(repo);

Gitクラスには、かなり複雑な動作を構築するために使用できる、優れた高レベルのビルダースタイルのメソッドセットがあります。git ls-remoteのような例を見てみましょう。

CredentialsProvider cp = new UsernamePasswordCredentialsProvider("username", "p4ssw0rd");
Collection<Ref> remoteRefs = git.lsRemote()
    .setCredentialsProvider(cp)
    .setRemote("origin")
    .setTags(true)
    .setHeads(false)
    .call();
for (Ref ref : remoteRefs) {
    System.out.println(ref.getName() + " -> " + ref.getObjectId().name());
}

これはGitクラスの一般的なパターンです。メソッドはコマンドオブジェクトを返し、それによってパラメータを設定するためのメソッド呼び出しをチェーンさせることができ、これらは.call()を呼び出すと実行されます。このケースでは、originリモートにタグを要求していますが、ヘッドは要求していません。また、認証にCredentialsProviderオブジェクトを使用していることにも注目してください。

他にも多くのコマンドがGitクラスを通じて利用可能で、add、blame、commit、clean、push、rebase、revert、resetなどが含まれますが、これらに限定されません。

さらに読む

これはJGitの全機能のほんの一部です。興味があり、さらに詳しく知りたい場合は、情報やインスピレーションを探す場所を以下に示します。

scroll-to-top