使用方法

requirements

• Python3
  • 3.10.12のみ動作を確認
• pygit2
  • https://www.pygit2.org/install.html

使用手順

1. OverlayGitリポジトリのクローン

$ git clone https://github.com/kusumotolab/OverlayGit.git

なお，mainブランチはベースレイヤ実装，nestブランチはネスト実装になっている．

2. 対象リポジトリのクローン

$ git clone https://github.com/apache/commons-compress.git

3. ogit用ディレクトリ作成＆configテンプレートコピー

$ mkdir ogit
$ cp OverlayGit/ogit-config-template.json ogit/ogit-config.json

4. configファイル編集
   configファイルにgitのオリジナルリポジトリへのパスを記載する．
   ogit用ディレクトリからオリジナルリポジトリまでの相対パスか，絶対パスを記載する．

// example
{
    "repository-path": "../commons-compress",
    "ogit-mount-directory-name": "ogit-mounted", 
    "upper-layers-directory-name": "upps", 
    "ofs-working-directory-name": "work", 
    "commit-graph-file-name": "commit-graph.txt", 
    "ogit-working-directory-name": "imd", 
    "intermediate-merge-directory-prefix": "imd",
    "git-layer-name": "gitlayer",
    "dummy-directory-name": "dummy-directory",
    "hash-length": 7
}

configファイルでは，他にogitが作成するファイル・ディレクトリの名前指定が可能．
また，"hash-length"でogit内部で使用するgitハッシュの長さを指定できる．
リポジトリによっては7文字ではハッシュが衝突するため，この値を変更する必要がある．詳しくは下記「ツールの懸念点」の「ハッシュの衝突」を参照．

5. ogit用ディレクトリへ移動，前処理コマンド実行

$ cd ogit
$ python ../OverlayGit/ogit.py mount

ogit用ディレクトリ直下に大量のディレクトリが生成される．

6. チェックアウトコマンド実行

$ python ../OverlayGit/ogit.py checkout bea0994a1d52886cca0b7ad54dec121dcba9b7b6

ogit-mountedというディレクトリにチェックアウト実行結果が反映される．
ogitのチェックアウトコマンドはgitコミットのハッシュ値のみを入力として受け付ける．
ハッシュ値はconfigファイルで指定した値以上の長さであれば良い．
例えばogit-config.jsonの"hash-length"を7にした場合，次でもチェックアウトが可能．

$ python ../OverlayGit/ogit.py checkout bea0994

なお，内部でOverlayFSのマウントを実行するため，rootパスワードを要求される．

7. OverlayFSアンマウント アンマウントコマンドは未実装のため，作業が終了した後は手動でumountコマンドを実行する必要がある．

sudo umount ogit-mounted
sudo umount imd/imd*

エラー・懸念点

マージで採用されなかった変更に対応できていない

マージコミットレイヤには，統合するブランチ双方で変更があったファイルだけを置いている．
これは，「マージコミットではブランチでの変更をすべて採用する」という前提に作ってしまっている．
両方のブランチで変更があって片方だけを採用する，という場合は問題ないが，片方のブランチだけで変更があったが採用しない，という場合に対応できない．
例えば，file1-3のファイルが存在するリポジトリにおいて，一方のブランチB1でfile1とfile2，他方のブランチB2でfile2とfile3を変更したとする．
マージコミットではB1のfile1とB2のfile2を採用し，B2のfile3は採用しなかったとする．
このとき，マージコミットレイヤにはfile2だけが設置される． しかし，マージコミットに対応するリビジョンにチェックアウトすると．file3はB1のものを採用したいところ，現在の実装ではB2のfile3が見えてしまう．
この問題に対応する解決策として，マージコミットレイヤに設置する内容を変える方法がある．
どちらか片方のブランチで変更されていればマージコミットレイヤに設置する，とすればこの問題は解決できる．
ただ，この場合マージコミットレイヤにはそれまでのレイヤの内容と重複する部分が多くなるため，冗長性が高くなってしまうという課題がある． なお，ベースレイヤ実装ではほとんど発生しない問題である．

ハッシュの衝突

Gitは全てのオブジェクトにハッシュ値を付与している．
ハッシュ値は40文字と長いため，GitコマンドやAPIでは7文字以上の短縮ハッシュ値を使用できる．
しかし，規模が大きいリポジトリにおいては，7文字のハッシュ値ではオブジェクトを一意に決定できない場合がある．
この場合，少なくとも一意にオブジェクトを決定できる長さのハッシュ値を指定する必要がある．
ogitではconfigファイルの"hash-length"で使用するハッシュ値を指定できる．
前処理やチェックアウトコマンド実行時にエラーが出た場合，"hash-length"の値を大きくして再度前処理・チェックアウトを行うことを推奨する．

inodeの枯渇

深いファイル構造を持つリポジトリや，巨大リポジトリに対してogitの前処理を行うと，膨大な数のディレクトリ・ファイルが生成される．
複数のリポジトリに対してogitの前処理を行うと，inodeが枯渇して前処理が行えない可能性がある．

チェックアウトコマンドが中止した場合

チェックアウトコマンドが途中で終了した場合，中途半端にOverlayFSがマウントされていることがある．
マウントされているディレクトリを全てアンマウントしてから再度チェックアウトコマンドを実行することを推奨する．
なお，mount | grep "overlay"で現在マウント中のディレクトリリストを見ることができる．