Dream of E&C - Wiki

이 문서는 읽기 전용입니다. 원본을 볼 수는 있지만 바꿀 수는 없습니다. 문제가 있다고 생각하면 관리자에게 문의하세요.
====== Git/GitHub 문제 해결 가이드 - 막혔을 때 이렇게 해결하세요! ======

**Git/GitHub 사용 중 문제가 생겼나요?** 😰 걱정하지 마세요! 모든 개발자가 겪는 일반적인 문제들입니다. 이 가이드는 초보자도 쉽게 따라할 수 있도록 단계별로 문제 해결 방법을 설명합니다. 차근차근 따라해보세요!


----
===== 1. 🆘 문제 해결 기본 원칙 =====
==== 1) 당황하지 마세요! ====
  - 🔒 **Git은 안전합니다**: 거의 모든 상황에서 데이터를 복구할 수 있습니다
  - 📚 **기록이 남습니다**: Git은 모든 변경사항을 기록하므로 되돌릴 수 있습니다
  - 🤝 **도움을 받을 수 있습니다**: 전 세계 개발자들이 같은 문제를 겪고 해결했습니다

----
==== 2) 문제 해결 순서 ====
  - **상황 파악하기**: 정확히 무엇이 문제인지 확인
  - **오류 메시지 읽기**: 오류 메시지에 해결 방법이 있는 경우가 많음
  - **상태 확인하기**: ''git status''로 현재 상태 확인
  - **단계별 해결**: 한 번에 하나씩 차근차근 해결

===== 2. 🚨 가장 자주 발생하는 문제들 =====
----
==== 1) 커밋 메시지를 잘못 작성했을 때 ====

**문제 상황:**

<file bash>
git commit -m "ㅇㅇ"  # 이런 식으로 대충 작성했을 때
</file>

**해결 방법:**

**방법 1: 아직 push하지 않은 경우 (가장 쉬움)**

<file bash>
# 마지막 커밋 메시지 수정
git commit --amend -m "로그인 기능 구현 완료"

# 결과 확인
git log --oneline -1
</file>

**방법 2: 이미 push한 경우**

<file bash>
# 주의: 이 방법은 혼자 작업할 때만 사용하세요!
git commit --amend -m "로그인 기능 구현 완료"
git push --force-with-lease origin main
</file>

**💡 예방법:**
  - 커밋 메시지를 의미있게 작성하는 습관 기르기
  - 커밋 전에 ''git status''로 한 번 더 확인하기

----
==== 2) 잘못된 파일을 커밋했을 때 ====

**문제 상황:**

<file bash>
git add .
git commit -m "기능 추가"
# 이후에 비밀번호 파일이나 불필요한 파일이 포함되었다는 것을 발견
</file>

**해결 방법:**

**방법 1: 아직 push하지 않은 경우**

<file bash>
# 마지막 커밋 취소 (변경사항은 유지)
git reset --soft HEAD~1

# 문제 파일 제거
git reset HEAD password.txt
rm password.txt

# 다시 커밋
git add .
git commit -m "기능 추가 (비밀번호 파일 제외)"
</file>

**방법 2: 이미 push한 경우**

<file bash>
# 문제 파일을 Git에서 제거 (파일은 유지)
git rm --cached password.txt

# .gitignore에 추가
echo "password.txt" >> .gitignore

# 커밋
git add .
git commit -m "비밀번호 파일 제거 및 .gitignore 추가"
git push origin main
</file>

**💡 예방법:**
  - %% .gitignore %% 파일을 미리 설정하기
  - ''git add .'' 대신 ''git add 파일명''으로 하나씩 추가하기

----
==== 3) Push가 거부될 때 ====

**문제 상황:**

<file>
! [rejected] main -> main (non-fast-forward)
error: failed to push some refs to 'https://github.com/username/repository.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
</file>

**원인:** GitHub에 내가 모르는 새로운 커밋이 있음 (다른 컴퓨터에서 작업했거나 팀원이 작업한 경우)

**해결 방법:**

**1단계: 상황 확인**

<file bash>
# 현재 상태 확인
git status

# 원격 저장소 정보 업데이트
git fetch origin

