부록: 자주 발생하는 문제와 해결 가이드¶

설치/설정 문제¶

Q: git 명령어를 찾을 수 없다고 나와요¶

Windows: Git Bash를 설치했는지 확인. 시작 메뉴에서 "Git Bash" 검색

macOS: 터미널을 열고 아래 입력

xcode-select --install

Linux:

# Ubuntu/Debian
sudo apt update && sudo apt install git

# Fedora
sudo dnf install git

Q: 줄바꿈 관련 경고가 나와요 (Windows)¶

warning: LF will be replaced by CRLF in ...

Windows와 macOS/Linux의 줄바꿈 문자가 달라서 발생합니다.

# Windows에서 추천 설정
git config --global core.autocrlf true

# macOS/Linux에서 추천 설정
git config --global core.autocrlf input

Q: 한국어 파일명이 깨져요¶

git config --global core.quotepath false

Q: 기본 에디터를 바꾸고 싶어요¶

# VS Code
git config --global core.editor "code --wait"

# nano (초보자 친화적)
git config --global core.editor "nano"

# vim
git config --global core.editor "vim"

인증 문제¶

Q: push할 때 인증 에러가 나와요¶

remote: Permission denied (publickey)
fatal: Could not read from remote repository

해결 1: SSH 키 확인

# 키 존재 확인
ls ~/.ssh/id_*.pub

# 없으면 생성
ssh-keygen -t ed25519 -C "your-email@example.com"

# 공개 키 복사
cat ~/.ssh/id_ed25519.pub
# → GitHub Settings > SSH Keys 에 추가

해결 2: HTTPS를 쓰고 있다면

# 원격 URL 확인
git remote -v

# HTTPS → SSH로 변경
git remote set-url origin git@github.com:username/repo.git

# 기존 인증 정보 초기화
gh auth logout

# 토큰으로 로그인
# GitHub → Settings → Developer settings → Personal access tokens
# 에서 토큰 생성 후:
echo "ghp_your_token" | gh auth login --with-token

커밋/브랜치 문제¶

Q: 빈 폴더가 커밋이 안 돼요¶

Git은 빈 폴더를 추적하지 않습니다. .gitkeep 파일을 넣으면 됩니다.

mkdir empty-folder
touch empty-folder/.gitkeep
git add empty-folder/.gitkeep

Q: 실수으로 큰 파일을 커밋했어요¶

# 파일을 Git에서 제거 (실제 파일은 유지)
git rm --cached large-file.zip

# .gitignore에 추가
echo "*.zip" >> .gitignore

git add .gitignore
git commit -m "remove large file and update .gitignore"

이미 push했다면 히스토리에서도 지워야 합니다:

# 주의: 히스토리가 재작성됩니다
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch large-file.zip' \
  --prune-empty HEAD
git push --force

Q: merge 충돌이 너무 복잡해요¶

# 병합 취소하고 처음부터 다시
git merge --abort

# 또는 rebase 중이면
git rebase --abort

# 특정 파일을 한쪽 버전으로 통째로 선택
git checkout --theirs conflicted-file.py   # 병합 대상 브랜치 버전
git checkout --ours conflicted-file.py     # 현재 브랜치 버전

Q: push가 거부돼요 (rejected)¶

! [rejected]        main -> main (fetch first)

원격에 내가 모르는 커밋이 있을 때:

# 안전한 방법: 먼저 pull 후 push
git pull --rebase origin main
git push

# 절대 하면 안 되는 것 (다른 사람의 커밋을 덮어씀):
# git push --force  ← 혼자 쓰는 저장소가 아니면 금지!

Q: detached HEAD 상태가 됐어요¶

# 특정 커밋을 checkout 하면 발생
git checkout abc123
# "HEAD detached at abc123"

# 여기서 작업한 내용을 유지하려면 브랜치 만들기
git checkout -b my-branch

# 아니면 그냥 돌아가기
git checkout main

GitHub 문제¶

Q: fork한 저장소를 원본과 동기화하고 싶어요¶

# 원본 저장소 추가 (최초 1회)
git remote add upstream git@github.com:original-owner/repo.git

# 동기화
git fetch upstream
git checkout main
git merge upstream/main
git push

Q: gh 명령어가 인식이 안 돼요¶

# 설치 확인
which gh
gh --version

# PATH 문제일 수 있음
# macOS (Homebrew)
brew link gh

# Linux: 설치 방법 재확인

Q: CI (GitHub Actions)가 실패해요¶

# 실패한 실행 찾기
gh run list --status failure --limit 3

# 로그 확인
gh run view RUN_ID --log-failed

# 가장 흔한 원인:
# 1. 의존성 설치 누락
# 2. 환경 변수 미설정 (Secrets 필요)
# 3. 테스트 코드 에러

복구 불가능한 것 같을 때¶

Q: 모든 걸 날려버린 것 같아요¶

# 1. reflog 확인 — 대부분 여기서 복구 가능
git reflog

# 2. 원하는 시점으로 돌아가기
git reset --hard abc123

# 3. 이미 push한 건 GitHub에서 복구
gh api repos/owner/repo/commits --jq '.[0].sha'

Q: 정말 모르겠어요¶

# 도움말 보기
git help <명령어>
git commit --help

# gh 도움말
gh help
gh pr create --help

전체 목차: 1. Git 기초 2. 되돌리기 3. 브랜치 4. 원격 저장소 5. GitHub 협업 6. 꿀팁 7. GitHub CLI 8. 문제 해결 가이드 (현재 문서)