GitHub 사용가이드

🚀 GitHub 초보자 완전 가이드

처음부터 끝까지, 모든 것을 완벽하게 배워보세요

🎯 GitHub 기초 설정

1

GitHub 계정 생성 (Sign up)

github.com에서 계정을 만들어보세요

GitHub

회원가입 필수 정보:
• Username (사용자명): 영문, 숫자, 하이픈(-) 가능
• Email address (이메일): 인증 가능한 이메일
• Password (비밀번호): 8자 이상, 숫자 포함 권장

2

프로필 설정 (Profile Setup)

프로필을 완성해서 전문성을 높여보세요

Profile Picture (프로필 사진)

Bio (자기소개)

Location (위치)

Website (웹사이트)

3

Git 설치 및 설정 (Git Installation & Configuration)

로컬 컴퓨터에서 Git을 사용하기 위한 설정

# Git 설치 확인 (Check Git installation) git --version # 사용자 정보 설정 (Set user information) git config --global user.name "Your Name" git config --global user.email "your.email@example.com" # 설정 확인 (Check configuration) git config --list

중요: 이메일은 GitHub 계정과 동일해야 합니다!

📚 Repository 저장소 관리

1

새 저장소 만들기 (Create a New Repository)

GitHub에서 새로운 프로젝트를 시작해보세요

Create a new repository

Repository name (저장소 이름)

Description (설명) - 선택사항

Visibility (공개/비공개)

Public (무료 사용자 권장) Private (유료 계정)

Initialize with README (README 파일 생성)

2

파일 업로드하기 (Upload Files)

웹 인터페이스를 통해 파일을 쉽게 업로드할 수 있습니다

Code Issues Pull requests Settings

📁 Drag additional files here to add them to your repository

Or choose your files

업로드 팁:
• 한 번에 여러 파일 선택 가능 (Ctrl+Click 또는 Shift+Click)
• 폴더 구조 유지됨
• 최대 100MB까지 업로드 가능
• 이미지, 문서, 코드 파일 모두 지원

3

커밋 (Commit) 이해하기

변경사항을 저장하는 Git의 핵심 개념

💾 Commit changes (변경사항 커밋)

Commit message (커밋 메시지)

Extended description (상세 설명) - 선택사항

Commit target

Commit directly to the main branch (메인 브랜치에 직접 커밋) Create a new branch (새 브랜치 생성) - 고급 사용자용

좋은 커밋 메시지 작성법:
• "feat: Add login functionality" (기능: 로그인 기능 추가)
• "fix: Fix navigation bug" (수정: 네비게이션 버그 수정)
• "docs: Update README documentation" (문서: README 문서 업데이트)
• "refactor: Remove unused CSS files" (리팩터링: 사용하지 않는 CSS 파일 제거)
(참고: 커밋 메시지 컨벤션을 사용하면 협업에 용이합니다.)

🌐 GitHub Pages로 웹사이트 배포

1

GitHub Pages 설정 (GitHub Pages Setup)

저장소의 특정 브랜치와 폴더를 이용해 웹사이트를 무료로 배포할 수 있습니다.

Code Issues Pull requests Settings

GitHub Pages

Static site hosting for your project, organization, or user page.

Source None main branch

Folder (Requires selecting a source branch) / (root) /docs

Settings > Pages 메뉴에서 Source 브랜치와 폴더를 선택 후 Save 버튼을 누르면 배포가 시작됩니다.

팁: 사이트가 정상적으로 표시되려면 선택한 소스 폴더의 최상위 경로에 index.html 파일이 있어야 합니다.

2

웹사이트 파일 준비 및 업로드 (Prepare and Upload Website Files)

배포할 HTML, CSS, JS 파일을 저장소의 Pages Source로 설정한 브랜치/폴더에 추가합니다.

my-awesome-project/

📄 index.html

📄 style.css

📄 script.js

images/

📄 logo.png

간단한 index.html 예시:

                                                
                

                
                
                
    
    
    
    

                

                
                











                
                

    
환영합니다!
    
