Git & GitHub으로 협업하며 개발하기 (상세)

이 글은 “Git & GitHub으로 협업하며 개발하기” 강의의 상세 내용입니다. 강의 개요는 여기에서 확인할 수 있습니다.

후속 강의: Git을 넘어 — 오픈소스 기여자의 세계로

이 내용을 슬라이드로 보려면 프레젠테이션 모드를 이용하세요.

Part 1 — Git & GitHub 기초

Git이란?

Git은 분산 버전 관리 시스템(DVCS) 입니다.
파일의 변경 이력을 기록하고, 원하는 시점으로 되돌리고, 여러 사람이 동시에 작업해도 충돌 없이 합칠 수 있게 해 줍니다.

핵심 개념은 네 가지 공간(공간을 의식하면 Git이 절반은 쉬워집니다):

• Working Directory — 지금 내가 편집하고 있는 실제 파일들
• Staging Area (Index) — “다음 커밋에 포함시킬” 변경분을 모아 두는 임시 영역
• Local Repository — 커밋이 영구히 저장되는 곳 (로컬 .git/ 폴더)
• Remote Repository — GitHub처럼 다른 사람과 공유하는 원격 저장소

아래 데모에서 파일이 네 공간 사이를 어떻게 이동하는지 직접 눌러 보며 확인할 수 있습니다.

GitHub이란?

Git이 “도구"라면, GitHub은 그 도구로 만들어진 결과물을 여러 사람이 함께 쓰는 공간 입니다.
정확히는 Git 저장소를 클라우드에서 호스팅하고, 협업 기능을 얹어 둔 서비스입니다.

GitHub이 제공하는 주요 협업 기능:

비슷한 서비스로 GitLab, Bitbucket, Gitea 등이 있습니다.
Git이라는 표준 위에서 각자 협업 기능을 얹은 형태입니다.

기본 명령어 한 사이클

Git에서 가장 자주 쓰는 명령어 한 사이클은 다음과 같습니다:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 1. 저장소를 내 컴퓨터에 복제
git clone https://github.com/<user>/<repo>.git
cd <repo>

# 2. 파일 수정 후 스테이징
git add <file>          # 특정 파일만
git add .               # 변경된 파일 전체

# 3. 커밋
git commit -m "Add timer start/pause/reset"

# 4. 원격 저장소에 업로드
git push

# 5. 다른 사람의 변경 사항 받아오기
git pull

각 명령은 앞서 본 4개의 공간 사이를 이동시키는 동작입니다.
“지금 내 변경이 어느 공간에 있는가” 만 의식하면 Git은 어렵지 않습니다.

GitHub 웹 UI 둘러보기

저장소 페이지 상단의 탭이 곧 GitHub의 협업 기능입니다:

• Code — 파일 트리, README, 브랜치/태그 목록
• Issues — 작업·논의 트래커
• Pull requests — 머지 요청과 리뷰
• Actions — CI/CD 실행 결과
• Projects / Wiki / Security / Insights — 부가 기능

처음에는 Code → Issues → Pull requests 셋만 익숙해져도 충분합니다.

Part 2 — Sourcetree 입문

왜 GUI를 쓰는가

Git을 CLI만으로 익히면 두 가지가 어려워집니다:

1. 그래프 시각화 — 브랜치들이 어떻게 갈라지고 합쳐졌는지, 텍스트만 봐서는 머릿속에 그려지지 않습니다.
2. 머지/충돌 상황 — 어디가 충돌인지, 양쪽 코드가 각각 무엇인지 한눈에 비교하기 어렵습니다.

Sourcetree(Atlassian 제공, 무료)는 이 두 가지를 시각적으로 보여 주는 GUI 도구입니다.
특히 Git Flow를 메뉴로 지원 한다는 점이 이 강의에서 Sourcetree를 고른 이유입니다.

설치와 GitHub 연동