# 차이점 확인
git log --oneline origin/main..HEAD  # 내가 추가한 커밋들
git log --oneline HEAD..origin/main  # 원격에 있는 새로운 커밋들
</file>

**2단계: 최신 코드 받아오기**

<file bash>
# 원격 저장소의 최신 코드 받아오기
git pull origin main

# 충돌이 없으면 자동으로 병합됨
# 충돌이 있으면 해결 후 커밋
</file>

**3단계: 다시 업로드**

<file bash>
git push origin main
</file>

**💡 예방법:**
  - 작업 시작 전 항상 ''git pull origin main'' 실행하기
  - 자주 push하여 충돌 가능성 줄이기

----
==== 4) 브랜치 이동 시 "변경사항이 있다" 오류 ====

**문제 상황:**

<file>
error: Your local changes to the following files would be overwritten by checkout:
	index.html
Please commit your changes or stash them before you switch branches.
</file>

**원인:** 현재 브랜치에서 수정한 파일이 있는데 커밋하지 않고 다른 브랜치로 이동하려고 할 때

**해결 방법:**

**방법 1: 변경사항을 커밋하기 (추천)**

<file bash>
# 현재 작업 내용 확인
git status
git diff

# 변경사항 커밋
git add .
git commit -m "작업 중인 내용 임시 저장"

# 이제 브랜치 이동 가능
git switch other-branch
</file>

**방법 2: 임시 저장 (stash) 사용하기**

<file bash>
# 변경사항 임시 저장
git stash

# 브랜치 이동
git switch other-branch

# 원래 브랜치로 돌아와서 작업 복원
git switch original-branch
git stash pop
</file>

**방법 3: 변경사항 버리기 (주의!)**

<file bash>
# 주의: 이 방법은 변경사항을 완전히 삭제합니다!
git checkout -- .

# 이제 브랜치 이동 가능
git switch other-branch
</file>

----
==== 5) 머지 충돌 (Merge Conflict) ====

**문제 상황:**

<file>
Auto-merging index.html
CONFLICT (content): Merge conflict in index.html
Automatic merge failed; fix conflicts and then commit the result.
</file>

**원인:** 같은 파일의 같은 부분을 서로 다르게 수정했을 때

**해결 방법:**

**1단계: 충돌 파일 확인**

<file bash>
# 충돌 상태 확인
git status

# 충돌 파일 내용 보기
cat index.html
</file>

**2단계: 충돌 마커 이해하기**

<file html>
<!DOCTYPE html>
<html>
<head>
<<<<<<< HEAD
    <title>메인 페이지</title>
=======
    <title>로그인 페이지</title>
>>>>>>> feature-login
</head>
</html>
</file>

**💡 충돌 마커 의미:**
  - %%<<<<<<< HEAD%%: 현재 브랜치의 내용
  - %%=======%%: 구분선
  - %%>>>>>>> feature-login%%: 병합하려는 브랜치의 내용

**3단계: 충돌 해결**

<file bash>
# 에디터로 파일 수정
nano index.html

# 충돌 마커 제거하고 원하는 내용으로 수정
# 예: <title>메인 페이지 - 로그인</title>
</file>

**4단계: 병합 완료**

<file bash>
# 수정된 파일 추가
git add index.html

# 병합 커밋 생성
git commit -m "Merge conflict 해결: 제목 통합"

# 결과 확인
git log --oneline --graph
</file>

===== 3. 🔐 인증 관련 문제 =====
----
==== 1) GitHub 인증 실패 ====

**문제 상황:**

<file>
remote: Support for password authentication was removed on August 13, 2021.
remote: Please use a personal access token instead.
fatal: Authentication failed for 'https://github.com/username/repository.git/'
</file>

**원인:** GitHub가 2021년부터 비밀번호 인증 중단함

**해결 방법:**

**방법 1: Personal Access Token 사용**

**1단계: 토큰 생성**
  - GitHub 로그인 → Settings → Developer settings → Personal access tokens
  - ''Generate new token (classic)'' 클릭
  - 토큰 이름 입력 (예: ''내 컴퓨터'')
  - 권한 선택 (repo 체크)
  - ''Generate token'' 클릭
  - 생성된 토큰 복사 (한 번만 보여줌!)