이것은 GitHub Pages로 만든 첫 번째 웹사이트입니다.
    
    

                



                
                




                

3

배포 확인 (Check Deployment)

설정 저장 및 파일 커밋 후 몇 분 뒤에 사이트가 활성화됩니다.

사이트 주소 형식: https://[YOUR_USERNAME].github.io/[REPOSITORY_NAME]/
예시: https://honggildong.github.io/my-awesome-project/

문제 발생 시:
• Settings > Pages에서 Source 설정이 올바른지 확인하세요.
• 저장소에 index.html 파일이 지정된 폴더에 있는지 확인하세요.
• GitHub Actions (Actions 탭)에서 Pages 빌드/배포 워크플로우의 상태를 확인하세요.
• 배포까지 최대 10분 이상 소요될 수 있습니다.

✨ GitHub 심화 기능

협업 및 효율적인 코드 관리를 위한 추가 기능들입니다.

1

Branches (브랜치)

독립적으로 코드를 변경하고 실험할 수 있는 기능입니다. 새로운 기능 개발이나 버그 수정 시 메인 코드에 영향을 주지 않고 작업할 수 있습니다.

• main (or master): 프로젝트의 기본이 되는 안정적인 브랜치
• feature/login: 로그인 기능 개발을 위한 브랜치
• bugfix/nav: 네비게이션 버그 수정을 위한 브랜치

# 현재 브랜치 확인 git branch # 새 브랜치 생성 (이동은 안 함) git branch feature/my-new-feature # 새 브랜치 생성과 동시에 이동 git checkout -b feature/my-new-feature # 다른 브랜치로 이동 git checkout main # 브랜치 삭제 git branch -d feature/my-new-feature # 병합된 브랜치만 삭제 git branch -D feature/my-new-feature # 강제 삭제 (주의!)

브랜치를 사용하면 여러 사람이 동시에 다른 기능을 개발하거나, 안정적인 버전을 유지하면서 실험적인 작업을 진행하기 용이합니다.

2

Pull Requests (PRs)

내가 작업한 브랜치(예: feature/login)의 변경사항을 다른 브랜치(예: main)로 병합(Merge)하기 전에 검토를 요청하는 기능입니다. 협업의 핵심입니다.

Code Issues Pull requests Actions Projects Wiki Security Insights Settings

Pull requests

Your code changes, reviewed.

PR을 생성하면 변경된 코드 라인 비교, 코드 리뷰 요청, 관련 이슈 연결, 팀원 간 토론 등을 진행할 수 있습니다. 리뷰가 끝나면 안전하게 병합할 수 있습니다.

PR 생성 전에는 반드시 로컬 브랜치를 최신 상태로 업데이트하고, 베이스 브랜치(예: main)와 비교하여 충돌 여부를 확인하는 것이 좋습니다.

3

Issues (이슈)

버그 보고, 기능 요청, 작업 항목, 질문 등 프로젝트와 관련된 모든 논의 및 추적을 위한 시스템입니다.

Code Issues Pull requests Settings

Issues

Find a bug or suggest an idea?

이슈에는 제목, 상세 설명, 라벨(bug, enhancement 등), 담당자(Assignee), 마일스톤, 프로젝트 보드 등을 지정하여 프로젝트의 할 일 목록을 체계적으로 관리할 수 있습니다.

🔍 문제 해결

GitHub 사용 중 자주 발생할 수 있는 문제와 기본적인 해결 방법입니다.

1

인증 오류 (Authentication Error)

Authentication failed 또는 권한 관련 오류 메시지가 나타날 때 로컬 Git 클라이언트가 GitHub에 접근하지 못하는 경우입니다.

주요 원인:
• GitHub 비밀번호 변경 후 로컬에 저장된 자격 증명 정보가 업데이트되지 않음
• 2FA (2단계 인증) 활성화 후 비밀번호 대신 PAT(Personal Access Token) 미사용
• SSH 키 설정 문제 또는 키가 GitHub 계정에 등록되지 않음
• 해당 저장소에 대한 접근 권한이 없음 (조직/팀 설정 확인)

