Git 에서 'error: untracked working tree files would be overwritten by checkout' 오류 처리 방법

소개

Git 은 현대 소프트웨어 개발에 필수적인 강력한 버전 관리 시스템입니다. Git 을 사용하다 보면 "error: untracked working tree files would be overwritten by checkout"와 같은 오류 메시지를 접할 수 있습니다. 이 오류는 브랜치를 전환하려고 할 때, Git 이 현재 작업 디렉토리에 있는 아직 Git 으로 추적되지 않은 파일들을 덮어쓰게 된다는 것을 감지했을 때 발생합니다. 이 안전 기능은 의도치 않은 데이터 손실을 방지합니다.

이 실습에서는 이 흔한 오류의 원인, 충돌하는 파일을 식별하는 방법, 그리고 이를 해결하는 여러 가지 방법을 배우게 됩니다. 이 튜토리얼을 마치면 Git 워크플로우를 더욱 효과적으로 관리하고 이 오류를 자신 있게 처리할 수 있게 될 것입니다.

체크아웃 오류 재현하기

오류를 수정하는 방법을 이해하기 위해 먼저 오류를 재현해 보겠습니다. 이렇게 하면 Git 이 왜 충돌을 보고하는지 명확히 알 수 있습니다. 저희의 설정 스크립트는 이미 두 개의 브랜치 (main 및 feature-branch) 를 가진 Git 저장소를 생성했습니다. feature-branch에는 현재 main 브랜치에서 로컬로 생성할 파일이 포함되어 있습니다.

먼저 프로젝트 디렉토리로 이동합니다. 이 실습의 모든 명령어는 이 디렉토리에서 실행됩니다.

cd ~/project/git-checkout-demo

모든 것이 깨끗한지 확인하기 위해 현재 저장소의 상태를 확인해 보겠습니다.

git status

출력은 다음과 같아야 합니다.

On branch main
nothing to commit, working tree clean

이는 우리가 main 브랜치에 있으며 보류 중인 변경 사항이 없음을 확인합니다. 이제 사용 가능한 브랜치를 나열해 보겠습니다.

git branch

두 개의 브랜치가 표시되며, *는 현재 브랜치를 나타냅니다.

  feature-branch
* main

이제 충돌을 생성해 보겠습니다. 현재 작업 디렉토리에 feature.md라는 새 파일을 생성할 것입니다. 이 파일은 현재 main 브랜치에서 Git 에 의해 "추적되지 않음" 상태이지만, feature-branch에서는 동일한 이름의 파일이 이미 존재하며 추적되고 있습니다.

echo "## My local changes to feature documentation" > feature.md

새로운 추적되지 않은 파일을 보기 위해 상태를 다시 확인합니다.

git status

출력은 이제 feature.md를 추적되지 않은 파일로 표시합니다.

On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
	feature.md

nothing added to commit but untracked files present (use "git add" to track)

마지막으로 feature-branch로 전환해 보겠습니다.

git checkout feature-branch

이 명령어는 실패하고 우리가 연구하고 있는 오류를 생성합니다.

error: The following untracked working tree files would be overwritten by checkout:
	feature.md
Please move or remove them before you switch branches.
Aborting

Git 은 feature-branch의 버전으로 인해 로컬의 추적되지 않은 feature.md 파일이 덮어쓰이는 것을 방지하기 위해 체크아웃을 중단했습니다. 다음 단계에서는 이를 해결하는 다양한 방법을 살펴보겠습니다.

git stash를 사용한 충돌 해결

이 오류를 해결하는 가장 안전하고 일반적인 방법 중 하나는 git stash를 사용하는 것입니다. 이 명령어는 로컬 수정 사항 (스테이징된 파일과 스테이징되지 않은 파일 모두) 을 임시로 저장하고 작업 디렉토리를 마지막 커밋과 일치하도록 되돌립니다. 이를 통해 자유롭게 브랜치를 전환할 수 있습니다.

현재 우리는 추적되지 않은 feature.md 파일로 인해 충돌이 발생하는 main 브랜치에 있습니다.

추적되지 않은 파일을 스태시하려면 --include-untracked (또는 -u) 옵션을 사용해야 합니다.

git stash push --include-untracked

확인 메시지가 표시됩니다.

Saved working directory and index state WIP on main: <commit_hash> Initial commit with README

이제 저장소의 상태를 다시 확인합니다.

git status

작업 트리가 깨끗하고 추적되지 않은 파일이 사라졌습니다.

On branch main
nothing to commit, working tree clean

작업 디렉토리가 깨끗해졌으므로 이제 오류 없이 feature-branch로 전환할 수 있습니다.

git checkout feature-branch

명령어가 성공합니다.

Switched to branch 'feature-branch'

이제 feature-branch에 있습니다. feature.md를 검사하면 이 브랜치에 속한 버전을 볼 수 있습니다.

cat feature.md

## Official Feature Documentation

로컬 변경 사항은 스태시에 안전하게 저장되었습니다. 이를 다시 가져오려면 main 브랜치로 다시 전환하고 스태시를 적용하면 됩니다.

git checkout main
git stash pop

git stash pop 명령어는 스태시된 변경 사항을 다시 적용하고 스태시 목록에서 제거합니다. 이제 feature.md 파일이 작업 디렉토리로 돌아왔습니다.

다음 단계로, 충돌 상태로 돌아갔는지 확인합니다. git stash pop 명령어를 따랐다면 이미 해당 상태입니다.

git clean을 사용한 충돌 해결

충돌을 해결하는 또 다른 방법은 추적되지 않은 파일을 삭제하는 것입니다. 이 방법은 추적되지 않은 파일이 필요 없다고 확신할 때만 적합합니다. git clean 명령어가 이 목적으로 사용됩니다.

