DevOpsナレッジハブ
DevOpsナレッジハブ

破損したGitリポジトリの修復：完全なトラブルシューティングガイド

Gitリポジトリの破損に遭遇すると開発が停止する可能性がありますが、多くの場合回復は可能です。このガイドでは、不可欠なバックアップ手順から始まる、専門家レベルの段階的なトラブルシューティングワークフローを提供します。`git fsck`を使用して壊れたオブジェクトを診断し、`git reset`を使用してインデックスを修復し、`git reflog`を介して失われたコミットを回復し、壊れた参照を手動で修正する方法を学びます。軽微なインデックスエラーまたは深刻なオブジェクト損失のいずれに対処する場合でも、この記事ではリポジトリの整合性を安全に復元するための実用的なコマンドとベストプラクティスを提供します。

23 ビュー

破損したGitリポジトリの修復：完全なトラブルシューティングガイド

Gitリポジトリは一般的に堅牢ですが、ハードウェアの故障、突然のシステムクラッシュ、ディスクエラー、あるいは重要なGit操作（オブジェクトのパッキングや履歴の書き換えなど）中の電力損失といった外部要因によって、データ破損が発生する可能性があります。破損したリポジトリは、分かりにくいエラー、コミットの不能、またはオブジェクトの欠落の報告として現れることがあります。

このガイドでは、破損の種類を診断し、適切な修復技術を適用し、失われたデータを安全に回復するための体系的で段階的なアプローチを提供します。リポジトリの破損は永続的なデータ損失につながる可能性があるため、侵襲的な修復を試みる前に、必ず安全なバックアップを作成するというベストプラクティスに従ってください。

1. 安全第一：破損したリポジトリのバックアップ

修復コマンド、特に.gitディレクトリ内のファイルシステム操作を伴うものを開始する前に、完全なバックアップを作成する必要があります。これにより、修復プロセスがさらなる問題を引き起こした場合でも、現在の破損した状態に戻すことができます。

# リポジトリディレクトリの外に移動
cd ..

# ディレクトリ全体の圧縮バックアップを作成
tar -czvf myrepo_corrupted_backup.tar.gz myrepo/.git

# あるいは、単に.gitフォルダをコピーします
cp -r myrepo/.git myrepo_backup_$(date +%Y%m%d)

2. git fsckによる破損の診断

Gitリポジトリの整合性をチェックするための主要なツールはgit fsck（ファイルシステムチェック）です。このコマンドはオブジェクトデータベースと参照をスキャンし、不整合、欠落したオブジェクト、または壊れたリンクを探します。

包括的なチェックのために以下のコマンドを実行します:

# 詳細な出力で整合性チェックを実行
git fsck --full --unreachable --strict

git fsck出力の解釈

エラーメッセージ 意味 重要度 主な修正方法
error: object XXXXX is missing 必要なブロブ、ツリー、またはコミットオブジェクトが完全に欠落しています。 高 リモート/バックアップからの回復。
dangling commit XXXXX コミットは存在するが、どのブランチ、タグ、またはreflogからも参照されていない。 低/中 git reflogによる回復。
dangling blob XXXXX データは存在するが、どのコミットやツリーにもリンクされていない。 低 通常は無視またはプルーニング可能。
error: HEAD points to an unborn branch .git/HEADファイルが破損しているか、存在しないブランチを指している。 中 .git/HEADの手動修正またはgit reset。

3. Gitインデックス（.git/index）の修復

インデックスファイルは、Gitが作業ディレクトリと最後のコミット間の変更を追跡するために使用するステージングエリアのキャッシュです。インデックスの破損は、システムクラッシュやマージの失敗後に最もよく発生する問題の一つです。

Git操作がインデックスが無効、不整合、または読み取り不能であるというエラーで失敗する場合、インデックスを再構築する必要があります。

方法1：Gitにインデックスを再読み込みさせる

インデックス修復を試みる最も安全な方法は、ハードリセットを実行することです。これにより、Gitは最新のコミットに基づいてインデックスと作業ディレクトリを強制的に調和させます。

git reset --hard HEAD

方法2：インデックスを手動で削除し、再作成する

git resetが失敗した場合、破損したインデックスファイルを削除できます。次にコマンド（git statusやgit addなど）がそれを必要とするときに、Gitは自動的に再作成します。

警告: インデックスを削除すると、ステージングエリアがクリアされます。ステージングしていた変更（git addを使用したもの）はすべて失われます。 

# 破損したインデックスファイルを削除
rm .git/index

# 作業ディレクトリに基づいてGitにインデックスを再構築させる
# これにより、現在変更されているすべてのファイルがステージングされます
git add -A

# 機能を検証するためにステータスを確認
git status

4. 破損したオブジェクトと欠落したオブジェクトへの対処

破損したGitオブジェクト（ブロブ、ツリー、またはコミット）に関する破損は、特にオブジェクトが本当に欠落している場合、修復が最も困難なことが多いです。しかし、破損の原因が不適切なパッキングされたオブジェクトや回復可能な宙ぶらりんのオブジェクトである場合もあります。

4.1. リポジトリの再パック

