Git에서 브랜치를 바꾸려고 할 때 error: Your local changes to the following files would be overwritten by checkout:, Please commit your changes or stash them before you switch branches., Aborting 메시지가 나오면 현재 브랜치의 로컬 수정사항을 먼저 정리해야 합니다.
이 오류는 현재 작업을 commit, stash, restore, 새 브랜치 저장 중 하나로 정리하면 해결할 수 있습니다. 다만 git reset --hard부터 실행하는 방식은 안전하지 않습니다. 이 명령은 커밋하지 않은 변경사항을 잃을 수 있으므로, 먼저 git status와 git diff로 현재 작업 내용을 확인해야 합니다.
Git branch 변경 오류 메시지 원문
브랜치 이동이 막히면 터미널에 아래와 비슷한 메시지가 표시됩니다. checkout을 사용해도 나오고, switch를 사용할 때도 같은 의미의 안내가 나올 수 있습니다.
error: Your local changes to the following files would be overwritten by checkout:
src/app.js
package.json
Please commit your changes or stash them before you switch branches.
Aborting이 메시지는 Git이 브랜치 변경을 실패했다는 뜻이 아니라, 사용자의 로컬 수정사항이 덮어써질 가능성이 있어 이동을 멈췄다는 뜻입니다. 즉, Git이 작업 내용을 보호하기 위해 브랜치 변경을 막은 상태입니다.
git reset --hard는 빠르게 보이지만 기본 해결책이 아닙니다. 현재 수정한 파일을 잃을 수 있으므로, branch 변경 오류에서는 먼저 commit, stash, restore, 새 브랜치 저장 중 어떤 방식이 맞는지 판단해야 합니다.
왜 브랜치 이동이 막힐까
이 오류는 현재 브랜치에서 수정한 파일이 있고, 이동하려는 브랜치에도 같은 파일의 다른 버전이 있을 때 자주 발생합니다. Git은 브랜치를 바꾸면서 작업 디렉터리 파일을 대상 브랜치 상태로 맞추는데, 이 과정에서 아직 저장하지 않은 변경사항이 사라질 수 있으면 이동을 중단합니다.
먼저 확인할 명령어
오류가 나오면 어떤 파일이 수정됐는지 먼저 확인합니다. Windows, Mac, Linux 모두 아래 Git 명령어는 공통으로 사용할 수 있습니다.
git status현재 어느 브랜치에 있는지도 함께 확인합니다.
git branch수정 내용이 중요한지 판단하려면 아래 명령어로 실제 변경 내용을 확인하는 것이 좋습니다.
git diff작업이 의미 있는 단위로 끝났다면 commit, 아직 임시 작업이면 stash, 필요 없는 수정이면 restore, 현재 작업을 따로 보존하고 싶다면 새 브랜치를 만드는 방식이 안전합니다.
commit, stash, restore, 새 브랜치 저장 차이
같은 오류라도 작업 상태에 따라 선택해야 할 해결 방법이 다릅니다. 아래 표를 먼저 보고 현재 상황에 맞는 방법을 고르면 됩니다.
해결 방법 1: 수정사항을 commit하고 브랜치 변경
현재 작업이 어느 정도 완성됐고 기록으로 남겨도 된다면 commit 후 브랜치를 바꾸는 방법이 가장 깔끔합니다. 팀 프로젝트에서는 작업 단위가 명확할수록 나중에 되돌리거나 리뷰하기 쉽습니다.
git add .
git commit -m "Save work before switching branch"
git switch 브랜치명checkout을 사용하는 프로젝트라면 아래처럼 이동할 수도 있습니다.
git checkout 브랜치명git pull 중에 나오는 local changes 오류와 헷갈릴 수 있지만, 이 글의 상황은 “원격 변경을 가져오는 중”이 아니라 “브랜치를 바꾸는 중”에 로컬 수정사항이 막는 경우입니다. 원격 변경을 가져오다 막힌 경우라면 Git pull 오류에서 local changes would be overwritten by merge가 나올 때 처리 순서를 확인하는 편이 맞습니다.
해결 방법 2: 아직 애매하면 stash 후 브랜치 변경
작업이 덜 끝났고 commit으로 남기기 애매하다면 stash가 적합합니다. stash는 현재 작업 내용을 임시로 보관하고 작업 디렉터리를 깨끗한 상태로 돌려 브랜치 이동을 쉽게 해줍니다.
git stash push -m "work before branch switch"
git switch 브랜치명보관된 stash 목록은 아래 명령어로 확인합니다.
git stash list다시 작업 내용을 꺼낼 때는 아래 명령어를 사용합니다.
git stash popgit stash pop은 stash를 적용한 뒤 목록에서 제거합니다. 적용만 하고 목록에 남겨두고 싶다면 git stash apply를 사용할 수 있습니다.
해결 방법 3: 필요 없는 수정사항이면 restore
수정한 내용이 필요 없다면 되돌릴 수 있습니다. 다만 삭제나 초기화에 가까운 작업이므로, 실행 전에 git status와 git diff로 버릴 내용이 맞는지 확인해야 합니다.
특정 파일만 되돌릴 때는 아래처럼 실행합니다.
git restore 파일명
아래 명령어는 커밋하지 않은 변경사항을 삭제할 수 있습니다. 실행 전 git status, git diff로 버릴 내용이 맞는지 확인하고, 필요한 파일은 따로 백업해 두는 것이 좋습니다.
git restore .해결 방법 4: 현재 작업을 새 브랜치로 저장
현재 작업이 원래 브랜치에 들어가면 안 되지만 버리기도 아깝다면 새 브랜치를 만들어 저장하는 방법이 좋습니다. 이렇게 하면 지금 작업을 잃지 않고, 원래 이동하려던 브랜치로 돌아갈 수 있습니다.
git switch -c 새브랜치명
git add .
git commit -m "Save current work"이후 원래 이동하려던 브랜치로 바꾸면 됩니다.
git switch 이동할브랜치명VSCode Source Control에서 처리하는 방법
VSCode에서는 왼쪽 Source Control 패널에서 수정된 파일을 확인할 수 있습니다. 파일명을 클릭하면 변경 전후를 비교할 수 있고, 필요한 파일은 stage한 뒤 commit할 수 있습니다. 터미널 명령어가 익숙하지 않다면 먼저 VSCode 화면에서 어떤 파일이 바뀌었는지 확인하는 것이 좋습니다.
1. 왼쪽 Source Control 아이콘을 클릭합니다.
2. Changes 목록에서 수정된 파일을 확인합니다.
3. 필요한 작업이면 메시지를 입력하고 commit합니다.
4. 아직 임시 작업이면 터미널에서 stash를 사용합니다.
5. 필요 없는 수정이면 파일별로 Discard Changes를 선택합니다.
6. Discard 전에는 변경 내용을 diff 화면에서 반드시 확인합니다.
VSCode에서 커밋, 푸시, 브랜치 전환, 충돌 해결 화면이 낯설다면 VSCode Git 입문 2026에서 커밋·푸시·브랜치 흐름을 먼저 확인하면 터미널 명령어와 화면 동작을 함께 이해하기 쉽습니다.
checkout과 switch 차이
git checkout은 오래전부터 브랜치 이동과 파일 복원에 함께 쓰이던 명령어입니다. 하나의 명령어가 여러 역할을 하다 보니 초보자에게 헷갈릴 수 있습니다. git switch는 브랜치 전환 목적을 더 분명하게 나눈 명령어입니다.
새 브랜치를 만들면서 이동할 때는 아래처럼 사용할 수 있습니다.
git switch -c 새브랜치명reset --hard는 마지막 수단으로만 생각하기
git reset --hard는 현재 작업 디렉터리와 스테이지 상태를 특정 커밋 기준으로 강하게 되돌리는 명령어입니다. 이 과정에서 커밋하지 않은 변경사항을 잃을 수 있으므로, branch 변경 오류의 기본 해결책으로 쓰지 않는 것이 좋습니다.
git reset --hard를 꼭 써야 한다면 먼저 git status, git diff로 변경 내용을 확인하고, 필요한 파일은 복사해 백업합니다. 팀 저장소에서는 현재 브랜치와 작업 범위를 다시 확인한 뒤 실행해야 합니다.
Git pull 오류, merge conflict와 헷갈리지 않는 기준
비슷한 메시지처럼 보여도 상황은 다릅니다. branch 변경 오류는 브랜치를 바꾸려는 순간 로컬 수정사항이 막는 문제입니다. Git pull 오류는 원격 변경을 가져오는 과정에서 로컬 수정사항이 막는 문제입니다. merge conflict는 Git이 병합을 시도했지만 같은 부분의 변경을 자동으로 합치지 못한 상태입니다.
공식 자료로 더 확인하기
Git 명령어는 작업 이력과 파일 상태에 직접 영향을 줍니다. 명령어의 역할이 헷갈릴 때는 공식 문서에서 목적과 옵션을 확인한 뒤 실행하는 것이 안전합니다.
브랜치를 전환할 때 사용하는 switch와 checkout의 역할을 확인할 수 있습니다.
git switch 공식 문서 확인하기git checkout 공식 문서 확인하기
임시 저장이 필요한 경우와 작업 내용을 되돌려야 하는 경우에 사용할 명령어를 확인할 수 있습니다.
git stash 공식 문서 확인하기git restore 공식 문서 확인하기
VSCode Source Control 화면에서 변경사항 확인, stage, commit, branch, stash 흐름을 확인할 수 있습니다.
VS Code Source Control 공식 문서 확인하기함께 보면 좋은 글
자주 묻는 질문
Git branch 변경 오류는 대부분 현재 작업을 commit, stash, restore 중 하나로 정리하면 안전하게 해결할 수 있습니다.
댓글