E: does not have a commit checked out fatal: adding files failed

dev_joo·2025년 4월 2일

git add .\some-folder\
error: 'some-folder/' does not have a commit checked out
fatal: adding files failed

디렉터리가 Git 저장소의 서브모듈(submodule)로 설정되어 있는데, 그 서브모듈이 제대로 초기화되지 않았거나 체크아웃되지 않아서 발생하는 문제
즉, 하나의 디렉터리 안에 다수의 Git 저장소 존재

서브모듈(Git Submodule) : 한 Git 저장소(repo) 안에서 다른 Git 저장소를 포함할 수 있도록 해주는 기능

해결

1. git 저장소 삭제 (서브모듈 사용 안할 때)

✅Linux/macOS 터미널에서.git 폴더 삭제

rm -rf .git

🔹 -r : 폴더 내부의 모든 파일과 하위 폴더를 삭제
🔹 -f : 삭제할 때 확인 없이 강제 실행

✅ PowerShell에서 .git 폴더 삭제

Remove-Item -Recurse -Force .git
🔹 -Recurse : 폴더 내부의 모든 파일과 하위 폴더를 삭제
🔹 -Force : 삭제할 때 확인 없이 강제 실행

✅ cmd(명령 프롬프트)에서 .git 폴더 삭제

rmdir /s /q .git
🔹 /s : 폴더와 그 안의 모든 내용을 삭제
🔹 /q : 삭제 확인 없이 진행

2. 올바른 서브모듈 설정

1️⃣ 서브모듈 추가

git submodule add <서브모듈_레포_URL> <디렉터리명>

git submodule add https://github.com/example/library.git libs/library
git commit -m "Added libs/library as a submodule"

✅ 결과: libs/library 폴더에 library 저장소가 추가됨
libs/library 폴더가 상위 프로젝트의 일부로 관리되지만, 독립적인 Git 저장소로 유지

2️⃣ 서브모듈이 있는 프로젝트를 처음 클론할 때

git clone --recurse-submodules <프로젝트_URL>

✅ --recurse-submodules 서브모듈까지 함께 가져옴
🚨 그냥 git clone만 하면 서브모듈 폴더는 비어 있음

3️⃣ (서브모듈 내부에서 실행) 서브모듈 안에서 관리

서브모듈은 독립적인 Git 저장소이므로, 폴더 안으로 들어가서 따로 작업할 수 있음

cd libs/library
git pull origin main   # 서브모듈을 메인저장소가 아닌 서브모듈저장소의 최신 상태로 업데이트

4️⃣ 서브모듈 변경 사항 != 메인 프로젝트 변경 사항

🚨 서브모듈 내부에서 변경 후, 원래 프로젝트에서 서브모듈 업데이트 기록을 커밋해야 함.

✅ 서브모듈은 독립적인 Git 저장소이므로, 서브모듈에서 commit하고 push해도 메인 저장소에는 자동으로 반영되지 않음 (메인 저장소에서는 서브모듈의 특정 커밋을 가리키는 방식으로 관리되기 때문)

git add libs/library
git commit -m "Update submodule to latest version"
git push origin main

5️⃣ (메인 저장소에서 실행) 서브모듈 초기화 및 업데이트

메인 저장소가 가리키는 서브모듈 커밋으로 이동

cd ..
git pull origin main  # 메인 저장소 최신 상태 가져오기
git submodule init   # 서브모듈 초기화: .gitmodules 파일에 있는 서브모듈 정보를 Git에 등록
git submodule update # 서브 모듈을 메인저장소가 가리키는 최신 버전으로 가져오기

6️⃣ 서브모듈 삭제

git submodule deinit -f libs/library #  Git이 서브모듈 관리 해제
git rm -r --cached libs/library # 메인 저장소에서 서브모듈 삭제
rm -rf .git/modules/libs/library # Git 내부 데이터 제거

rm -rf libs/library  # 실제 파일 삭제 (원하면 실행)

git add .gitmodules  # .gitmodules 변경 사항 추가
git commit -m "Completely removed submodule libs/library" # 서브모듈 삭제 반영

🎯 언제 서브모듈을 사용하면 좋을까?

✅ 공유 라이브러리를 관리할 때
✅ 큰 프로젝트에서 독립적인 모듈을 유지해야 할 때
✅ 다른 팀에서 개발한 코드베이스를 특정 버전으로 유지할 때

🚨 서브모듈 사용의 단점:

서브모듈을 업데이트할 때 따로 관리해야 함
서브모듈이 많아지면 관리가 복잡해질 수 있음

💡 👉 보통은 패키지 매니저(NPM, Maven, Pip 등)를 사용하지만 서브모듈이 꼭 필요한 경우가 있음

dev_joo

풀스택 연습생. 끈기있는 삽질로 무대에서 화려하게 데뷔할 예정 ❤️🔥