git bundleで、リポジトリを1つのファイルにまとめる方法

​​Git​コマンドライン

git bundle create <ファイル名> --all を実行すると、ブランチ、タグ、コミットの履歴をまとめて1つのファイルにできます。できたファイルは、ふつうのリモートリポジトリと同じように git clone や git pull の取得元として使えます。GitHub などのサーバーにつなげない環境(オフラインの環境)へ USB メモリーやファイル共有でリポジトリを持ち込むときや、履歴ごとバックアップを取っておきたいときに使える方法です。

補足

検証環境は Ubuntu 24.04、Git 2.43.0 です。作者の名前とメールアドレスには例示用の値(Neko <neko@example.com>)を設定し、コミットの日時は環境変数で決めています。bundle ファイルは、リポジトリの1つ上のフォルダーに作っています。コマンドと出力は、検証環境で実行したものをそのまま載せています。Windows と macOS での動作、SHA-256 のリポジトリ、--since や -10 のような日時や数での範囲の指定は試していません。

まとめる前のリポジトリ

neko-app というリポジトリを用意しました。main ブランチにコミットが2つあり、2つ目に v1.0 のタグを付けています。feature ブランチには、もう1つコミットがあります。作業フォルダーには、Git の管理に入れていない memo.txt を置きました。

console
$ git log --oneline --graph --all --decorate
* c4263b0 (feature) 肉球を追加
* ba27b17 (HEAD -> main, tag: v1.0) 鳴き声を追加
* 6b9961f 最初のコミット

$ git status --short
?? memo.txt

$ git branch
  feature
* main

git bundle create でファイルにまとめる

リポジトリのフォルダーで次のコマンドを実行します。--all は、refs/ の下にあるすべての参照(ブランチやタグなど)と HEAD を入れる指定です(git rev-list の –all の説明)。

console
$ git bundle create ../neko-app.bundle --all

何も表示されずに終わり、../neko-app.bundle ができました。大きさは 999 バイトで、file コマンドでは Git の bundle と判定されます。ファイルの先頭はテキストになっていて、入っているブランチやタグの名前と、それが指すコミットの ID が並んでいます。この後ろに、コミットやファイルの中身がまとめて入っています。

console
$ ls -l ../neko-app.bundle | awk "{print \$5, \$9}"
999 ../neko-app.bundle

$ file ../neko-app.bundle
../neko-app.bundle: Git bundle

$ head -n 5 ../neko-app.bundle | cut -c 1-80
# v2 git bundle
c4263b0f065590ad674d9df2dd9aad1fbb2906b9 refs/heads/feature
ba27b17fe6b7fd6c749a9e9004961e00333515db refs/heads/main
ba27b17fe6b7fd6c749a9e9004961e00333515db refs/tags/v1.0
ba27b17fe6b7fd6c749a9e9004961e00333515db HEAD

1行目の v2 は bundle の形式の版です。git bundle の公式リファレンスにある --version の説明によると、指定しなければ、リポジトリのハッシュの方式で使える、いちばん古い形式になります。

中身を確かめる verify と list-heads

git bundle verify で、ファイルが壊れていないかと、何が入っているかを確かめられます。

console
$ git bundle verify ../neko-app.bundle
../neko-app.bundle is okay
The bundle contains these 4 refs:
c4263b0f065590ad674d9df2dd9aad1fbb2906b9 refs/heads/feature
ba27b17fe6b7fd6c749a9e9004961e00333515db refs/heads/main
ba27b17fe6b7fd6c749a9e9004961e00333515db refs/tags/v1.0
ba27b17fe6b7fd6c749a9e9004961e00333515db HEAD
The bundle records a complete history.
The bundle uses this hash algorithm: sha1

is okay と、The bundle records a complete history.(最初のコミットからの履歴がすべて入っている)が出ました。ブランチとタグの一覧だけを見たいときは git bundle list-heads を使います。bundle はリモートリポジトリと同じように扱えるので、git ls-remote でも一覧が出ます。

