Dream of E&C - Wiki

사용자 도구

사이트 도구

추적: • Git/GitHub 문제 해결 가이드 - 막혔을 때 이렇게 해결하세요!
wiki:it:github:troubleshooting

목차

Git/GitHub 문제 해결 가이드 - 막혔을 때 이렇게 해결하세요!

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

1. 🆘 문제 해결 기본 원칙

1) 당황하지 마세요!

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

2) 문제 해결 순서

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

2. 🚨 가장 자주 발생하는 문제들

1) 커밋 메시지를 잘못 작성했을 때

문제 상황: 

git commit -m "ㅇㅇ"  # 이런 식으로 대충 작성했을 때

해결 방법:

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

# 마지막 커밋 메시지 수정
git commit --amend -m "로그인 기능 구현 완료"
 
# 결과 확인
git log --oneline -1

방법 2: 이미 push한 경우 

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

💡 예방법:

  1. 커밋 메시지를 의미있게 작성하는 습관 기르기
  2. 커밋 전에 git status로 한 번 더 확인하기

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

문제 상황: 

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

해결 방법:

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

# 마지막 커밋 취소 (변경사항은 유지)
git reset --soft HEAD~1
 
# 문제 파일 제거
git reset HEAD password.txt
rm password.txt
 
# 다시 커밋
git add .
git commit -m "기능 추가 (비밀번호 파일 제외)"

방법 2: 이미 push한 경우 

# 문제 파일을 Git에서 제거 (파일은 유지)
git rm --cached password.txt
 
# .gitignore에 추가
echo "password.txt" >> .gitignore
 
# 커밋
git add .
git commit -m "비밀번호 파일 제거 및 .gitignore 추가"
git push origin main

💡 예방법:

  1. .gitignore 파일을 미리 설정하기
  2. git add . 대신 git add 파일명으로 하나씩 추가하기

3) Push가 거부될 때

문제 상황: 

! [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.

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

해결 방법:

1단계: 상황 확인 

# 현재 상태 확인
git status
 
# 원격 저장소 정보 업데이트
git fetch origin
 
# 차이점 확인
git log --oneline origin/main..HEAD  # 내가 추가한 커밋들
git log --oneline HEAD..origin/main  # 원격에 있는 새로운 커밋들

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

# 원격 저장소의 최신 코드 받아오기
git pull origin main
 
# 충돌이 없으면 자동으로 병합됨
# 충돌이 있으면 해결 후 커밋

3단계: 다시 업로드 

git push origin main

💡 예방법:

  1. 작업 시작 전 항상 git pull origin main 실행하기
  2. 자주 push하여 충돌 가능성 줄이기

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

문제 상황: 

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.

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

해결 방법:

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

# 현재 작업 내용 확인
git status
git diff
 
# 변경사항 커밋
git add .
git commit -m "작업 중인 내용 임시 저장"
 
# 이제 브랜치 이동 가능
git switch other-branch

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

# 변경사항 임시 저장
git stash
 
# 브랜치 이동
git switch other-branch
 
# 원래 브랜치로 돌아와서 작업 복원
git switch original-branch
git stash pop

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

# 주의: 이 방법은 변경사항을 완전히 삭제합니다!
git checkout -- .
 
# 이제 브랜치 이동 가능
git switch other-branch

5) 머지 충돌 (Merge Conflict)

문제 상황: 

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

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

해결 방법:

1단계: 충돌 파일 확인 

# 충돌 상태 확인
git status
 
# 충돌 파일 내용 보기
cat index.html

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

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

💡 충돌 마커 의미:

  1. <<<<<<< HEAD: 현재 브랜치의 내용
  2. =======: 구분선
  3. >>>>>>> feature-login: 병합하려는 브랜치의 내용

3단계: 충돌 해결 

# 에디터로 파일 수정
nano index.html
 
# 충돌 마커 제거하고 원하는 내용으로 수정
# 예: <title>메인 페이지 - 로그인</title>

4단계: 병합 완료 

# 수정된 파일 추가
git add index.html
 
# 병합 커밋 생성
git commit -m "Merge conflict 해결: 제목 통합"
 
