Plastic SCM - GitServer ガイド


GitServer とは?

すべての Plastic SCM サーバーは、Git プロトコルを使用してリポジトリを操作できるようになりました(git と http がサポートされています)。

つまり、すべての Git クライアントで、Plastic SCM サーバーに対するプッシュ/プルを直接実行できるということです。

Git エコシステム内のすべてのツールは、ネイティブの Git 機能を使用して Plastic SCM に直接接続できるようになりました。これからは、Plastic で作業しているチームで、Git 用に開発されたすべての DevOps、CI、およびプロジェクト管理統合を活用することができます。

GitServer は、GitSync のサーバー型の機能単位です(Plastic SCM クライアントから git サーバーに対してプッシュ/プルを実行できるようにします)。これにより、Git の相互運用ループが完結します。


対象ユーザー

GitServer は幅広いシナリオで使用できますが、主な目的は、任意の Git ソフトウェアを Plastic に接続するための「ユニバーサルコネクター」として機能することです。

Git と互換性がある git クライアントは GitServer に変更をプッシュ/プルできるので、さまざまなシナリオでの活用が可能です。

  1. Git 互換ソフトウェアを Plastic SCM に接続する - 開発者は GitServer を使用して、FishEye、CodeCollaborator、ReviewBoard、TeamCity などのさまざまなソフトウェアを、Git 統合を使用した Plastic SCM に接続することができます。
  2. Plastic SCM を中央の Git サーバーとして使用する - 開発者は、GitServer 対応の Plastic SCM サーバーに対して、Git からプッシュ/プルを実行できます。
  3. 異種環境を使うチーム用の中央リポジトリとして使用する - Git と Plastic SCM を使用して、複数のチームで共同作業ができるようになりました。Plastic SCM への移行を段階的に進めていて、一部のチームがまだ Git を使用している場合や、バージョン管理オプションとして Plastic と Git のどちらかを各チームが選べるような戦略をとっている場合でも、Plastic を中央のランデブーポイントとして使用することにより、チーム間での共同作業が可能になります。

GitServer の設定


GitServer のクイックスタート

GitServer を Plastic SCM サーバーで有効にする方法は簡単です。

  1. 空の gitserver.conf ファイルを、サーバーのバイナリディレクトリ(plasticd.exe が置かれている場所)に作成します
  2. 次に、Plastic SCM サーバーを再起動します。git プロトコルのデフォルトポート(9418)でのリッスンが開始されます。

これで、Git から Plastic SCM に対するプル/プッシュを実行できるようになりました。

git push --all git://localhost/default

このコマンドを実行すると、Git リポジトリが default という Plastic リポジトリにプッシュされます。

重要:Plastic SCM クライアントのインストールも必要です。

gitserver.conf ファイルの詳細

gitserver.conf は GitServer の設定を制御するファイルで、次の形式になっています。各行はオプションです。

# port configuration
tcp.port=9418
http.port=80

# mapping storage - the mappings between git and plastic objects
# the default path is automatically generated by the server
storage.baseDirectory=e:\gitserver\mappings

# mapping interval - how often GitServer looks for new changes
# on the Plastic side to make them available to git
# By default, it is 5 minutes (300 seconds)
mapping.interval=300

# repositories to be exported. By default, all repositories 
# will be available on GitServer unless a list is specified here
export.repo=code
export.repo=quake
export.repo=robotcode

Windows での http ポートの設定

Windows での HTTP に対するセキュリティ制限のため、GitServer が特定の HTTP ポートを使用できるように特別な操作を行う必要があります。これは管理者権限アカウントで実行されないプロセスのみに影響します。つまり、Plastic SCM を Windows サービスとして実行することで、http を有効化するための特別な操作が必要なくなります。

Plastic SCM サーバーが管理者以外のモードで(デフォルト Windows サービスとしてではなく)実行している場合は、そのプロセスを実行している特定のユーザーに権限を付与するだけです。これは、次のコマンドを使用して行うことができます。

> netsh http add urlacl url=http://+:80/ user=DOMAIN\user

http 認証の設定

GitServer は、HTTP Basic 認証を使用して Git クライアントを保護することができます。

つまり、この認証が有効な場合、Git クライアントは、GitServer に接続するときにユーザー名とパスワードの入力を求めます。

HTTP 認証を設定するために必要となるのは、次のエントリを gitserver.conf ファイルに入力することだけです。

# http authentication
http.basicauth=true

もちろん、GitServer が HTTP プロトコルでリッスンするように設定する必要があります。