경고: 이 명령어는 파일을 영구적으로 삭제하므로 주의해서 사용하십시오.

먼저, 추적되지 않은 feature.md 파일로 인해 main 브랜치에서 충돌 상태인지 확인합니다.

cd ~/project/git-checkout-demo
git checkout main
## feature.md가 존재하지 않으면 다시 생성합니다.
if [ ! -f "feature.md" ]; then echo "## My local changes" > feature.md; fi
git status

무언가를 삭제하기 전에 -n 플래그를 사용하여 "드라이 런 (dry run)"을 수행하는 것이 가장 좋습니다. 이렇게 하면 실제로 파일을 삭제하지 않고 삭제될 파일을 보여줍니다.

git clean -n

출력은 제거될 파일 목록을 표시합니다.

Would remove feature.md

이 파일들을 삭제하려는 것을 확인했다면, -f (force) 플래그를 사용하여 명령어를 다시 실행할 수 있습니다.

git clean -f

Git 이 제거를 확인합니다.

Removing feature.md

추적되지 않은 파일이 사라졌으므로 작업 디렉토리가 깨끗해졌고 문제 없이 브랜치를 전환할 수 있습니다.

git checkout feature-branch

체크아웃이 성공합니다.

Switched to branch 'feature-branch'

이 방법은 빠르지만 파괴적입니다. 이전 단계의 git stash 방법은 작업을 보존하기 때문에 일반적으로 더 안전합니다.

파일을 추적하고 모범 사례를 통해 충돌 해결하기

때로는 추적되지 않은 파일이 폐기할 수 있는 것이 아니라 보존하고 싶은 작업일 수 있습니다. 이 경우 올바른 접근 방식은 파일을 커밋하여 Git 의 추적 시스템에 추가하는 것입니다. 이 섹션에서는 이 오류가 처음부터 발생하지 않도록 하는 모범 사례도 다룹니다.

먼저 main 브랜치로 돌아가 충돌 파일을 다시 생성해 보겠습니다.

cd ~/project/git-checkout-demo
git checkout main
echo "## My local changes to feature documentation" > feature.md

방법: 파일 추적하기

추적되지 않은 파일이 중요하다면 현재 브랜치에 커밋해야 합니다.

1. 파일을 스테이징 영역에 추가합니다.

   git add feature.md

2. 스테이징된 파일을 커밋합니다.

   git commit -m "Add local version of feature.md"

이제 변경 사항이 main 브랜치에 안전하게 커밋되었으므로 Git 이 전환을 처리할 수 있습니다. feature-branch를 체크아웃하면 Git 은 단순히 해당 브랜치의 버전으로 작업 공간 파일을 대체합니다.

git checkout feature-branch

체크아웃이 성공합니다. 커밋된 변경 사항은 main 브랜치의 히스토리에 안전하게 보관됩니다.

모범 사례: .gitignore 사용하기

특정 파일 (로그, 빌드 아티팩트 또는 환경 파일 등) 이 추적되지 않도록 하려면 .gitignore 파일을 사용해야 합니다. Git 은 .gitignore의 패턴과 일치하는 모든 파일 또는 디렉토리를 무시하여 충돌하는 추적되지 않은 파일이 되는 것을 방지합니다.

모든 .log 파일을 무시하도록 .gitignore 파일을 만들어 보겠습니다.

## .gitignore 파일을 추가하기 위해 main으로 다시 전환합니다.
git checkout main

## .gitignore 파일을 생성합니다.
echo "*.log" > .gitignore

이제 로그 파일을 생성합니다.

touch app.log

상태를 확인합니다.

git status

app.log가 추적되지 않은 파일로 나타나지 않는 것을 확인할 수 있습니다. 그러나 .gitignore 파일 자체는 추적되지 않습니다.

On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
	.gitignore

nothing added to commit but untracked files present (use "git add" to track)

규칙이 프로젝트 전체에 공유되도록 항상 .gitignore 파일을 커밋해야 합니다.

git add .gitignore
git commit -m "Add .gitignore to ignore log files"

자주 커밋하고 .gitignore를 효과적으로 사용하면 이 체크아웃 오류가 발생할 가능성을 크게 줄일 수 있습니다.

요약

이 실습에서는 Git 에서 "error: untracked working tree files would be overwritten by checkout" 오류를 진단하고 해결하는 방법을 배웠습니다.

다음과 같은 작업을 수행했습니다.

1. 오류 재현: 오류를 유발하는 시나리오를 성공적으로 생성하여 원인을 명확하게 이해했습니다.
2. git stash로 해결: 추적되지 않은 파일을 임시로 저장하기 위해 git stash를 사용하는 방법을 배웠으며, 작업 내용을 잃지 않고 안전하게 브랜치를 전환할 수 있었습니다.
3. git clean으로 해결: 더 이상 필요하지 않은 추적되지 않은 파일을 제거하기 위해 git clean을 사용하는 방법을 배웠으며, 실수를 방지하기 위해 먼저 드라이 런을 수행했습니다.
4. 파일 추적으로 해결: 보존하려는 작업에 대한 올바른 접근 방식인 추적되지 않은 파일을 커밋하여 문제를 해결하는 방법을 배웠습니다.
5. 모범 사례 학습: 임시 파일이나 빌드 관련 파일이 충돌을 일으키는 것을 방지하기 위해 .gitignore 파일을 사용하는 방법을 배웠습니다.

이러한 기술을 숙달하면 더 깨끗하고 효율적인 Git 워크플로를 유지하고 개발자가 직면하는 가장 일반적인 문제 중 하나를 자신 있게 처리할 수 있습니다.