1. Sourcetree를 설치합니다.
2. 첫 실행 시 Atlassian 계정 등록을 요구할 수 있습니다 (무료).
3. 계정 추가 → GitHub 을 선택해 OAuth로 GitHub 계정과 연결합니다.
4. 메뉴 → Clone에서 GitHub의 저장소 URL을 붙여 넣으면 로컬에 복제됩니다.

핵심 화면 구성

Sourcetree의 메인 화면은 크게 네 영역으로 나뉩니다:

• 좌측 사이드바 — 로컬 브랜치, 원격 브랜치, 태그, Stash 목록
• 상단 그래프 — 커밋 히스토리를 시각화한 브랜치 그래프
• 하단 좌측 — 선택한 커밋에 포함된 파일 목록
• 하단 우측 — 선택한 파일의 diff (변경 내용)

작업 흐름은 상단 그래프로 현재 상황 파악 → 우측 상단 버튼(Commit, Push, Pull, Branch, Merge) 으로 명령 실행입니다.

CLI ↔ GUI 1:1 대응표

명령어를 모두 외울 필요는 없습니다. “내가 지금 무엇을 하고 싶은가” 를 GUI에서 찾는 습관이 먼저 들면, CLI는 자연스럽게 따라옵니다.

에디터에서 보는 Git — VS Code의 Git 통합

Sourcetree가 “브랜치와 히스토리 관리” 에 강점이라면,
VS Code의 Git 통합은 “코드를 편집하면서 변경을 곧바로 확인” 하는 데 강점입니다.
두 도구는 경쟁 관계가 아니라 보완 관계입니다.

VS Code가 보여 주는 Git 정보:

핵심 장점은 “내가 지금 어디를 바꿨는가"를 에디터를 떠나지 않고 라인 단위로 즉시 확인할 수 있다는 것입니다.
커밋 전에 거터 표시만 훑어도 의도하지 않은 변경이 섞였는지 한눈에 잡힙니다.

실무 조합 예시: VS Code(편집 + 라인 단위 변경 확인) + Sourcetree(브랜치·머지·Git Flow) + CLI(스크립트·자동화).
세 도구가 각자 강한 부분만 맡으면 가장 매끄럽습니다.

Part 3 — Git Flow 워크플로 이해하기

Git Flow란?

Git Flow는 2010년 Vincent Driessen이 글 한 편으로 제안한 브랜치 전략입니다.
핵심 아이디어는 “브랜치마다 역할을 명확히 분리하자” 입니다.

다섯 가지 브랜치의 역할

핵심은 “분기와 머지의 방향이 정해져 있다” 는 점입니다.

feature는 develop에서 따와 develop으로 합치고,
hotfix는 main에서 따와 main과 develop 모두에 합칩니다.

이 규칙만 지키면 브랜치가 아무리 많아져도 흐름이 어지러워지지 않습니다.

한 사이클의 흐름

위 그래프에서:

1. main에서 develop 분기
2. develop → feature/timer 분기 → 기능 구현 후 다시 develop으로 머지
3. develop → release/0.1.0 → 출시 준비 → main에 머지 + 태깅 → develop에도 머지
4. main → hotfix/critical → 긴급 수정 → main + develop 모두에 머지

아래 시뮬레이터에서 직접 버튼을 눌러 가며 같은 흐름을 만들어 볼 수 있습니다.
추상적인 다이어그램과 실제 그래프가 어떻게 일치하는지 한눈에 들어옵니다.

Git Flow vs GitHub Flow

(이외에 Trunk-based development도 있으나, 대형 SaaS에서 feature flag와 결합해 쓰는 고급 전략입니다.)

왜 오픈소스에서 Git Flow가 자주 쓰이나

오픈소스 라이브러리·도구는 보통 버전을 명시적으로 릴리스 합니다. (예: v1.4.2)

사용자가 특정 버전에 고정해서 의존하기 때문에,
“지금 배포된 안정 버전"과 “다음 릴리스를 위해 개발 중인 버전"을 분리할 필요가 있습니다.
Git Flow의 main ↔ develop 분리가 이 요구에 정확히 들어맞습니다.