# http authentication
http.port=8080
http.basicauth=true
重要:ユーザーを認証するには、Plastic SCM サーバーを LDAP、AD または UP セキュリティモードで設定する必要があります。こうすることで、Git クライアントが、サーバーでサポートされる有効なユーザー/パスワードを入力できます。
注:セキュリティはリポジトリレベルのみでチェックされます。つまり、サーバーによってチェックされるのは、Git で認証されたユーザーが、指定のリポジトリ(Git url)を表示する Plastic の権限を持っているかどうかのみです。

GitServer の動作の仕組み

Plastic SCM サーバーは、Git クライアントによって透過的にアクセスされる Git サーバーのように振る舞うことができます。

変更は、次のようにさまざまなソースから GitServer に入ってくる可能性があります。

  • Git から git push 操作を使用して。Git コマンドが完了すると、変更は Plastic SCM と Git クライアントに即座に反映されます。
  • Plastic から check-in 操作または replica を使用して。これらの変更は Git クライアントに即座には反映されません。バックグラウンドスレッドは、Git に「エクスポートされた」リポジトリに Plastic で加えられた新たな変更があるかどうかを、mapping.interval 秒ごとにチェックします。変更が見つかった場合はマッピングの計算を開始し、計算が終わるとその新たに加えられた変更が Git で見えるようになります。

部分的なレプリカの制限事項

Plastic SCM では部分的なレプリカがサポートされていますが、この機能は Git にマッピングできません。これは純粋な Plastic 環境では非常に便利ですが、Git と Plastic が混在するシナリオでは問題となる可能性があります。


部分的なレプリカは Git には表示されない

次のシナリオについて考えてみましょう。John は最初に main をメインリポジトリ(GitServer を使用して Git に同期されたリポジトリ)にプッシュしますが、main へのマージがあるブランチ main/task001 はプッシュしません。

部分的なレプリカは Git には表示されない

GitServer コードが新規変更セット(この例では番号 10)のインデックス作成を開始して、それらを Git で利用できるようにしても、Git では変更セット 10 しか表示されません。新規変更セットは Git コミットとして利用可能になり、Git クライアントによってプルされる可能性があります。

後で Johnmain/task001central にプッシュすることを思い出したとしても、新規ブランチ task001 が Git で表示可能になることはありません。変更セット 10 はすでにエクスポートされており、task001 の再計算によって 10 の「sha」が変更されるため、すでに 10 をプルしたリモート git リポジトリとの同期が崩れるからです。

この制限事項を理解することは重要です。git マッピングは、Git に同期される Plastic リポジトリ内に正しいブランチがある場合にしか計算されないということを理解しておいてください。


リンクされていないブランチは Git には表示されない

次のシナリオについて見てみましょう。中央のリポジトリが、部分的なレプリカを使用して task002 を受け取っています。task002 の親はメインリポジトリでは利用できないので、Git へのマッピングが計算されると、このブランチは無視されます。

リンクされていないブランチは Git には表示されない

後で task001 がプッシュされたとしても、task001 が中央のリポジトリにプッシュされる前にマッピングが計算されたのであれば、task002 はその後も Git リポジトリでは表示されません。

Git では、すでにリモートでプッシュされたリポジトリに対して「リベース」や「履歴の再書き込み」を実行しないようにすることが強く推奨されています。これと同じことが、ここで説明しているシナリオにも当てはまります。新しい履歴が確認されると、Git 側でそれが再書き込みされ、リモートの Git リポジトリが壊れます。


無視される変更からのマージも無視される

今度は前の例から少し変えて、完全に複製された、リンクされていないブランチのマージについて考えてみましょう。

無視される変更からのマージも無視される

この場合、task002 はリンクされていないブランチなので、Git に認識させることはできません。これは、新しい変更セット 10 も Git に認識されないことを意味します。履歴を破壊する可能性があるためです。ブランチ task002 の親が複製されると、GitServer は履歴全体をリンクできるようになり、変更セット 10 が Git クライアントに認識されます。


親がマップされていない場合でもブランチのマッピングを強制する方法

一部の変更セットが条件に合わない場合でも、Git で 1 つのブランチを利用可能にすることを GitServer に強制できます。

前のシナリオでは、task002 が完全にはリンクされておらず、Git に一切マップされない場合でも、変更セット 10 を「マップ」するよう GitServer に強制することが可能です。

次のように、gitserver.conf に対して add branch.toForceMap エントリを実行するだけです。

# branches which changesets are made visible
# although they have unlinked merge sources
branch.toForceMap=/main

利用できない Xlink では含まれているブランチが無視される

未解決の Xlink がある変更セットも、GitServer によって無視されます。そのため、Git クライアントでは表示できません。

