Git '체크아웃 시 로컬 변경 사항이 덮어써집니다' 오류 해결 가이드

Git에서 두 개의 브랜치에서 동일한 파일을 수정한 상태로, 커밋이나 스태시(stash) 없이 브랜치를 전환할 수는 없습니다. Git은 어떤 변경 사항을 저장하고 어떤 변경 사항을 덮어써야 할지 판단할 수 없기 때문입니다.

이 가이드에서는 "Your local changes to the following files would be overwritten by checkout"(다음 파일에 대한 로컬 변경 사항이 체크아웃에 의해 덮어써집니다) 오류의 의미와 함께, 실제 예제를 통해 이 오류를 해결하는 방법을 자세히 살펴보겠습니다.

오류의 의미: 체크아웃 시 로컬 변경 사항이 덮어써지는 이유

Git 버전 관리 시스템은 브랜치(branch)라고 불리는 독립적인 개발 라인을 유지할 수 있도록 지원합니다. 한 브랜치에서 발생한 변경 사항은 두 브랜치를 병합(merge)하기 전까지는 다른 브랜치에 반영되지 않습니다.

브랜치로 이동하면 저장소의 특정 시점을 확인하고 필요한 변경 작업을 수행할 수 있습니다. 작업이 완료되면 변경 사항을 커밋(commit)하여 Git이 프로젝트의 변화를 추적하도록 해야 합니다.

그런데 두 브랜치 모두 커밋되지 않은 파일 변경 사항을 포함하고 있다면 브랜치 간 전환이 불가능합니다. Git은 해당 파일을 그대로 저장해야 하는지, 아니면 커밋의 일부로 포함해야 하는지 알 수 없기 때문입니다. 이는 나중에 다시 참조하고 싶은 코드를 실수로 덮어쓰는 것을 방지하는 안전장치 역할을 합니다.

예제 시나리오

README.md라는 파일 하나가 담긴 저장소를 클론(clone)해 보겠습니다:

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

README.md 파일의 내용은 다음과 같습니다:

# ck-git

이 저장소에는 development와 master라는 두 개의 브랜치가 있습니다. 로컬 작업 디렉터리에서 origin master 브랜치의 README.md 파일을 다음과 같이 수정해 보겠습니다:

# Career Karma Git

이제 master 브랜치는 원격 저장소와 달라진 상태입니다. development 브랜치로 전환한 후 해당 브랜치의 README 파일 내용을 다음과 같이 변경하겠습니다:

# Career Karma [Development]

development 브랜치에서 이 파일을 수정하려면 다음 명령어를 실행합니다:

git checkout development
nano README.md

다음으로 master 브랜치로 다시 전환한 후, 해당 브랜치에서 변경한 내용을 커밋하고 원격 저장소에 푸시(push)합니다:

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

git checkout 명령어로 master 브랜치로 전환했습니다. 정리하면 현재 원격 저장소의 상태는 다음과 같습니다:

• development 브랜치에 수정된 README.md
• 커밋 하나만큼 앞서 있는(ahead one commit) master 브랜치

이제 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에 적용했던 커밋되지 않은 변경 사항은 저장되지 않고 사라졌을 것입니다.

이 오류는 두 가지 방법으로 해결할 수 있습니다. 첫 번째 방법은 master 브랜치에서 변경 사항을 커밋하는 것입니다:

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

위 명령어들은 README.md 파일을 스테이징 영역(stage)에 추가하고, 스테이징 영역의 모든 파일을 커밋에 포함한 뒤, 변경 사항을 원격 저장소에 푸시합니다.

이제 Git은 수정된 README.md 파일의 변경 기록을 안전하게 보관하게 됩니다.

두 번째 방법은 변경 사항을 나중을 위해 스태시(stash)에 임시 저장하는 것입니다. 변경 사항을 아직 커밋할 준비가 되지 않았지만 나중에 다시 사용하고 싶을 때 유용한 해결책입니다. 변경 사항을 스태시하려면 git stash 명령어를 실행합니다:

git stash save README.md

이렇게 하면 README.md 파일이 스태시에 저장됩니다. 나중에 이 파일을 다시 확인할 준비가 되면 stash pop 명령어로 스태시에 접근할 수 있습니다:

git stash pop

이 명령은 저장소의 README.md 파일을 복원합니다. "스태싱(stashing)"은 쉽게 말해 "나중을 위해 저장해 두는 것"을 의미하며, 스태시는 변경 사항으로 커밋을 생성하지 않는다는 점이 특징입니다.

위 해결 방법 중 하나를 실행한 후에는 development 브랜치로 성공적으로 이동할 수 있습니다:

git checkout development

이 명령은 현재 브랜치를 "development"로 전환하고, 터미널에 다음과 같이 알려줍니다:

Switched to branch 'development'

문제가 성공적으로 해결되었습니다.

마무리

Git의 "Your local changes to the following files would be overwritten by checkout" 오류는 두 브랜치에서 변경 사항을 커밋하거나 스태시하지 않은 상태로 브랜치 간에 이동하려고 할 때 발생합니다.

이 문제는 변경 사항을 나중을 위해 스태시에 저장하거나 커밋에 추가하는 두 가지 방법으로 해결할 수 있습니다.

이제 여러분도 이 오류를 전문가처럼 손쉽게 해결할 수 있습니다!