Part 4 — Sourcetree의 Git Flow 메뉴 살펴보기

Sourcetree에는 Git Flow가 메뉴 한 항목 으로 내장되어 있습니다.
메뉴 클릭 한 번이 곧 Vincent Driessen의 표준 흐름 한 단계를 그대로 실행합니다.

Git Flow 메뉴 활성화

저장소를 연 상태에서 상단 메뉴 Repository → Git Flow → Initialize Repository 를 선택합니다.
기본 브랜치 이름(main, develop, feature/, release/, hotfix/)을 확인하고 OK를 누르면
develop 브랜치가 자동으로 만들어집니다.

각 메뉴가 실행하는 Git 명령

--no-ff 옵션이 핵심입니다.
빨리 감기(fast-forward) 머지 대신 명시적 머지 커밋을 만들어,
그래프에서 “이 묶음이 한 feature였다"는 정보가 사라지지 않게 합니다.

CLI로 같은 일을 할 때

git-flow CLI 확장을 설치하면 CLI에서도 같은 명령을 쓸 수 있습니다:

1
2
3
4
5
6
7
8

brew install git-flow-avh           # macOS
git flow init                       # 초기화
git flow feature start timer        # feature/timer 시작
git flow feature finish timer       # feature/timer 종료
git flow release start 0.1.0        # release/0.1.0 시작
git flow release finish 0.1.0       # 태깅 + main/develop 머지
git flow hotfix start critical      # hotfix/critical 시작
git flow hotfix finish critical     # 태깅 + main/develop 머지

Sourcetree의 Git Flow 메뉴는 이 CLI 명령들을 GUI로 감싼 것에 가깝습니다.
메뉴를 눌렀을 때 어떤 명령이 실행되는지 만 알면, 둘 사이를 오가는 데 어려움이 없습니다.

Part 5 — Pull Request와 코드 리뷰

Pull Request의 의미

Pull Request(PR)는 단순한 머지 요청이 아닙니다. 두 가지를 동시에 부탁하는 행위입니다:

1. “내 브랜치를 합쳐 주세요” — 머지 요청
2. “리뷰해 주세요” — 동료의 검토 요청

따라서 좋은 PR은 머지보다 리뷰가 쉬워지는 형태 로 만드는 것이 중요합니다.

좋은 PR의 조건

코드 리뷰 주고받기

GitHub PR 페이지의 핵심 인터페이스:

• Files changed 탭 — diff. 라인 옆 + 버튼으로 인라인 코멘트 작성
• Start a review → 여러 코멘트를 모아 한 번에 보내기
• Review changes 메뉴 — Comment / Approve / Request changes 셋 중 선택
• Resolve conversation — 토론이 끝난 코멘트 접기

리뷰는 “공격이 아니라 협업” 이라는 합의가 가장 중요합니다.
“이 코드 이상해요"보다 “여기 이런 케이스에서 어떻게 동작할까요?” 가 훨씬 건강한 리뷰입니다.

충돌(Merge Conflict) 해결

PR을 보내고 다른 PR이 먼저 머지되면, 내 브랜치가 main(또는 develop)과 충돌할 수 있습니다. Sourcetree의 충돌 해결 흐름:

1. 충돌 발생 → 머지 시도가 중단되며 파일 옆에 ⚠️ 표시
2. 충돌 파일 더블클릭 → 외부 머지 도구가 열림 (또는 텍스트로 <<<<<<< 마커 직접 편집)
3. 양쪽 코드 중 어느 쪽을 살리고/합칠지 결정
4. 저장 후 Mark Resolved → 다시 커밋

머지 도구로 Beyond Compare, Kaleidoscope(macOS), WinMerge(Windows) 등이 자주 쓰입니다.