# 결과 확인
git log --oneline --graph

3. 🔐 인증 관련 문제

1) GitHub 인증 실패

문제 상황: 

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/'

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

해결 방법:

방법 1: Personal Access Token 사용

1단계: 토큰 생성

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

2단계: 토큰 사용 

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

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

1단계: SSH 키 생성 

# SSH 키 생성
ssh-keygen -t ed25519 -C ''your-email@example.com''
 
# 기본 설정으로 Enter 3번 입력
# 키 파일 위치: ~/.ssh/id_ed25519

2단계: SSH 키 GitHub에 등록 

# 공개 키 내용 복사
cat ~/.ssh/id_ed25519.pub
  1. GitHub → Settings → SSH and GPG keys
  2. New SSH key 클릭
  3. 제목 입력하고 키 내용 붙여넣기
  4. Add SSH key 클릭

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

# HTTPS에서 SSH로 변경
git remote set-url origin git@github.com:username/repository.git
 
# 확인
git remote -v

4. 🗂️ 파일 관리 문제

1) 파일을 실수로 삭제했을 때

문제 상황: 

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

해결 방법:

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

# 마지막 커밋 상태로 파일 복원
git checkout -- important-file.txt
 
# 또는 특정 커밋에서 복원
git checkout HEAD -- important-file.txt

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

# 파일이 삭제된 커밋 찾기
git log --oneline -- important-file.txt
 
# 삭제되기 직전 커밋에서 파일 복원
git checkout commit-hash -- important-file.txt
 
# 복원 후 커밋
git add important-file.txt
git commit -m "중요한 파일 복원"

2) 큰 파일 업로드 오류

문제 상황: 

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.

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

해결 방법:

방법 1: 파일 제거 

# 큰 파일을 .gitignore에 추가
echo "large-file.zip" >> .gitignore
 
# 이미 추가된 파일 제거
git rm --cached large-file.zip
 
# 커밋
git add .gitignore
git commit -m "큰 파일 제거 및 .gitignore 추가"
git push origin main

방법 2: Git LFS 사용 

# 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

5. 🔄 히스토리 관리 문제

1) 커밋을 너무 많이 만들었을 때

문제 상황: 

git log --oneline
# a1b2c3d 오타 수정
# e4f5g6h 또 오타 수정
# i7j8k9l 또또 오타 수정
# m1n2o3p 기능 추가

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

방법 1: Interactive Rebase 사용 

# 최근 4개 커밋을 하나로 합치기
git rebase -i HEAD~4
 
# 에디터가 열리면:
# pick m1n2o3p 기능 추가
# squash i7j8k9l 또또 오타 수정
# squash e4f5g6h 또 오타 수정
# squash a1b2c3d 오타 수정
 
# 저장하고 닫으면 커밋 메시지 편집 화면이 나타남
# 원하는 메시지로 수정 후 저장

방법 2: Soft Reset 사용 

# 최근 4개 커밋을 취소하되 변경사항은 유지
git reset --soft HEAD~4
 
# 모든 변경사항을 하나의 커밋으로 만들기
git commit -m "기능 추가 및 오타 수정"

⚠️ 주의사항:

  1. 이미 push한 커밋은 수정하지 마세요 (팀 작업 시)
  2. 혼자 작업할 때만 사용하세요

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

문제 상황: 

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

해결 방법:

1단계: 새 브랜치 생성 

# 현재 위치에서 새 브랜치 생성
git branch feature-new-function
 
# 또는 생성과 동시에 이동
git checkout -b feature-new-function

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

# main 브랜치로 이동
git checkout main
 
# 잘못된 커밋 되돌리기
git reset --hard HEAD~1
 
# 확인
git log --oneline -3

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

# 새 브랜치로 이동
git checkout feature-new-function
 
# 작업 계속...

6. 🛠️ 고급 복구 기법

1) 실수로 브랜치를 삭제했을 때

문제 상황: 

git branch -D feature-important  # 실수로 중요한 브랜치 삭제

해결 방법:

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

# reflog에서 삭제된 브랜치의 마지막 커밋 찾기
git reflog
 