次のシナリオについて考えてみましょう。ブランチ main@root には、main@xlink への Xlink が含まれています。root にある変更セット 15 では、Xlink によって変更セット 4 がポイントされていますが、この変更セットはまだレプリケートされていません。

利用できない Xlink では含まれているブランチが無視される

つまり、変更セット 15 は無視され、xlink 先の変更セットがレプリケートされるまでは、Git から表示することはできません。


GitServer で見つからない Xlink を無視する方法

一部のコンテンツが見つからない場合であったとしても Git との同期が発生するように、見つけることができない Xlink をスキップするように GitServer を設定することができます。

次のように、gitserver.confunresolvedxlink.skip=true を追加するだけです。

# skip the xlink entries that cannot be resolved
unresolvedxlink.skip=true

Plastic SCM へのサブモジュールのプッシュ

Git サブモジュールは Plastic SCM Xlink に変換されます。Xlink は、開発者の作業を楽にするために進化したサブモジュールのようなものとも言えます。

一部の git 変更/リポジトリを GitServer にプッシュする際、その GitServer が解決方法を知らない git リポジトリをポイントしているサブモジュールが存在する場合には、操作が失敗する可能性があります。

>git push --all git://localhost/default Counting objects: 143, done. Writing objects: 100% (143/143), 106.43 KiB | 0 bytes/s, done. Total 143 (delta 0), reused 143 (delta 0) error: invalid ref status from remote: The specified repository couldn't be found: mduem. To git://localhost/default ! [remote failure] master -> master (remote failed to report status) error: failed to push some refs to 'git://localhost/default'

このケースでは、GitServer が有効な Plastic SCM リポジトリを見つけられない、mduem というリポジトリをポイントしているサブモジュールが存在します。

この問題を解決するには、mduem という名前のリポジトリが Plastic で作成される必要があります。そうすると、サブモジュールリポジトリが Gitserver にプッシュされます。

>cm repository create mduem >git clone https://github.com/user/mduem.git Cloning into 'mduem'... remote: Counting objects: 461, done. Receiving objects: 95% (438/461) Receiving objects: 100% (461/461), 68.40 KiB | 0 bytes/s, done. Resolving deltas: 100% (172/172), done. Checking connectivity... done. >git push --all git://localhost/mduem Writing objects: 100% (453/453), 731.45 KiB | 0 bytes/s, done. Total 453 (delta 0), reused 453 (delta 0) To git://localhost/mduem * [new branch] master -> master >git push --all git://localhost/default Counting objects: 118, done. Writing objects: 100% (118/118), 83.75 KiB | 0 bytes/s, done. Total 118 (delta 0), reused 118 (delta 0) To git://localhost/default 46232e0..41c12e1 master -> master

このケースでは、Git サブモジュール定義は次のようになります。

[submodule "mduem"]
        path = mduem
        url = git://github.com/user/mduem

Plastic SCM Xlink に対する Git サブモジュールのマッピングのカスタマイズ

Git サブモジュールと Plastic Xlink の間のマッピングをカスタマイズする必要があるとします。

次のエントリを gitserver.conf ファイルに追加することで、これを行うことができます(Git サブモジュールごとに必要な数だけ追加できます)。

repository.mapping=git://github.com/user/mduem -> mduem-xlinked@localhost:8084 writable:true relativeserver:false

これにより、リポジトリ mduem が Plastic 側で mduem-xlinked に変換されます。


Git サブモジュールのスキップ

特定の Git サブモジュールをスキップして、それらが Plastic SCM リポジトリにマップされないようにすることができます。これを行うには、gitserver.conf を次のように編集します。

# when a submoule points to one of the following
# git urls, it will be ignored.
ignore.submoduleUrl= git://github.com/user/mduem

ignore.submoduleUrl エントリは、必要な数だけ追加できます。


要件

Plastic SCM サーバーで GitServer を正常に有効化するには、有効な Enterprise Edition ライセンスが必要です。

Personal Edition と Community Edition では、GitServer はサポートされていません。

GitServer は、サポートされているすべての Plastic SCM サーバープラットフォーム(Linux、Windows、およびMacOS X)上で動作します。


現在の制限事項

ファストフォワード、リベース、および Git コミットの削除は避ける

GitServer にプッシュされる git リポジトリに対して、ファストフォワード、リベースおよび削除のコミットを回避します。

リベースまたは削除のコミットを回避することは、以前から、通常の git サーバーにプッシュする際の git 間の制限事項になっていました。

ファストフォワードの制限が存在するのは、Plastic SCM と Git の内部の違いのためです。Git では、単一のコミットを複数のブランチヘッドが指すことができるため、単一コミットが複数のブランチに存在する可能性があります。