아래 데모에서 충돌 한 건마다 “Keep mine / Keep theirs / Keep both” 중 무엇을 골라야 하는지, 결과 파일이 어떻게 달라지는지 직접 확인해 보세요.

Merge vs Rebase vs Squash

세 가지 모두 GitHub PR의 머지 버튼 옆 드롭다운에서 선택할 수 있습니다.
팀이 한 가지 전략으로 합의해 두면 그래프가 일관됩니다.

Part 6 — AI 코드 생성기와 Git Flow

AI 코드 생성기 시대의 개발 흐름

2024년 이후 개발자의 일상에 AI 코드 생성기 가 자리 잡았습니다:

• Claude Code (Anthropic) — 터미널에서 동작하는 에이전트형 코드 생성기
• GitHub Copilot (GitHub × OpenAI) — 에디터 인라인 자동 완성 중심
• Cursor — VS Code 포크 기반 IDE
• Windsurf, Aider 등

이들의 공통점은 “사람이 의도를 말하면, AI가 코드를 만들고, 사람이 검토한다” 는 새로운 협업 구조를 만든다는 것입니다.

왜 Git Flow가 AI 시대에도 유효한가

AI 코드 생성기가 새로운 도구라고 해서 Git Flow가 낡은 것은 아닙니다.
오히려 Git Flow의 구조가 AI 워크플로와 잘 들어맞습니다:

요약하면, Git Flow의 각 브랜치는 “사람의 개입 지점” 이고, AI 코드 생성기 시대에 그 지점은 더욱 중요해집니다.

AI 생성 코드를 리뷰할 때 추가로 봐야 할 것

사람이 작성한 코드 리뷰와 동일한 항목 + 다음을 추가로 봐야 합니다:

• 환각(hallucination) — 존재하지 않는 함수·라이브러리·API를 호출하지 않는가
• 라이선스 — 학습 데이터에서 비롯된 코드 조각이 라이선스를 위반하지 않는가
• 보안 — 비밀키 노출, 인증·인가 누락, 입력 검증 누락
• 테스트 커버리지 — AI가 “동작은 하는 것처럼 보이는” 코드를 만들 수 있으므로, 경계값/실패 경로를 사람이 직접 테스트
• 의도와 일치성 — 시키지 않은 추가 동작(주석 자동 작성, 무관한 리팩토링)이 섞이지 않았는가

AI에게 커밋 메시지·PR 설명을 맡기기

AI가 가장 잘하는 글쓰기 중 하나가 변경 요약 입니다:

1
2

# Claude Code의 자동 커밋 메시지 예시
git diff --staged | claude "이 변경을 한 줄 요약하는 커밋 메시지를 작성해 줘"

PR 설명도 마찬가지입니다.
단, AI 요약은 “무엇이 바뀌었는가(WHAT)” 는 잘 쓰지만 “왜 바뀌었는가(WHY)” 는 사람이 직접 보충해야 합니다.
AI 요약을 초안으로 두고, “왜"를 한두 문장 더해 주는 정도가 가장 효율적입니다.

Part 7 — 시연: Claude Code + Git Flow로 타이머 앱 만들기

이 파트는 강사가 빈 저장소부터 배포까지 한 사이클을 화면 공유로 보여 주는 메인 시연 입니다.

아래의 단계별 흐름은 시연을 글로 옮겨 둔 복습용 기록입니다.
강의 중에는 화면을 따라가며 흐름을 잡고, 세부 단계는 끝난 뒤 이 글에서 확인해도 충분합니다 — 미리 외울 필요는 없습니다.

시연 환경

단계별 시연 흐름

Step 1 — 저장소 생성과 Clone

1. GitHub 웹에서 timer-app 저장소를 비어 있는 상태로 생성
2. Sourcetree에서 Clone, 로컬 폴더 선택
3. 터미널에서 같은 폴더로 이동

Step 2 — Git Flow 초기화

1. Sourcetree → Repository → Git Flow → Initialize Repository
2. 기본값으로 OK → develop 브랜치가 생성되고 자동 체크아웃