# 결과 예시:
# a1b2c3d HEAD@{0}: checkout: moving from feature-important to main
# e4f5g6h HEAD@{1}: commit: 중요한 기능 완성
# ...

2단계: 브랜치 복원 

# 삭제된 브랜치 복원
git checkout -b feature-important e4f5g6h
 
# 확인
git log --oneline

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

문제 상황: 

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

해결 방법:

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

# 2번 전 커밋에서 해당 파일만 복원
git checkout HEAD~2 -- config.json
 
# 복원 후 커밋
git add config.json
git commit -m "설정 파일 복원"

방법 2: 커밋 되돌리기 

# 잘못된 커밋을 되돌리는 새 커밋 생성
git revert HEAD
 
# 또는 특정 커밋 되돌리기
git revert a1b2c3d

7. 🔍 문제 진단 도구

1) 유용한 명령어들

현재 상태 확인 

# 기본 상태 확인
git status
 
# 상세 상태 확인
git status -v
 
# 간단한 상태 확인
git status -s

히스토리 확인 

# 커밋 히스토리
git log --oneline --graph
 
# 특정 파일의 히스토리
git log --oneline -- filename.txt
 
# 모든 참조 히스토리 (삭제된 커밋도 포함)
git reflog

차이점 확인 

# 작업 디렉토리와 스테이징 영역 차이
git diff
 
# 스테이징 영역과 마지막 커밋 차이
git diff --cached
 
# 두 커밋 간 차이
git diff commit1 commit2

8. 🆘 응급 상황 대처법

1) "모든 것이 망가졌을 때"

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

해결 방법:

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

# 현재 상태 확인
git status
 
# 현재 브랜치 확인
git branch
 
# 최근 커밋 확인
git log --oneline -5
 
# 모든 참조 히스토리 확인
git reflog

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

# 작업 디렉토리의 모든 변경사항 버리기
git checkout -- .
 
# 스테이징 영역 정리
git reset HEAD
 
# 마지막 커밋 상태로 완전히 복원
git reset --hard HEAD

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

# 특정 커밋으로 완전히 되돌리기 (주의!)
git reset --hard commit-hash
 
# 또는 안전한 되돌리기
git revert commit-hash

9. 📚 도움 받는 방법

1) Git 내장 도움말

# 명령어 도움말 보기
git help status
git help commit
git help merge
 
# 간단한 도움말
git status --help
git commit --help

2) 온라인 리소스

공식 문서:

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

커뮤니티:

  1. Stack Overflow: git 태그로 검색
  2. GitHub Community: https://github.community/

한국어 자료:

  1. 생활코딩 Git 강의
  2. Git 공식 문서 한국어 번역

3) 오류 메시지 검색 팁

# 오류 메시지를 그대로 구글에 검색
"error: Your local changes to the following files would be overwritten"
 
# "git" 키워드 추가
git "CONFLICT (content): Merge conflict"
 
# 해결 방법도 함께 검색
git merge conflict how to resolve

10. 💡 문제 예방 팁

1) 좋은 습관 기르기

1. 자주 상태 확인하기 

# 명령어 실행 전후로 항상 확인
git status

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

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

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

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

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

# 중요한 브랜치 백업
git branch backup-main main
 
# 또는 태그로 백업
git tag backup-before-merge

5. .gitignore 파일 활용하기 

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

11. 🎓 마무리

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

기억해야 할 핵심 원칙:

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

문제가 생겼을 때:

  1. 당황하지 말고 현재 상태 파악
  2. 이 가이드에서 비슷한 상황 찾기
  3. 단계별로 차근차근 해결
  4. 해결되지 않으면 온라인 커뮤니티에 질문

예방이 최선입니다:

  1. 자주 커밋하고 push하기
  2. 중요한 작업 전 백업하기
  3. .gitignore 파일 활용하기
  4. 의미있는 커밋 메시지 작성하기

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

이전: 🌿 브랜치 관리 | 다음: 🚀 고급 팁과 트릭 | 목록: 📋 전체 문서 목록

wiki/it/github/troubleshooting.txt · 마지막으로 수정됨: 저자 syjang0803
Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki