원격 저장소에서 코드를 pull할 때, 로컬에서 아직 커밋하지 않은 변경 사항과 원격 저장소의 내용 사이에 충돌이 있으면 코드를 가져올 수 없습니다. 이는 여러분이 소중히 여기는 코드가 실수로 덮어써지는 것을 막아주는 Git의 안전장치입니다.
이 글에서는 "Your local changes to the following files would be overwritten by merge" 오류가 왜 발생하는지 살펴보고, 실제 예시를 통해 해결 방법까지 단계별로 알아보겠습니다.
오류가 발생하는 이유
로컬 저장소의 버전은 원격 저장소의 버전과 다른 경우가 많습니다. 이것이야말로 Git의 핵심 기능입니다. 준비가 될 때까지 로컬에서 자유롭게 작업하고, 원격 저장소에는 푸시하지 않아도 되기 때문입니다.
원격 저장소에서 코드를 pull하면 Git은 해당 저장소의 내용을 가져와 로컬 머신에 저장합니다. 이 과정은 저장하고 싶은 모든 파일 변경 사항을 미리 커밋해 둔 상태일 때만 정상적으로 수행됩니다.
변경 사항을 커밋하지 않은 상태에서 pull을 시도하면 "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 파일 하나가 들어 있으며, 내용은 다음과 같습니다:
# ck-git
이번에는 GitHub에서 서버 쪽의 파일을 직접 수정해 보겠습니다. 수정 후 파일 내용은 다음과 같습니다:
# Career Karma Git
이제 로컬 저장소 버전은 원격 저장소의 origin master 브랜치와 달라졌습니다. 로컬 버전은 클론 당시의 원격 저장소 코드를 담고 있고, 원격 저장소에는 README.md에 대한 새로운 변경 사항이 반영되어 있습니다.
여기서 로컬 머신의 README.md도 수정해 보겠습니다:
# CK Git
파일을 변경했습니다. 이제 원격 저장소의 최신 변경 사항을 pull해서 로컬에 반영해 보겠습니다:
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"입니다.
해결 방법
현재 파일의 두 가지 버전이 존재합니다. 하나는 로컬 머신에 있는 버전이고, 다른 하나는 원격 저장소에 있는 버전입니다. 이 상태에서 pull을 실행하면 Git은 어떤 버전을 남겨야 할지 판단하지 못해 작업을 중단합니다.
이 오류를 해결하는 방법은 크게 두 가지입니다. 변경 사항을 커밋하거나, stash로 임시 저장하는 것입니다.
방법 1: 변경 사항 커밋하기
README.md 파일을 스테이징하고 커밋을 생성합니다:
git add README.md git commit -m "docs: Update README.md"
이렇게 하면 로컬에서 README.md에 가한 변경 사항이 프로젝트의 커밋 히스토리에 기록됩니다. Git은 이제 해당 변경 사항을 유지해야 한다는 것을 인식하므로, 이후 pull이 정상적으로 진행됩니다.
방법 2: git stash로 임시 저장하기
두 번째 방법은 변경 사항을 stash에 임시 저장하는 것입니다. 이렇게 하면 나중에 변경 사항을 꺼내 확인할 수 있습니다. git stash 명령어를 사용합니다:
git stash
이 명령은 현재 변경 사항을 stash 영역에 저장합니다(코드가 나중을 위해 "잠시 치워진" 상태가 됩니다). 이제 안전하게 원격 저장소에서 코드를 pull할 수 있습니다:
git stash pop
git stash pop 명령을 실행하면 stash에 저장해 둔 코드를 다시 꺼내올 수 있습니다. 이를 통해 커밋하지 않았던 파일 변경 사항을 복원할 수 있으며, 나중에 해당 변경 사항을 커밋하기로 결정하면 그때 진행하면 됩니다.
마무리
"Your local changes to the following files would be overwritten by merge" 오류는 원격 저장소의 내용이 로컬 저장소 버전과 충돌하는 상태에서 pull을 시도할 때 발생합니다.
이 오류를 해결하려면 변경 사항을 stash로 임시 저장하거나 커밋하면 됩니다. 이제 전문가처럼 이 오류를 손쉽게 해결할 준비가 되셨습니다!