# HTTPS 사용 시: # push/pull 시 GitHub 사용자명과 비밀번호(또는 PAT) 입력 창이 나타남 # 비밀번호 입력 시 PAT를 사용해야 함 (2FA 활성화 시) # Git 자격 증명 관리자 업데이트/설정 (OS별 다를 수 있음) # Windows: `git config --global credential.helper manager` # macOS: `git config --global credential.helper osxkeychain` # Linux: `git config --global credential.helper store` (보안에 취약, 권장하지 않음) # SSH 사용 시: # SSH 키가 올바르게 설정되었는지 확인 ssh -T git@github.com # (성공 시 "Hi [username]! You've successfully authenticated..." 메시지 출력)

해결 방법:
• 가장 확실한 방법은 GitHub Personal Access Token(PAT)을 발급받아 비밀번호 대신 사용하는 것입니다.
• SSH 사용자는 SSH 키를 새로 생성하거나 GitHub 계정에 올바르게 등록되었는지 확인하세요.

2

병합 충돌 (Merge Conflict)

두 개 이상의 브랜치에서 같은 파일의 같은 줄을 서로 다르게 수정하고 이를 병합하려 할 때 발생합니다. Git이 어떤 변경사항을 선택해야 할지 알 수 없을 때 수동 해결이 필요합니다.

충돌이 발생한 파일에는 Git이 자동으로 추가한 충돌 마커(<<<<<, =====, >>>>>)가 표시됩니다. 이 부분을 보고 수동으로 코드를 수정해야 합니다.

# 병합 중 충돌 발생 git merge another-branch # 충돌 상태 확인 (Unmerged paths 확인) git status # 충돌 파일 열기 (예: index.html) # 에디터에서 충돌 마커 확인 및 수정 # 충돌 해결 후 파일 Stage에 추가 git add index.html # 병합 완료 커밋 (Git이 기본 메시지 제공) git commit # 또는 git commit -m "Resolve merge conflict in index.html" # 원격 저장소에 푸시 git push origin main # 또는 병합 대상 브랜치

VS Code, Sublime Text 등 많은 코드 에디터나 IDE는 충돌 해결을 도와주는 기능을 제공합니다.

3

대용량 파일 문제 (Large Files)

Git은 소스코드와 같은 작은 텍스트 파일 버전을 관리하는 데 최적화되어 있습니다. 이미지, 동영상, 컴파일된 바이너리 등 수십 MB 이상의 대용량 파일을 직접 저장소에 추가하면 여러 문제가 발생합니다.

문제점:
• 저장소 크기가 매우 커져서 Clone/Fetch/Pull 속도가 느려집니다.
• 저장소 백업/이동이 어렵습니다.
• GitHub 무료 계정의 저장소 크기 제한에 걸릴 수 있습니다.

해결책: Git LFS (Large File Storage) 사용
Git LFS는 대용량 파일 자체는 GitHub의 별도 스토리지나 다른 원격 스토리지에 저장하고, Git 저장소에는 해당 파일의 포인터(텍스트 파일)만 저장하는 방식입니다.

# Git LFS 설치 (사용하는 운영체제 및 패키지 관리자에 따라 다름) # 예: brew install git-lfs (macOS) # 예: apt-get install git-lfs (Debian/Ubuntu) # Git LFS 초기화 (저장소별 1회) git lfs install # 특정 확장자의 파일을 LFS로 관리하도록 설정 (.gitattributes 파일 수정) git lfs track "*.mp4" git lfs track "*.zip" git lfs track "path/to/large_assets/*" # .gitattributes 파일을 커밋 (LFS 추적 설정 저장) git add .gitattributes git commit -m "Configure Git LFS" # 이제 대용량 파일을 추가/커밋/푸시하면 LFS가 자동으로 처리 git add large_video.mp4 git commit -m "Add large video file" git push origin main