**2단계: 토큰 사용**

<file bash>
# Git 명령어 실행 시 비밀번호 대신 토큰 입력
git push origin main
# Username: your-github-username
# Password: [여기에 토큰 입력]
</file>

**방법 2: SSH 키 사용 (더 안전)**

**1단계: SSH 키 생성**

<file bash>
# SSH 키 생성
ssh-keygen -t ed25519 -C ''your-email@example.com''

# 기본 설정으로 Enter 3번 입력
# 키 파일 위치: ~/.ssh/id_ed25519
</file>

**2단계: SSH 키 GitHub에 등록**

<file bash>
# 공개 키 내용 복사
cat ~/.ssh/id_ed25519.pub
</file>

  - GitHub → Settings → SSH and GPG keys
  - ''New SSH key'' 클릭
  - 제목 입력하고 키 내용 붙여넣기
  - ''Add SSH key'' 클릭

**3단계: 원격 저장소 URL 변경**

<file bash>
# HTTPS에서 SSH로 변경
git remote set-url origin git@github.com:username/repository.git

# 확인
git remote -v
</file>
===== 4. 🗂️ 파일 관리 문제 =====
----
==== 1) 파일을 실수로 삭제했을 때 ====

**문제 상황:**

<file bash>
rm important-file.txt  # 실수로 중요한 파일 삭제
</file>

**해결 방법:**

**방법 1: 아직 커밋하지 않은 경우**

<file bash>
# 마지막 커밋 상태로 파일 복원
git checkout -- important-file.txt

# 또는 특정 커밋에서 복원
git checkout HEAD -- important-file.txt
</file>

**방법 2: 이미 삭제를 커밋한 경우**

<file bash>
# 파일이 삭제된 커밋 찾기
git log --oneline -- important-file.txt

# 삭제되기 직전 커밋에서 파일 복원
git checkout commit-hash -- important-file.txt

# 복원 후 커밋
git add important-file.txt
git commit -m "중요한 파일 복원"
</file>

----
==== 2) 큰 파일 업로드 오류 ====

**문제 상황:**

<file>
remote: error: File large-file.zip is 120.00 MB; this exceeds GitHub's file size limit of 100.00 MB
remote: error: See https://docs.github.com/articles/about-git-large-files for more information.
</file>

**원인:** GitHub는 100MB 이상의 파일 업로드를 제한함

**해결 방법:**

**방법 1: 파일 제거**

<file bash>
# 큰 파일을 .gitignore에 추가
echo "large-file.zip" >> .gitignore

# 이미 추가된 파일 제거
git rm --cached large-file.zip

# 커밋
git add .gitignore
git commit -m "큰 파일 제거 및 .gitignore 추가"
git push origin main
</file>

**방법 2: Git LFS 사용**

<file bash>
# Git LFS 설치 (한 번만)
git lfs install

# 큰 파일 타입을 LFS로 관리
git lfs track "*.zip"

# .gitattributes 파일 커밋
git add .gitattributes
git commit -m "Git LFS 설정 추가"

# 큰 파일 추가
git add large-file.zip
git commit -m "큰 파일 추가 (LFS 사용)"
git push origin main
</file>

===== 5. 🔄 히스토리 관리 문제 =====
----
==== 1) 커밋을 너무 많이 만들었을 때 ====

**문제 상황:**

<file bash>
git log --oneline
# a1b2c3d 오타 수정
# e4f5g6h 또 오타 수정
# i7j8k9l 또또 오타 수정
# m1n2o3p 기능 추가
</file>

**해결 방법: 여러 커밋을 하나로 합치기 (Squash)**

**방법 1: Interactive Rebase 사용**

<file bash>
# 최근 4개 커밋을 하나로 합치기
git rebase -i HEAD~4

# 에디터가 열리면:
# pick m1n2o3p 기능 추가
# squash i7j8k9l 또또 오타 수정
# squash e4f5g6h 또 오타 수정
# squash a1b2c3d 오타 수정

# 저장하고 닫으면 커밋 메시지 편집 화면이 나타남
# 원하는 메시지로 수정 후 저장
</file>

**방법 2: Soft Reset 사용**