1
2

# CLI로도 같은 동작
git flow init -d

Step 3 — feature/timer 시작

1. Sourcetree → Git Flow → Start New Feature → 이름 timer
2. feature/timer 브랜치로 자동 전환

Step 4 — Claude Code로 구현

터미널에서 Claude Code를 띄우고 작업을 작은 단위로 분리해서 요청합니다:

1
2
3
4
5
6
7
8

> 빈 폴더에 index.html, style.css, script.js로 구성된 타이머 앱 골격을 만들어 줘.
  화면에는 큰 숫자(MM:SS) 하나와 Start / Pause / Reset 세 버튼만 둬.

> 이제 Start 버튼 동작을 구현해 줘. setInterval로 1초마다 카운트하고,
  같은 버튼을 다시 누르면 일시정지하도록.

> Pause는 별도 버튼으로 두고, Reset은 00:00으로 되돌리는 동작.
  CSS는 다크 톤으로 간결하게.

각 요청 후 동작을 확인하고, 의도한 만큼만 코드가 들어왔는지 검토합니다.

Step 5 — 의미 있는 커밋 단위로 나누기

Sourcetree에서 변경 파일을 보며 다음 단위로 커밋을 분리합니다:

“한 커밋 = 한 의도"가 유지되면 PR 리뷰가 훨씬 쉬워집니다.

Step 6 — Push와 Pull Request

1. Sourcetree → Push → feature/timer를 origin으로 푸시
2. GitHub 페이지에 자동 표시되는 Compare & pull request 클릭
3. 제목: Add timer feature (start / pause / reset)
4. 설명: 무엇을·왜 + Claude Code 사용 여부 명시
5. PR 페이지에서 리뷰 인터페이스, Files changed 탭, 인라인 코멘트 작성 화면을 둘러보기

Step 7 — 머지

1. (시연용 상황) 셀프 승인 → Merge pull request
2. 머지 전략은 Create a merge commit (Git Flow의 --no-ff와 동일한 효과)
3. 로컬에서 Sourcetree → Git Flow → Finish Feature 로도 동일하게 종료 가능

Step 8 — release/0.1.0 → 배포

1. Sourcetree → Git Flow → Start New Release → 버전 0.1.0
2. 필요한 경우 README.md에 버전 추가, 마지막 점검
3. Finish Release → 자동으로:
   • main에 머지
   • 태그 0.1.0 생성
   • develop에도 머지
4. Push + Push tags 로 원격에 반영

Step 9 — hotfix/critical 시연

타이머가 1분을 넘기면 분 자릿수가 깨지는 버그를 일부러 만들어 놓고, hotfix 사이클을 보여 줍니다:

1. Git Flow → Start New Hotfix → 이름 time-format
2. Claude Code에게 한 줄 수정 요청
3. Finish Hotfix → main에 머지 + 태그 0.1.1 + develop에도 자동 머지

최종 GitGraph

시연이 끝나면 Sourcetree 그래프가 Part 3의 다이어그램과 거의 동일한 모양이 됩니다.
추상적인 모델 ↔ 실제 그래프 가 일치하는 순간이 이 강의의 핵심 장면입니다.

Part 8 — 오픈소스 기여 흐름 살펴보기

오픈소스 저장소에서 먼저 확인할 핵심 문서

오픈소스 저장소를 처음 만났을 때 가장 먼저 확인할 것은 코드가 아니라 루트의 문서들 입니다.
프로젝트의 성격과 기여 방식이 코드보다 이 문서들에 먼저 드러납니다:

기여 전에 적어도 README와 CONTRIBUTING은 꼭 읽어야 합니다.
CONTRIBUTING을 무시한 PR은 메인테이너의 신뢰를 잃기 쉽고,
CHANGELOG는 내 변경이 어떤 버전 흐름에 들어가는지 가늠하는 데 유용합니다.

Good First Issue 찾기

