Git pull 오류 해결: Your local changes would be overwritten by merge 원인과 해결

로컬에서 수정한 파일과 원격 저장소의 변경 내용이 겹치면 Git은 병합을 멈추고 먼저 선택을 요구합니다.

Git에서 git pull을 실행했는데 Your local changes would be overwritten by merge 오류가 나오면, 원격 저장소 문제가 아니라 내 컴퓨터에 아직 정리되지 않은 수정 내용이 있다는 뜻입니다.

먼저 정해야 할 것은 로컬 수정 내용을 어떻게 처리할지입니다. 남길 작업이면 commit, 잠시 보관할 작업이면 stash, 버려도 되는 작업이면 restore를 선택한 뒤 다시 pull을 실행하면 됩니다. 바로 되돌리기 명령어를 실행하기 전에 git status와 git diff로 바뀐 파일부터 확인하세요.

오류 메시지 원문

터미널, VSCode Source Control, Git Bash, PowerShell에서 보통 아래와 비슷한 메시지가 표시됩니다.

error: Your local changes to the following files would be overwritten by merge:
    path/to/file
Please commit your changes or stash them before you merge.
Aborting

파일명이 여러 개 표시될 수도 있습니다. 표시된 파일은 현재 내 작업 폴더에서 수정된 상태이며, 원격 저장소에서 내려받을 변경 내용과 겹칠 가능성이 있는 파일입니다.

언제 발생하는 오류인지

git pull은 원격 저장소의 변경 내용을 가져온 뒤 현재 브랜치에 합치는 작업입니다. 이때 내 컴퓨터에서 아직 커밋하지 않은 파일이 있고, 원격 저장소에도 같은 파일의 변경이 있으면 Git은 자동 병합을 진행하지 않습니다.

자주 발생하는 상황은 다음과 같습니다.

상황	예시	확인 방법
로컬 파일을 수정한 뒤 pull	코드 수정 후 commit 없이 pull 실행	git status
팀원이 같은 파일을 먼저 push	같은 컴포넌트, 설정 파일, README 수정	git fetch 후 비교
도구가 파일을 자동 변경	VSCode 자동 포맷, 줄바꿈, lock 파일 변경	git diff

원인 3가지

1. 로컬 수정 내용을 아직 commit하지 않음

가장 흔한 원인입니다. 파일을 수정했지만 아직 git add와 git commit을 하지 않은 상태에서 pull을 실행하면 Git은 내 작업 내용을 보호하기 위해 중단합니다.

git status
git diff

git status에서 modified 파일이 보이면 아직 정리되지 않은 변경 내용이 있는 상태입니다.

2. 원격 저장소와 같은 파일을 수정함

내가 수정한 파일과 팀원이 원격 저장소에 올린 파일이 같으면 pull 과정에서 병합 충돌이 날 수 있습니다. Git은 이때 내 파일을 조용히 덮어쓰지 않고, 먼저 commit 또는 stash를 하라고 안내합니다.

특히 팀 프로젝트에서는 package-lock.json, yarn.lock, README.md, 환경 설정 파일, 공통 컴포넌트에서 자주 발생합니다.

3. VSCode 자동 포맷·줄바꿈·권한 변경으로 파일이 바뀜

코드를 직접 많이 수정하지 않았는데도 파일이 변경된 것으로 표시될 수 있습니다. VSCode의 저장 시 자동 포맷, Windows의 CRLF 줄바꿈, Mac·Linux의 실행 권한 변경이 원인이 될 수 있습니다.

git diff --stat
git diff --summary

내용 변경이 아니라 줄바꿈이나 파일 권한만 바뀐 경우에는 팀의 설정 기준에 맞춰 .gitattributes 또는 Git 설정을 정리하는 것이 좋습니다.

빠른 해결 방법: 먼저 변경 내용을 확인한다

아래 2개 명령어를 먼저 실행해 현재 상태를 확인합니다.

git status
git diff

그다음 내 수정 내용을 어떻게 처리할지 선택합니다.

선택	언제 사용하나	핵심 명령어
commit	내 수정 내용을 정식 작업 기록으로 남길 때	git add, git commit
stash	아직 커밋하기 애매하지만 잠시 치워두고 pull할 때	git stash
restore	내 로컬 수정 내용을 버려도 될 때	git restore

방법 1. 내 수정 내용을 살릴 때: commit 후 pull

현재 작업이 의미 있는 변경이라면 commit으로 기록한 뒤 pull을 실행합니다. 팀 프로젝트에서 가장 안전하고 추적하기 쉬운 방식입니다.

git status
git add .
git commit -m "작업 내용 설명"
git pull

특정 파일만 커밋하고 싶다면 아래처럼 파일명을 지정합니다.

git add path/to/file
git commit -m "작업 내용 설명"
git pull

pull 이후 충돌이 발생하면 충돌 파일을 수정한 뒤 다시 add와 commit을 진행합니다.

git status
git add path/to/conflicted-file
git commit

방법 2. 잠시 치워두고 pull할 때: stash 사용

아직 커밋할 정도로 정리되지 않은 작업이라면 stash를 사용합니다. stash는 현재 수정 내용을 임시 보관함에 넣고 작업 폴더를 깨끗한 상태로 되돌립니다.

git status
git stash push -m "before pull"
git pull
git stash pop

git stash pop을 실행하면 임시 보관한 수정 내용이 다시 적용됩니다. 이때 원격 변경과 겹치면 충돌이 날 수 있으므로, 충돌 표시를 확인하고 파일을 정리해야 합니다.

stash 목록을 확인하려면 아래 명령어를 사용합니다.

git stash list

특정 stash를 적용만 하고 목록에는 남겨두고 싶다면 pop 대신 apply를 사용합니다.

git stash apply stash@{0}

방법 3. 내 수정 내용을 버릴 때: restore 사용

특정 파일의 로컬 수정만 버리려면 아래 명령어를 사용합니다.

git restore path/to/file
git pull

현재 폴더의 모든 로컬 수정을 버려도 확실한 경우에만 아래 명령어를 사용합니다.

git restore .
git pull

이미 git add로 스테이징한 파일은 먼저 스테이징을 해제한 뒤 restore를 실행할 수 있습니다.

git restore --staged path/to/file
git restore path/to/file
git pull

commit, stash, restore 차이

세 명령은 모두 pull 오류 해결에 사용할 수 있지만 목적이 다릅니다. 초보자라면 “저장, 임시보관, 버리기”로 구분하면 이해하기 쉽습니다.

명령	의미	추천 상황
commit	변경 내용을 Git 기록으로 저장	작업이 의미 있고 나중에 추적해야 할 때
stash	변경 내용을 임시로 숨김	아직 커밋하기 애매하지만 pull이 필요할 때
restore	로컬 수정 내용을 되돌림	실수로 바뀐 파일을 버려도 될 때

Windows, Mac, Linux에서 다른 점

Git 명령어 자체는 Windows, Mac, Linux에서 거의 같습니다. 차이는 터미널, 경로 표기, 줄바꿈, 파일 권한에서 주로 발생합니다.

Windows

Windows에서는 PowerShell, 명령 프롬프트, Git Bash, VSCode 터미널을 사용할 수 있습니다. Git 명령어에서는 Windows 경로의 역슬래시보다 슬래시를 쓰는 방식이 더 안전합니다.

git restore src/app.js

Windows에서는 CRLF 줄바꿈 때문에 파일 전체가 변경된 것처럼 보일 수 있습니다. 반복된다면 팀 기준에 맞춰 줄바꿈 설정을 확인합니다.

git config --global core.autocrlf

Mac

Mac에서는 기본 Terminal 또는 iTerm, VSCode 터미널에서 같은 명령어를 사용할 수 있습니다. 파일명 대소문자, 실행 권한 변경, zsh 환경 설정 때문에 변경 사항이 생기는 경우가 있습니다.

git diff --summary

Linux

Linux도 Git 명령어는 동일합니다. 다만 파일 권한 변경이 Git diff에 나타날 수 있으므로, 실제 코드 변경인지 권한 변경인지 확인하는 것이 좋습니다.

