【Git】「Your local changes to the following files would be overwritten by merge」エラーの原因と解決方法

Gitでは、ローカルマシン上でコミットしていない変更とリモートリポジトリの内容との間に競合がある場合、リモートからコードをプルすることができません。これは、保持しておきたいコードが誤って上書きされるのを防ぐための仕組みです。

本記事では、「Your local changes to the following files would be overwritten by merge（次のファイルへのローカルの変更はマージによって上書きされます）」というエラーの原因と、その具体的な解決方法を詳しく解説します。

エラーが発生する仕組み

ローカルリポジトリの状態は、リモートリポジトリとは異なることがよくあります。これはGitの基本的な機能の一つです。準備が整うまで、ローカルでの変更をリモートリポジトリにプッシュせずに自由に作業を進められます。

リモートリポジトリからコードをプルすると、Gitはそのリポジトリの内容を取得し、ローカルマシンに保存します。ただしこの操作が実行されるのは、保存したいファイルへの変更がすべてコミット済みである場合のみです。

変更をコミットせずにコードをプルしようとすると、「Your local changes to the following files would be overwritten by merge」というエラーが表示されることがあります。このエラーは、ローカルで修正したファイルが、リモートリポジトリ側でも変更されている場合にのみ発生します。

具体例で理解する

ここでは、ck-gitという名前のGitリポジトリを例に見ていきましょう。まず、リポジトリのコピーをクローンします。

git clone https://github.com/career-karma-tutorials/ck-git

これでローカルマシン上にリポジトリのコピーが作成されました。このリポジトリにはREADME.mdというファイルが1つ含まれており、内容は以下の通りです。

# ck-git

次に、GitHub上でこのファイルを直接編集し、以下のように変更したとします。

# Career Karma Git

この時点で、ローカルのリポジトリとリモートのmasterブランチの内容が異なる状態になっています。ローカル側にはクローン時点のコードが残っており、リモート側にはREADME.mdへの変更が反映されています。

さらに、ローカルマシン上でもREADME.mdを以下のように変更してみましょう。

# CK Git

ファイルを変更したら、リモートリポジトリの変更をローカルに取り込むためにプルを実行します。

git pull

すると、次のようなエラーが返されます。

...
Updating a30b784..ec281fc
error: Your local changes to the following files would be overwritten by merge:
    README.md
Please commit your changes or stash them before you merge.
Aborting

出力は簡潔にするため一部省略しています。注目すべきメッセージは「Your local changes to the following files would be overwritten by merge」の部分です。このエラーが発生すると、マージ処理は中断（Aborting）されます。

解決策1：変更をコミットする

この時点で、ファイルには2つのバージョンが存在しています。1つはローカルマシン上のもので、もう1つはリモートリポジトリにあるものです。リモートからコードをプルしても、Gitはどちらのバージョンを残すべきか判断できません。

このエラーを解決するには、変更をコミットするか、スタッシュするかのどちらかを行います。

まず、コミットによる解決方法です。README.mdをステージングに追加し、コミットを作成します。

git add README.md
git commit -m "docs: Update README.md"

これにより、ローカルで行ったREADME.mdへの変更がプロジェクトのコミット履歴に記録され、Gitはこれらの変更を保持すべきものだと認識します。その後、再度git pullを実行すれば、エラーなくリモートの変更を取り込めるようになります。

解決策2：変更をスタッシュする

もう一つの解決策は、変更をスタッシュ（stash）することです。スタッシュを使うと、変更を一時的に退避させ、後で確認・復元できます。git stashコマンドを使用します。

git stash

このコマンドは変更をスタッシュ領域に保存します（コードを一時的に「しまっておく」イメージです）。スタッシュした後は、ワーキングディレクトリがクリーンな状態になるため、リモートリポジトリから安全にコードをプルできます。

スタッシュした変更を復元するには、git stash popコマンドを実行します。

git stash pop

このコマンドにより、コミットせずに退避しておいた変更をワーキングディレクトリに戻せます。後から変更をコミットしたくなった場合も、問題なく対応できます。

まとめ

「Your local changes to the following files would be overwritten by merge」エラーは、リモートリポジトリの内容とローカルリポジトリの内容が競合している状態でプルを実行した際に発生します。

このエラーを解決するには、変更をコミットするか、git stashで一時的に退避させるかのいずれかを行いましょう。状況に応じて適切な方法を選べば、プロのようにスムーズにこのエラーを解決できるはずです。