console
$ git bundle list-heads ../neko-app.bundle
c4263b0f065590ad674d9df2dd9aad1fbb2906b9 refs/heads/feature
ba27b17fe6b7fd6c749a9e9004961e00333515db refs/heads/main
ba27b17fe6b7fd6c749a9e9004961e00333515db refs/tags/v1.0
ba27b17fe6b7fd6c749a9e9004961e00333515db HEAD

$ git ls-remote ../neko-app.bundle
ba27b17fe6b7fd6c749a9e9004961e00333515db	HEAD
ba27b17fe6b7fd6c749a9e9004961e00333515db	refs/tags/v1.0
ba27b17fe6b7fd6c749a9e9004961e00333515db	refs/heads/main
c4263b0f065590ad674d9df2dd9aad1fbb2906b9	refs/heads/feature

bundle ファイルから clone する

受け取った側では、bundle ファイルの名前を URL の代わりに書いて git clone します。ここでは、同じ検証環境の neko-app の1つ上のフォルダーに移り、別のフォルダーに clone しました。

console
$ cd ..

$ git clone neko-app.bundle neko-copy
Cloning into 'neko-copy'...

$ cd neko-copy

$ git log --oneline --graph --all --decorate
* c4263b0 (origin/feature) 肉球を追加
* ba27b17 (HEAD -> main, tag: v1.0, origin/main, origin/HEAD) 鳴き声を追加
* 6b9961f 最初のコミット

$ git branch -a
* main
  remotes/origin/HEAD -> origin/main
  remotes/origin/feature
  remotes/origin/main

$ git tag
v1.0

コミットの ID は元のリポジトリと同じで、feature ブランチと v1.0 のタグも届いています。元のブランチは、origin/feature のようなリモート追跡ブランチとして届いています。origin の URL は、bundle ファイルの場所になっていました(出力の検証環境のフォルダーは /path/to に置き換えています)。

console
$ git remote -v
origin	/path/to/neko-app.bundle (fetch)
origin	/path/to/neko-app.bundle (push)

作業フォルダーには、コミットしたファイルだけが出てきました。元のリポジトリにあった memo.txt は、コミットしていないので入りません。feature に切り替えると、そのブランチのファイル paw.txt も出てきます。

console
$ ls -A
.git
README.md
main.js

$ git switch feature && ls
Switched to a new branch 'feature'
branch 'feature' set up to track 'origin/feature'.
README.md
main.js
paw.txt

入れるブランチを選ぶ

--all の代わりにブランチの名前を書くと、そのブランチだけが入ります。main だけを入れた bundle では、feature のコミットは clone しても届きませんでした。ここからは neko-app の1つ上のフォルダーで、git -C neko-app を付けて実行しています。

console
$ cd ..

$ git -C neko-app bundle create ../main-only.bundle main

$ git bundle list-heads main-only.bundle
ba27b17fe6b7fd6c749a9e9004961e00333515db refs/heads/main

$ git clone -q main-only.bundle main-copy && git -C main-copy log --oneline --all
ba27b17 鳴き声を追加
6b9961f 最初のコミット

HEAD が入っていない bundle から clone すると、init.defaultBranch の設定と同じ名前のブランチが取り出されました。検証環境では main にしているので、上の main-only.bundle からは main が取り出されています。feature だけを入れた bundle では、main ブランチが入っていないため、作業フォルダーが空のままになりました(init.defaultBranch を変えたときの結果は、後の節で示します)。

console
$ git -C neko-app bundle create ../no-head.bundle feature

$ git clone no-head.bundle no-head-copy
Cloning into 'no-head-copy'...
warning: remote HEAD refers to nonexistent ref, unable to checkout

$ git -C no-head-copy status
On branch main

No commits yet

nothing to commit (create/copy files and use "git add" to track)

