작업 중 다른 브랜치로 급히 전환할 때 — git stash 사용법 실전 예제

새 기능을 한창 개발하던 중, 갑자기 긴급 버그 수정 요청이 들어와 급히 다른 브랜치로 전환해야 할 때가 있습니다. 문제는 아직 완성되지 않아 커밋하기 곤란한 로컬 변경사항들이 남아있다는 점입니다.

이러한 상황에서는 Git이 커밋되지 않은 변경사항 때문에 브랜치 전환을 막아 개발 흐름이 끊기기 쉽습니다. 이 글에서는 Git의 `stash` 기능을 활용하여 이러한 미완성 변경사항들을 안전하게 임시 저장하고 필요할 때 다시 복구하는 실전 방법을 상세히 안내합니다.

git stash, 왜 필요할까요?

개발 작업을 진행하다 보면 현재 하던 일을 잠시 멈추고 다른 브랜치로 이동해야 할 때가 빈번합니다. 특히 새로운 기능을 만들던 중 긴급 버그 수정 요청이 들어오는 경우가 대표적입니다. 이때 로컬에 반영된 변경사항들이 아직 커밋하기 곤란한 미완성 상태라면 난감해집니다. Git은 커밋되지 않은 변경사항이 있는 경우 다른 브랜치로의 전환을 허용하지 않기 때문입니다.

바로 이 순간, `git stash` 명령어가 빛을 발합니다. `git stash`는 현재 작업 중인 변경사항들(수정된 파일 및 스테이징된 파일)을 임시 저장 공간에 보관하여, 작업 디렉토리를 깨끗하게 만들어줍니다. 이는 마치 작업대 위를 정리하고 다른 작업을 시작한 뒤, 나중에 다시 원래 작업으로 돌아와 정돈된 작업물을 그대로 펼쳐보는 것과 같습니다. Git 히스토리에 불필요한 커밋을 남기지 않고 유연하게 브랜치를 오갈 수 있게 되는 핵심적인 기능입니다.

Photo by Startup Stock Photos on Pexels

git stash 기본 사용법: 변경사항 저장하고 복구하기

`git stash`의 가장 기본적인 사용법은 현재 작업 중인 변경사항을 임시 저장소에 넣고, 필요할 때 다시 꺼내오는 과정으로 진행됩니다. 이 과정은 크게 세 단계로 나누어 볼 수 있습니다.

`git stash` 명령은 기본적으로 수정된(Modified) 파일과 스테이징된(Staged) 파일들을 저장합니다. `git stash save “메시지”`와 같이 메시지를 함께 기록하여 어떤 작업에 대한 stash인지 명확히 할 수 있습니다. 이렇게 stash에 저장된 변경사항은 `git stash list` 명령으로 언제든지 확인할 수 있으며, 각각의 stash는 고유한 인덱스(`stash@{0}`, `stash@{1}` 등)를 가집니다.

변경사항을 복구할 때는 `git stash apply` 또는 `git stash pop`을 사용합니다. `apply`는 stash 내용을 작업 디렉토리에 적용하고 stash 목록에는 그대로 남겨두며, `pop`은 적용과 동시에 해당 stash를 목록에서 제거합니다. 일반적으로 한 번만 적용할 변경사항이라면 `pop`을, 여러 번 적용하거나 백업용으로 남겨두고 싶다면 `apply`를 사용하는 것이 효율적입니다. 다음은 `git stash`의 실전 예제입니다.

1. 작업 변경사항 생성 — `main` 브랜치에서 `feature/new-login` 브랜치를 생성하고, 로그인 관련 파일을 수정합니다. 이때, 아직 커밋하기 애매한 미완성 상태입니다.
2. 변경사항 임시 저장 — 긴급 버그 수정 요청이 들어와 `git stash save “로그인 기능 개발 중 임시 저장”` 명령으로 현재 변경사항을 임시 저장합니다. 이제 `git status`를 확인하면 작업 디렉토리가 깨끗해진 것을 볼 수 있습니다.
3. 긴급 버그 수정 및 커밋 — `main` 브랜치로 전환 후 긴급 버그 수정 브랜치를 생성하여 버그를 수정하고 커밋합니다. 이후 다시 `feature/new-login` 브랜치로 돌아옵니다.
4. 원래 작업으로 복귀 — `git stash pop` 명령으로 이전에 저장했던 로그인 기능 개발 변경사항을 다시 불러와 작업을 이어갑니다.

Photo by cottonbro studio on Pexels

여러 개의 stash 관리 및 선택적 적용

`git stash`를 여러 번 사용하다 보면, 임시 저장된 항목들이 쌓이게 됩니다. 이때, 어떤 stash가 어떤 작업에 대한 것인지 명확히 구분하고 필요에 따라 원하는 stash를 선택적으로 적용하는 것이 중요합니다. `git stash list` 명령을 통해 현재까지 저장된 모든 stash 목록을 확인할 수 있습니다.

각각의 stash 항목은 `stash@{숫자}` 형태로 고유한 인덱스를 가집니다. 가장 최근에 저장된 stash는 `stash@{0}`이며, 그 다음은 `stash@{1}` 순으로 부여됩니다. 특정 stash를 복구하고 싶다면, `git stash apply stash@{1}` 또는 `git stash pop stash@{2}`와 같이 인덱스를 지정하여 명령을 실행할 수 있습니다. 예를 들어, 두 번째로 저장했던 stash를 적용하고 싶다면 `git stash apply stash@{1}`을 사용합니다.

더 이상 필요 없는 stash는 `git stash drop stash@{n}` 명령으로 삭제할 수 있습니다. 예를 들어, `stash@{0}`을 삭제하려면 `git stash drop stash@{0}`을 입력합니다. 모든 stash를 한 번에 지우려면 `git stash clear` 명령을 사용합니다. 불필요한 stash를 주기적으로 정리하는 것은 Git 저장소를 깔끔하게 관리하는 데 큰 도움이 됩니다.

Photo by Adonis Arias on Pexels

git stash 고급 활용 팁

`git stash`는 단순히 변경사항을 임시 저장하는 것을 넘어, 몇 가지 유용한 옵션을 통해 더 강력하게 활용될 수 있습니다. 특히 새로 생성했지만 아직 Git의 추적을 받지 않는(Untracked) 파일이나, 특정 파일만 stash하고 싶을 때 유용합니다. 기본 `git stash` 명령은 Untracked 파일을 저장하지 않습니다.

만약 Untracked 파일까지 함께 저장하고 싶다면, `-u` 옵션을 추가합니다. 예를 들어, `git stash -u` 또는 `git stash save -u “Untracked 파일 포함 stash”`와 같이 사용하면 됩니다. 이는 새 기능을 개발하면서 임시로 생성된 파일들이나 빌드 결과물 등 추적되지 않는 파일들을 한 번에 정리하고 싶을 때 매우 편리합니다. 덕분에 작업 디렉토리를 100% 깔끔한 상태로 만들 수 있습니다.

또한, 작업 디렉토리 내의 모든 변경사항이 아닌 특정 파일이나 특정 변경 내용만 stash하고 싶을 때도 있습니다. 이때는 먼저 `git add -p` 명령을 사용하여 원하는 변경사항만 선택적으로 스테이징 영역에 올린 다음, `git stash –staged` 명령을 사용합니다. 이렇게 하면 스테이징된 변경사항만 stash에 저장되고, 스테이징되지 않은 변경사항은 작업 디렉토리에 그대로 남습니다. 이 방법은 전체를 저장하기엔 부담스럽고, 일부 변경사항만 잠시 빼두고 싶을 때 활용도가 높습니다.