Gitはオブジェクトをルーズファイルとして、またはパックファイルに統合して保存します。時として、repack操作を実行することで、軽微な整合性問題を解決し、パフォーマンスを向上させることができます。

# すべてのルーズオブジェクトを再パックし、整合性を検証し、古いパックファイルをプルーニング
git repack -a -d

# 改善を確認するためにfsckを再実行
git fsck --full

4.2. Reflogを介した宙ぶらりんのコミットの回復

dangling commitとは、有効ではあるものの、既知の参照（ブランチ、タグ）から到達できないコミットオブジェクトのことです。これは強制リセットや履歴の書き換え後に頻繁に発生します。reflogはローカルのHEADと参照の履歴を追跡し、多くの場合、回復の鍵を握っています。

  1. Reflogを表示:

bash git reflog
損失の原因となったアクションの前のSHA-1ハッシュを探します（例：HEAD@{5}: reset: moving to origin/main）。

  1. コミットを再参照する:

正しいSHA-1（例：a1b2c3d4）を特定したら、それを指す新しいブランチを作成するか、現在のブランチをリセットすることができます。

```bash
# 例：新しい回復ブランチを作成
git branch recovered-work a1b2c3d4

# あるいは、現在のブランチを宙ぶらりんのコミットにリセットします
# （注意して使用してください）
git reset --hard a1b2c3d4
```

4.3. 真に欠落しているオブジェクトへの対処

git fsckがerror: object XXXXX is missingと報告した場合、それは特定のコミット履歴に必要なデータがローカルのオブジェクトデータベース（.git/objects）にもはや存在しないことを意味します。

  • リモートが存在する場合: 唯一信頼できる解決策は、リモートリポジトリから欠落したオブジェクトをフェッチすることです。

    ```bash
    git fetch origin

    その後、リンクを修復するか、影響を受けるブランチをリセットを試みます

    ```

  • リモートが存在しない場合（ローカル破損）: リポジトリが完全にローカルであり、オブジェクトが欠落している場合、そのオブジェクトによって参照されるデータは、外部バックアップがない限り永久に失われます。

5. 破損した参照（Refs）の修復

参照（ref）とは、.git/refs/ディレクトリ内のファイル（例：ブランチ、タグ、リモート追跡ブランチ）で、それらが指すコミットのSHA-1ハッシュを含んでいます。これらのファイルが破損している場合（例：ゼロバイトまたは無効なハッシュを含んでいる場合）、Gitはブランチの状態を判断できません。

5.1. 特定と手動修復

  1. 破損した参照を特定します: エラーメッセージは通常、どの参照が壊れているかを指定します（例：error: bad ref for branch 'feature/X'）。

  2. refsディレクトリに移動します:

bash cd .git/refs/heads/ # または .git/refs/remotes/origin/

  1. ファイルを検査します: テキストエディタまたはcatを使用してファイルを表示します。ファイルには正確に40桁の16進数文字（SHA-1ハッシュ）が含まれているはずです。

  2. 修復:

  • ハッシュが既知の場合（例：git reflogから）、正しい40文字のSHA-1をファイルに手動で貼り付けます。
  • 参照が明らかに壊れている場合（例：ゼロバイト、ゴミデータ）、ファイルを削除します。その後、必要に応じてブランチ/参照を再作成する必要があります（例：git checkout -b <branch-name> <known-good-commit>）。

ベストプラクティス：Reflogの削除

Reflogデータベース全体が破損しているように見える場合、logsフォルダを削除するとGitは初期状態から再開され、多くの場合、深刻な参照問題が解決されます。

rm -rf .git/logs

6. 最終的な復旧オプション：既知の良好なソースからのクローン

リポジトリの破損が広範囲に及んでいる場合や、必要なオブジェクトが欠落している場合、最も安全で信頼性の高い回復方法は、現在のローカルリポジトリを破棄し、信頼できるソース（通常はGitHub、GitLab、Bitbucketのようなリモートサーバー）から再クローンすることです。

# 1. 破損したリポジトリの作業中の変更をバックアップします
# （例：未コミットのファイルを一時的な場所にコピーします）

# 2. 破損したリポジトリディレクトリの名前を変更または削除します
mv myrepo myrepo_bad

# 3. 新しいコピーをクローンします
git clone <remote_url> myrepo

# 4. バックアップした作業中の変更を新しいリポジトリに適用します

この方法により、確実にクリーンで検証済みのリポジトリ履歴から開始することができ、永続的な破損のリスクを最小限に抑えられます。

まとめと予防

破損したGitリポジトリを修復するには、インデックス、オブジェクト、または参照にターゲットを絞った修復を適用する前に、git fsckを使用して慎重な診断が必要です。開始する前に.gitディレクトリをバックアップすることで、常に安全を最優先してください。git reflogのようなローカルリカバリ方法は履歴を回復するのに強力ですが、リモートリポジトリからのクローンは、深刻な破損に対する最も信頼性の高い解決策です。

重要なポイント:

  1. まずバックアップ。 （常に）。
  2. git fsck --fullで診断。
  3. インデックスの問題は通常git reset --hardで修正されます。
  4. 欠落したオブジェクトは通常、リモートからのフェッチが必要です。