<file bash>
# 최근 4개 커밋을 취소하되 변경사항은 유지
git reset --soft HEAD~4

# 모든 변경사항을 하나의 커밋으로 만들기
git commit -m "기능 추가 및 오타 수정"
</file>

**⚠️ 주의사항:**
  - 이미 push한 커밋은 수정하지 마세요 (팀 작업 시)
  - 혼자 작업할 때만 사용하세요

----
==== 2) 잘못된 브랜치에서 작업했을 때 ====

**문제 상황:**

<file bash>
# main 브랜치에서 작업했는데 feature 브랜치에서 했어야 했을 때
git branch
# * main  ← 현재 main 브랜치
git log --oneline -3
# a1b2c3d 새 기능 추가  ← 이 커밋이 잘못된 브랜치에 있음
</file>

**해결 방법:**

**1단계: 새 브랜치 생성**

<file bash>
# 현재 위치에서 새 브랜치 생성
git branch feature-new-function

# 또는 생성과 동시에 이동
git checkout -b feature-new-function
</file>

**2단계: main 브랜치 되돌리기**

<file bash>
# main 브랜치로 이동
git checkout main

# 잘못된 커밋 되돌리기
git reset --hard HEAD~1

# 확인
git log --oneline -3
</file>

**3단계: 새 브랜치에서 작업 계속**

<file bash>
# 새 브랜치로 이동
git checkout feature-new-function

# 작업 계속...
</file>

===== 6. 🛠️ 고급 복구 기법 =====
----
==== 1) 실수로 브랜치를 삭제했을 때 ====

**문제 상황:**

<file bash>
git branch -D feature-important  # 실수로 중요한 브랜치 삭제
</file>

**해결 방법:**

**1단계: 삭제된 브랜치의 커밋 해시 찾기**

<file bash>
# reflog에서 삭제된 브랜치의 마지막 커밋 찾기
git reflog

# 결과 예시:
# a1b2c3d HEAD@{0}: checkout: moving from feature-important to main
# e4f5g6h HEAD@{1}: commit: 중요한 기능 완성
# ...
</file>

**2단계: 브랜치 복원**

<file bash>
# 삭제된 브랜치 복원
git checkout -b feature-important e4f5g6h

# 확인
git log --oneline
</file>

----
==== 2) 잘못된 파일 내용을 커밋했을 때 ====

**문제 상황:**

<file bash>
# 중요한 파일에 잘못된 내용을 작성하고 커밋함
git log --oneline -1
# a1b2c3d 설정 파일 업데이트  ← 이 커밋에서 파일 내용이 잘못됨
</file>

**해결 방법:**

**방법 1: 특정 파일만 이전 상태로 복원**

<file bash>
# 2번 전 커밋에서 해당 파일만 복원
git checkout HEAD~2 -- config.json

# 복원 후 커밋
git add config.json
git commit -m "설정 파일 복원"
</file>

**방법 2: 커밋 되돌리기**

<file bash>
# 잘못된 커밋을 되돌리는 새 커밋 생성
git revert HEAD

# 또는 특정 커밋 되돌리기
git revert a1b2c3d
</file>

===== 7. 🔍 문제 진단 도구 =====
----
==== 1) 유용한 명령어들 ====

**현재 상태 확인**

<file bash>
# 기본 상태 확인
git status

# 상세 상태 확인
git status -v

# 간단한 상태 확인
git status -s
</file>

**히스토리 확인**

<file bash>
# 커밋 히스토리
git log --oneline --graph

# 특정 파일의 히스토리
git log --oneline -- filename.txt

# 모든 참조 히스토리 (삭제된 커밋도 포함)
git reflog
</file>

**차이점 확인**

<file bash>
# 작업 디렉토리와 스테이징 영역 차이
git diff

# 스테이징 영역과 마지막 커밋 차이
git diff --cached

# 두 커밋 간 차이
git diff commit1 commit2
</file>

===== 8. 🆘 응급 상황 대처법 =====
----
==== 1) "모든 것이 망가졌을 때" ====

**상황:** 무엇을 했는지 모르겠는데 모든 것이 이상해졌을 때

**해결 방법:**

**1단계: 당황하지 말고 현재 상태 파악**

<file bash>
# 현재 상태 확인
git status