コミットの ID だけを渡すと、bundle は作られません。公式リファレンスの SPECIFYING REFERENCES の節にあるとおり、ブランチやタグの名前が必要です。

console
$ git -C neko-app bundle create ../commit-only.bundle $(git -C neko-app rev-parse HEAD)
fatal: Refusing to create empty bundle.

$ ls commit-only.bundle
ls: cannot access 'commit-only.bundle': No such file or directory

前回からの差分だけを bundle にする

2回目からは、相手がすでに持っているところより後のコミットだけを渡せます。neko-app に戻って main にコミットを2つ足し、v1.0..main(v1.0 の後から main まで)を bundle にしました。

console
$ cd neko-app

$ git log --oneline v1.0..main
9ff13f5 使い方を追加
04ebc0a 鳴き声を2回にする

$ git bundle create ../update.bundle v1.0..main

$ ls -l ../neko-app.bundle ../update.bundle | awk "{print \$5, \$9}"
999 ../neko-app.bundle
759 ../update.bundle

この bundle を verify すると、The bundle requires this ref: の後ろに v1.0 のコミット ba27b17 が出ます。取り込む側のリポジトリに、このコミットがすでにある必要があるという意味です。

console
$ git bundle verify ../update.bundle
../update.bundle is okay
The bundle contains this ref:
9ff13f5e6bc4b55c66fdece235be000f3f7c663f refs/heads/main
The bundle requires this ref:
ba27b17fe6b7fd6c749a9e9004961e00333515db 
The bundle uses this hash algorithm: sha1

そのため、差分だけの bundle からは clone できません。1つ上のフォルダーに空のリポジトリを作って verify したときも、この bundle から clone したときも、足りないコミットがあるというエラーになりました。

console
$ cd ..

$ git init -q empty && git -C empty bundle verify ../update.bundle
error: Repository lacks these prerequisite commits:
error: ba27b17fe6b7fd6c749a9e9004961e00333515db 

$ git clone update.bundle update-copy
Cloning into 'update-copy'...
error: Repository lacks these prerequisite commits:
error: ba27b17fe6b7fd6c749a9e9004961e00333515db 
fatal: remote transport reported error
ポイント

最初に渡す bundle は、--all やブランチの名前だけで作った、履歴をすべて含むものにします。v1.0..main のような範囲で作った bundle は、相手が範囲の始まりのコミットを持っているときにしか使えません。

受け取った側で差分を取り込む

さきほど clone した neko-copy は ba27b17 を持っているので、verify は is okay になりました。git pull に bundle ファイルとブランチの名前を渡すと、2つのコミットが取り込まれます。

console
$ cd neko-copy

$ git bundle verify ../update.bundle
../update.bundle is okay
The bundle contains this ref:
9ff13f5e6bc4b55c66fdece235be000f3f7c663f refs/heads/main
The bundle requires this ref:
ba27b17fe6b7fd6c749a9e9004961e00333515db 
The bundle uses this hash algorithm: sha1

$ git log --oneline -1
ba27b17 鳴き声を追加

$ git pull ../update.bundle main
From ../update.bundle
 * branch            main       -> FETCH_HEAD
Updating ba27b17..9ff13f5
Fast-forward
 README.md | 1 +
 main.js   | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

$ git log --oneline
9ff13f5 使い方を追加
04ebc0a 鳴き声を2回にする
ba27b17 鳴き声を追加
6b9961f 最初のコミット

$ cat main.js
console.log("にゃーにゃー");

origin の URL を新しい bundle ファイルに向けておけば、引数なしの git fetch でもリモート追跡ブランチが更新されます。

console
$ git remote set-url origin ../update.bundle

$ git fetch
From ../update.bundle
   ba27b17..9ff13f5  main       -> origin/main

$ git status -sb
## main...origin/main

公式リファレンスの EXAMPLES の節では、bundle を作るたびにタグ(例では lastR2bundle)を付け直しておき、次回はそのタグからの範囲で bundle を作る手順が紹介されています。どこまで渡したかをタグで覚えておく方法です。