Plastic SCM では、すべての変更セットが 1 つのブランチに結び付けられ、同時に複数のブランチ上に存在することはできません。このため、Plastic SCM と同期される予定の git リポジトリではファストフォワードマージを回避することをお勧めします。


GitServer によって操作されるリポジトリに対してはセキュリティを強制しない

GitServer では、エクスポートされたリポジトリに対するセキュリティチェックは実行されません。

Git クライアントでは、リポジトリコンテンツ全体をダウンロードするか、変更をリポジトリにプッシュすることができます。

gitserver.confexport.repo エントリを使用して、GitServer で表示できるリポジトリを制限することができるということを覚えておいてください。


Git リポジトリについては差分化を無効にする

GitServer は差分化された Git パッケージをサポートしません。つまり、パッケージは差分化されていない形式で送信される必要があります。

これは 2 つのシステム間でメタデータとデータの変換をスピードアップするためのパフォーマンス上の制約です。

Git 側で差分化を無効にするには、Git リポジトリで次のコマンドを実行します。

git config --global pack.window 0

GitServer がプッシュ中に差分化されたパックを受け取ると、次のエラーメッセージが表示されます。

git deltas are not supported. Please, set the 'pack.window 0' config variable or run an 'git repack -a -f -d' command

当メッセージ中において、Git リポジトリを「再パック」して差分化を無効にする方法についてのわかりやすい手順が記載されています。

git repack -a -f -d

シャロークローンはサポートされない

GitServer では、シャロークローンはサポートされていません。Git クライアントのバージョンによっては、次のエラーメッセージが表示されます。

> git clone git://localhost/default --depth=1 Cloning into 's'... fatal: Server does not support shallow clients

Git クライアントとの互換性

バージョン1.7.2 以降の git クライアントには互換性の問題はありません。それでも、入手可能な最新の git クライアントソフトウェアを使用することを強くお勧めします。


git push では進捗状況が表示されない

オブジェクトが Plastic SCM にインポートされている間、git push は一切進行しません。このプロセスはプッシュのサイズによって数秒、数分、数時間かかる場合があります。


注釈付きタグ

注釈付きタグは Plastic SCM に正常にインポートされますが、GitServer から Git に再度クローニングされると、軽量タグとしてエクスポートされます。


ブランチの名前と階層

複数のレベルがあるブランチ名は、Plastic SCM と Git で異なる場合があります。

たとえば、Plastic SCM のブランチ /main/Fix-5.0/scm003 は Git では main-Fix-5.0-scm003 に変換されます。


サポートされている Git プロトコル

現在、GitServer には git:// と http:// の両方のプロトコルを通じてアクセスできます。

SSH のサポートは今後追加される予定です。


ストレージの制限事項

現時点では、GitServer によってエクスポートされたリポジトリのファイルコンテンツは重複します。つまり、これらのコンテンツは Plastic SCM 形式でデータベース内に格納され、GitServer ストレージフォルダー内にも格納されます。


GitServer のマッピングフォルダーの再作成

GitServer マッピングフォルダーを再作成する必要が生じた場合においては、新しい Git SHA が以前のものと一致することかどうかについては保証をしておりません。

次に示すのは、以前のものと一致しない新規の Git SHA が作成されているアクションの例です。

  • 変更セットのコメントを編集した場合。
  • すでにマップされているいずれかの変更セットに影響を与えるレプリカ(複製)を実行した場合(たとえば、新しいマージリンクを追加するなど)。

以上の理由から、Git マッピングが再作成された後には、必ず新しい Git リポジトリを作成し、それを Plastic からクローンするようにしてください。

以前の Git リポジトリを再利用した場合、コミットの重複が発生する可能性があります(最終的には、Plastic へのプッシュバック時に変更セットも重複することになります)。


最終更新

2019 年 3 月 22 日
  • 非推奨となったリポジトリ管理コマンド(cm mkrep など)に関する説明を、新しい代替機能の説明に置き換えました。
  • 2018 年 11 月 23 日
  • Plastic SCM クライアントのインストールが必要であることを忘れないように注記を追加しました。
  • 2018 年 11 月 8 日
  • HTTP Basic 認証を使用して Git クライアントを保護できるようになりました。
  • 2018 年 11 月 2 日
  • GitServer マッピングフォルダーの再作成に関する新しい制限事項を追加しました。
  • 2016 年 4 月 19 日
  • Git から Plastic にプル/プッシュできるようになりました。
  • 2016 年 3 月 30 日
  • 公開日。