처음 기여한다면 라벨 good first issue 또는 help wanted 가 붙은 이슈부터 시작합니다.

GitHub 검색:

1

is:issue is:open label:"good first issue" language:python

좋은 첫 이슈의 조건:

• 명확한 재현 방법 또는 명확한 작업 범위
• 메인테이너가 최근에도 활동 중 (최근 30일 내 응답이 있는 저장소)
• 다른 기여자가 이미 잡고 있지 않음 (코멘트 확인)

Fork → Branch → PR 흐름

내가 직접 푸시 권한이 없는 저장소에 기여할 때:

1. Fork — 저장소를 내 계정으로 복제
2. Clone — 내 fork를 로컬에 복제
3. Branch — feature/<short-description> 같은 의미 있는 이름
4. 작업 → 커밋 → push
5. GitHub에서 원본 저장소에 PR 생성 (“base: upstream:main”, “compare: myuser:feature/…”)
6. 리뷰 응답 → 추가 커밋 → 머지

upstream(원본)과 origin(내 fork)을 둘 다 원격으로 두면 동기화가 쉽습니다:

1
2
3

git remote add upstream https://github.com/<원본 조직>/<repo>.git
git fetch upstream
git rebase upstream/main

메인테이너와 소통하는 매너

• 리뷰는 시간이 걸리는 일 — 메인테이너 대부분이 자원봉사이거나 본업과 병행 중입니다. 즉답을 기대하지 마세요. 며칠~일주일 정도의 응답 주기는 평범한 편입니다
• 충분히 기다린 뒤에는 한 번 더 알려도 됩니다 — 2주 이상 무소식이면 “여유 되실 때 한 번 봐주시면 감사하겠습니다” 정도의 정중한 코멘트로 가볍게 환기시키는 정도가 적당합니다
• 변경 요청을 받았을 때 — 동의하면 반영, 동의하지 않으면 근거를 정중하게 설명. 감정 없이 “왜 그렇게 결정했는지"만 또렷이 전하면 충분합니다
• 합쳐지지 않을 수도 있음 — “프로젝트 방향과 맞지 않는다"는 결정도 정당합니다. 그 자체로 배움이 됩니다
• 머지된 후 — 짧은 감사 인사 한 줄. 그리고 다음 이슈로 이동

AI 생성 코드를 오픈소스에 기여할 때

오픈소스 커뮤니티는 AI 생성 코드 기여에 대해 정책이 다양해지고 있습니다. 기여 전 다음을 확인하세요:

• 저장소의 정책 — 일부 프로젝트는 AI 생성 코드를 거부하거나 명시를 요구함 (CONTRIBUTING.md 확인)
• 라이선스 호환성 — 학습 데이터에서 비롯된 코드 조각이 프로젝트 라이선스와 충돌하지 않는지
• 검토 책임 — “AI가 만든 것” 이라고 책임이 면제되지 않습니다. 기여자가 코드의 동작을 이해해야 합니다
• 공시 — 의심스러우면 PR 설명에 “Claude Code로 초안을 작성하고 직접 검토했습니다” 정도로 명시

투명성과 책임감이 가장 좋은 정책입니다.

핵심 메시지 다시 보기

참고 자료

• Vincent Driessen, “A successful Git branching model” (2010): https://nvie.com/posts/a-successful-git-branching-model/
• Pro Git 책 (한국어 번역본): https://git-scm.com/book/ko/v2
• GitHub Docs — Pull Requests: https://docs.github.com/ko/pull-requests
• GitHub Docs — Code review: https://docs.github.com/ko/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests
• Atlassian Sourcetree: https://www.sourcetreeapp.com/
• git-flow CLI 확장: https://github.com/petervanderdoes/gitflow-avh
• Anthropic Claude Code: https://claude.com/claude-code
• GitHub “Good first issues”: https://github.com/search?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
• Open Source Guide — How to Contribute: https://opensource.guide/how-to-contribute/