bundle からブランチを、別の名前で取り込むこともできます。ブランチ名:新しい名前 の形で git fetch に渡します。

console
$ git fetch ../neko-app.bundle feature:copy-of-feature
From ../neko-app.bundle
 * [new branch]      feature    -> copy-of-feature

$ git branch
  copy-of-feature
  feature
* main

clone したリポジトリでは –all にリモート追跡ブランチも入る

clone してきたリポジトリで --all を使うと、refs/remotes/origin/… のリモート追跡ブランチまで bundle に入りました。自分のブランチとタグだけにしたいときは、--branches --tags を指定します。

console
$ git bundle create ../copy-all.bundle --all && git bundle list-heads ../copy-all.bundle
c4263b0f065590ad674d9df2dd9aad1fbb2906b9 refs/heads/copy-of-feature
c4263b0f065590ad674d9df2dd9aad1fbb2906b9 refs/heads/feature
9ff13f5e6bc4b55c66fdece235be000f3f7c663f refs/heads/main
9ff13f5e6bc4b55c66fdece235be000f3f7c663f refs/remotes/origin/HEAD
c4263b0f065590ad674d9df2dd9aad1fbb2906b9 refs/remotes/origin/feature
9ff13f5e6bc4b55c66fdece235be000f3f7c663f refs/remotes/origin/main
ba27b17fe6b7fd6c749a9e9004961e00333515db refs/tags/v1.0
9ff13f5e6bc4b55c66fdece235be000f3f7c663f HEAD

$ git bundle create ../copy-branches.bundle --branches --tags && git bundle list-heads ../copy-branches.bundle
c4263b0f065590ad674d9df2dd9aad1fbb2906b9 refs/heads/copy-of-feature
c4263b0f065590ad674d9df2dd9aad1fbb2906b9 refs/heads/feature
9ff13f5e6bc4b55c66fdece235be000f3f7c663f refs/heads/main
ba27b17fe6b7fd6c749a9e9004961e00333515db refs/tags/v1.0

公式リファレンスの OBJECT PREREQUISITES の節にも、git clone --mirror と同じように refs/remotes/* まで入れたいなら --all、元のリポジトリから直接 clone したときと同じものを渡したいなら --branches --tags を使う、と書かれています。--branches --tags の一覧には HEAD が出ません。この bundle から clone すると、さきほどと同じく init.defaultBranch の main が取り出されました。

console
$ git clone ../copy-branches.bundle ../branches-copy && git -C ../branches-copy status -sb
Cloning into '../branches-copy'...
## main...origin/main

なお、bundle は clone や fetch で読み取る専用です。公式リファレンスの冒頭の説明にあるとおり、bundle ファイルへの git push はできません。新しいコミットを渡すときは、そのつど git bundle create で作り直します。

HEAD のない bundle を clone したときに取り出されるブランチ

「入れるブランチを選ぶ」の節で見た、HEAD のない bundle の動きを、neko-copy の中から確かめます。main-only.bundle から clone した main-copy には、main のファイルが取り出されていました。設定を一時的に変えて(git -c)試すと、init.defaultBranch を trunk にしたときは main-only.bundle でも同じ警告が出ました。feature にしたときは、no-head.bundle から feature が取り出されました。

console
$ git config --global init.defaultBranch
main

$ ls ../main-copy
README.md
main.js

$ git -c init.defaultBranch=trunk clone ../main-only.bundle ../trunk-copy
Cloning into '../trunk-copy'...
warning: remote HEAD refers to nonexistent ref, unable to checkout

$ git -c init.defaultBranch=feature clone ../no-head.bundle ../feature-copy && git -C ../feature-copy status -sb && ls ../feature-copy
Cloning into '../feature-copy'...
## feature...origin/feature
README.md
main.js
paw.txt

​Posted by 86