# 현재 브랜치 확인
git branch

# 최근 커밋 확인
git log --oneline -5

# 모든 참조 히스토리 확인
git reflog
</file>

**2단계: 안전한 상태로 복원**

<file bash>
# 작업 디렉토리의 모든 변경사항 버리기
git checkout -- .

# 스테이징 영역 정리
git reset HEAD

# 마지막 커밋 상태로 완전히 복원
git reset --hard HEAD
</file>

**3단계: 필요시 특정 시점으로 복원**

<file bash>
# 특정 커밋으로 완전히 되돌리기 (주의!)
git reset --hard commit-hash

# 또는 안전한 되돌리기
git revert commit-hash
</file>

===== 9. 📚 도움 받는 방법 =====
----
==== 1) Git 내장 도움말 ====

<file bash>
# 명령어 도움말 보기
git help status
git help commit
git help merge

# 간단한 도움말
git status --help
git commit --help
</file>

----
==== 2) 온라인 리소스 ====

**공식 문서:**
  - Git 공식 문서: https://git-scm.com/doc
  - GitHub 도움말: https://docs.github.com/

**커뮤니티:**
  - Stack Overflow: ''git'' 태그로 검색
  - GitHub Community: https://github.community/

**한국어 자료:**
  - 생활코딩 Git 강의
  - Git 공식 문서 한국어 번역

----
==== 3) 오류 메시지 검색 팁 ====

<file bash>
# 오류 메시지를 그대로 구글에 검색
"error: Your local changes to the following files would be overwritten"

# "git" 키워드 추가
git "CONFLICT (content): Merge conflict"

# 해결 방법도 함께 검색
git merge conflict how to resolve
</file>

===== 10. 💡 문제 예방 팁 =====
----
==== 1) 좋은 습관 기르기 ====

**1. 자주 상태 확인하기**

<file bash>
# 명령어 실행 전후로 항상 확인
git status
</file>

**2. 작은 단위로 자주 커밋하기**

<file bash>
# 큰 변경사항을 한 번에 커밋하지 말고 작은 단위로
git add specific-file.txt
git commit -m "특정 기능 추가"
</file>

**3. 의미있는 커밋 메시지 작성하기**

<file bash>
# 나중에 봐도 이해할 수 있는 메시지
git commit -m "사용자 로그인 기능 구현"
</file>

**4. 중요한 작업 전 백업하기**

<file bash>
# 중요한 브랜치 백업
git branch backup-main main

# 또는 태그로 백업
git tag backup-before-merge
</file>

**5. .gitignore 파일 활용하기**

<file bash>
# 프로젝트 시작 시 .gitignore 설정
echo "*.log" >> .gitignore
echo "node_modules/" >> .gitignore
echo ".env" >> .gitignore
</file>

===== 11. 🎓 마무리 =====

**축하합니다! 🎉 이제 Git/GitHub 문제 해결 능력을 갖추셨습니다!**

**기억해야 할 핵심 원칙:**
  - 🔒 **Git은 안전합니다**: 거의 모든 상황에서 복구 가능
  - 📖 **오류 메시지를 읽어보세요**: 해결 방법이 있는 경우가 많음
  - 🔍 ''git status''를 자주 사용하세요!: 현재 상태 파악이 중요
  - 🤝 **도움을 요청하세요**: 혼자 해결하려고 하지 마세요

**문제가 생겼을 때:**
  - 당황하지 말고 현재 상태 파악
  - 이 가이드에서 비슷한 상황 찾기
  - 단계별로 차근차근 해결
  - 해결되지 않으면 온라인 커뮤니티에 질문

**예방이 최선입니다:**
  - 자주 커밋하고 push하기
  - 중요한 작업 전 백업하기
  - %% .gitignore %% 파일 활용하기
  - 의미있는 커밋 메시지 작성하기

**이제 고급 팁을 배워서 더 효율적으로 Git을 사용해보세요!** 🌟

----

**이전:** [[wiki:it:github:branch_management|🌿 브랜치 관리]] | **다음:** [[wiki:it:github:advanced_tips|🚀 고급 팁과 트릭]] | **목록:** [[wiki:it:github:start|📋 전체 문서 목록]]