git diff --summary
git status

VSCode에서 해결하는 방법

VSCode에서 pull 오류가 났다면 터미널 명령어를 몰라도 Source Control 화면에서 대부분 처리할 수 있습니다.

1. 변경 파일 확인

왼쪽 사이드바의 Source Control 아이콘을 열고 변경된 파일 목록을 확인합니다. 파일을 클릭하면 왼쪽에는 이전 내용, 오른쪽에는 현재 수정 내용이 표시됩니다.

2. 수정 내용을 저장하려면 Commit

저장할 변경이라면 파일 옆의 + 버튼으로 stage 처리한 뒤 메시지를 입력하고 Commit을 실행합니다. 이후 Pull을 다시 실행합니다.

git add .
git commit -m "작업 내용 설명"
git pull

3. 잠시 치워둘 변경이라면 Stash

VSCode Source Control의 더보기 메뉴에서 Stash 관련 메뉴를 사용할 수 있습니다. 메뉴 이름은 버전과 확장 설정에 따라 조금 다를 수 있으므로, 보이지 않으면 VSCode 터미널에서 아래 명령어를 실행합니다.

git stash push -m "before pull"
git pull
git stash pop

4. 버려도 되는 변경이라면 Discard Changes

파일 단위로 버릴 경우 변경 파일을 우클릭한 뒤 Discard Changes를 선택합니다. 이 작업은 git restore path/to/file과 비슷하게 로컬 수정 내용을 되돌리므로, 버려도 되는 파일인지 먼저 확인해야 합니다.

5. 충돌이 생기면 Accept Current, Accept Incoming을 선택

stash를 다시 적용하거나 pull 후 충돌이 생기면 VSCode 편집기에 충돌 표시가 나타납니다. 내 변경을 유지하려면 Current, 원격 변경을 선택하려면 Incoming, 둘 다 조합하려면 Both를 기준으로 정리합니다. 정리 후에는 파일을 저장하고 add, commit을 진행합니다.

git add .
git commit -m "resolve merge conflict"

복사해서 쓰는 상황별 Git 명령어

현재 상태만 확인

git status
git diff

내 변경을 커밋하고 pull

git add .
git commit -m "save local changes"
git pull

내 변경을 임시 보관하고 pull

git stash push -m "before pull"
git pull
git stash pop

특정 파일 수정만 버리고 pull

git restore path/to/file
git pull

모든 로컬 수정을 버리고 pull

git restore .
git pull

재발 방지 방법

이 오류는 pull 전에 작업 상태를 확인하고, 작업 단위를 작게 나누어 커밋하면 대부분 줄일 수 있습니다.

• 작업 시작 전 git pull로 최신 상태를 먼저 맞춥니다.
• 작업 중간마다 작은 단위로 commit합니다.
• 아직 미완성 작업이면 pull 전에 stash를 사용합니다.
• VSCode 저장 시 자동 포맷 범위를 팀 기준에 맞춥니다.
• 줄바꿈 문제가 반복되면 .gitattributes를 저장소에 추가합니다.
• 팀원이 자주 수정하는 공통 파일은 작업 전 브랜치와 담당 범위를 확인합니다.
• 원격 저장소 주소가 바뀐 경우에는 pull 전에 git remote -v로 origin을 확인합니다.

작업 전 확인 루틴은 아래처럼 짧게 만들 수 있습니다.

git status
git pull
git checkout -b feature/my-work

공식 자료로 더 확인하기

Git 명령어는 버전과 환경에 따라 옵션 설명이나 출력 메시지가 다르게 보일 수 있습니다. pull, stash, restore의 세부 옵션은 공식 문서를 기준으로 확인하면 잘못된 명령어 선택을 줄일 수 있습니다.

함께 보면 좋은 글

자주 묻는 질문

Git pull 오류는 먼저 로컬 변경 내용을 확인한 뒤, 살릴 작업은 commit, 잠시 보관할 작업은 stash, 버려도 되는 작업은 restore로 처리하면 안전하게 해결할 수 있습니다.