Gitの「checkoutでローカルの変更が上書きされます」エラーの原因と解決方法

Gitでは、コミットやstash（退避）をしていない状態で、同じファイルを2つのブランチ上で編集したままブランチを切り替えることはできません。これは、どの変更を保存し、どの変更を上書きすべきかをGitが判断できないためです。

本記事では、「Your local changes to the following files would be overwritten by checkout（以下のファイルへのローカルの変更はチェックアウトによって上書きされます）」というエラーの意味と、その修正方法を具体的な例とともに解説します。

エラーの内容とは？

Gitのバージョン管理システムでは、「ブランチ」と呼ばれる独立した開発ラインを維持できます。あるブランチでの変更は、2つのブランチをマージしない限り、別のブランチには反映されません。

ブランチに移動すると、リポジトリの歴史における特定の時点の状態を確認し、必要な変更を加えることができます。変更が完了したらコミットすることで、Gitはプロジェクトの変遷を記録し続けます。

しかし、両方のブランチに未コミットのファイル変更が含まれている場合、ブランチ間を切り替えることはできません。Gitは、そのファイルを保存すべきか、コミットの一部にすべきかを把握する必要があります。この仕組みにより、後から参照したいコードを誤って上書きしてしまう事故を防げます。

具体的なシナリオ例

まず、README.mdという1つのファイルを含むリポジトリをクローンします。

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

README.mdファイルの内容は以下のとおりです。

# ck-git

このリポジトリには「development」と「master」という2つのブランチがあります。ローカルの作業ディレクトリで、originのmasterブランチ上のREADME.mdファイルを次のように変更してみましょう。

# Career Karma Git

これで、ローカルのmasterブランチはリモートリポジトリと異なる状態になりました。次に、developmentブランチに切り替えて、そちらのREADMEの内容を以下のように変更します。

# Career Karma [Development]

developmentブランチ上でこのファイルを編集するには、以下のコマンドを実行します。

git checkout development
nano README.md

続いて、masterブランチに戻り、このブランチへの変更をコミットして、リモートリポジトリへプッシュします。

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

git checkoutコマンドにより、masterブランチへ切り替えることができます。ここまでの状況を整理すると、リモートリポジトリは以下の状態になっています。

• developmentブランチ上に変更済みのREADME.mdがある
• masterブランチが1コミット進んでいる

さらに、masterブランチ上でREADME.mdを再度変更してみましょう。

# Tutorials

これで、両方のブランチがリモートのmasterブランチと差分を持つ状態になりました。この変更が残ったまま、developmentブランチへ切り替えを試みます。

git checkout development

すると、このコマンドは次のエラーメッセージを返します。

error: Your local changes to the following files would be overwritten by checkout:
    README.md
Please commit your changes or stash them before you switch branches.
Aborting

解決方法

developmentブランチとmasterブランチの両方に未コミットの変更が含まれているため、Gitはチェックアウト処理を先に進められません。もしGitがそのまま処理を続行すると、masterブランチ上のREADME.mdに対して行った未コミットの変更が失われてしまうからです。

このエラーは2つの方法で解決できます。まず1つ目は、masterブランチ上で変更をコミットする方法です。

git add README.md
git commit -m "docs: Add tutorials message to README.md file"
git push

これらのコマンドでは、README.mdファイルをステージングエリアに追加し、ステージングエリアのすべてのファイルをコミットに含め、その変更をリモートリポジトリへプッシュしています。

これで、Gitは変更を加えた後のREADME.mdファイルの状態を記録しました。

もう1つの方法は、変更を一時的にstash（退避）しておくことです。これは、変更をまだコミットに含める準備ができていないものの、後から参照できるようにしておきたい場合に有効な解決策です。変更をstashするには、git stashコマンドを実行します。

git stash save README.md

これにより、README.mdファイルがstashに保存されます。このファイルを再び作業したいときは、stash popコマンドでstashにアクセスできます。

git stash pop

このコマンドを実行すると、README.mdファイルがリポジトリに復元されます。「stashする」とは、いわば「後回しにして保存する」という意味です。stashは変更をコミットとして記録するわけではない点に注意してください。

上記のいずれかの解決策を実行した後は、developmentブランチへ正常に移動できます。

git checkout development

このコマンドにより、ブランチが「development」へ切り替わり、ターミナルにその旨が表示されます。

Switched to branch 'development'

これで問題は解決です。

まとめ

Gitの「Your local changes to the following files would be overwritten by checkout」エラーは、変更をコミットまたはstashせずに2つのブランチ上で編集を行い、その状態でブランチ間を移動しようとしたときに発生します。

この問題は、変更を後のためにstashしておくか、コミットに追加することで解決できます。

これで、プロのようにこのエラーを修正するための知識が身につきました！