Git과 협업 워크플로

작은 변경을 브랜치·커밋·푸시·PR로 전달하고 재현 가능한 실행 안내 작성하기

이번 문서에서 만드는 것

작은 변경 하나를 브랜치에서 작성하고 커밋·푸시·PR 리뷰까지 경험합니다. 앱 기능을 만들기 전에는 README 개선으로 연습해도 됩니다. 기획·디자인 트랙은 같은 흐름을 산출물 링크와 의사결정 기록에 적용할 수 있습니다.

세션 전 준비

GitHub 로그인과 팀 저장소 접근 권한을 확인합니다. 팀 저장소가 있다면 clone 주소를 준비합니다. 없다면 GitHub에서 연습용 저장소를 만듭니다. 다른 팀의 저장소에 임의로 푸시하지 않습니다. 인증이나 권한 문제는 세션 전에 확인합니다.

작업 기준점 확인하기

Shell
git clone <팀 저장소 URL>cd <생성된 폴더>git statusgit remote -vgit branch --show-current

꺾쇠 안의 값은 실제 주소와 폴더명으로 바꿉니다. 현재 프로젝트를 이미 clone했다면 다시 중첩 clone하지 않습니다. 기존 수정이 있으면 누구의 작업인지 확인하고 이해하지 못한 변경을 reset·clean으로 지우지 않습니다.

팀 기본 브랜치가 main이라고 가정한 예시입니다. 실제 이름이 다르면 맞춰 바꿉니다.

Shell
git switch maingit pull --ff-onlygit switch -c docs/my-first-contribution

--ff-only가 실패하면 로컬과 원격 이력이 갈라졌는지 확인합니다. 바로 강제 푸시하거나 브랜치를 덮어쓰는 해결책을 사용하지 않습니다.

README에 재현 가능한 안내 쓰기

다음 중 자신의 트랙에 맞는 작은 변경을 하나만 고릅니다.

  • 프론트엔드: 실제 실행 명령·접속 주소·첫 화면 확인 방법.
  • Django: 가상환경·설치·migration·서버 실행 순서.
  • Spring: JDK·Wrapper·API 확인 주소.
  • 기획·디자인: 검토할 Figma 프레임·문제 정의·미확정 질문 링크.

문서에 명령을 적었다면 실제로 실행합니다. 예를 들어 package.json에 test 스크립트가 없는 프로젝트에 npm test를 복사해 넣지 않습니다. 비밀값 대신 변수 이름과 준비 방법을 설명합니다.

변경 확인과 커밋

Shell
git diffgit add README.mdgit diff --cachedgit commit -m "docs: add local setup instructions"git push -u origin docs/my-first-contribution

git add .보다 이번 변경 파일을 명시하면 불필요한 로그·비밀 파일을 함께 올리는 실수를 줄일 수 있습니다. staged diff에 의도한 내용만 있는지 확인한 뒤 커밋합니다. -u는 이후 해당 브랜치의 push·pull 대상 추적 관계를 설정합니다.

PR에서 설명할 것

GitHub의 비교 화면에서 base를 팀 기본 브랜치, compare를 작업 브랜치로 선택하고 PR을 만듭니다. 저장소 템플릿이 있다면 따릅니다.

문제: 처음 참여한 팀원이 실행 폴더와 명령을 찾기 어렵다. 변경: README에 실행 위치·명령·성공 확인을 추가했다. 검증: 새 터미널에서 안내대로 실행해 첫 화면을 확인했다. 남은 점: 운영 배포 안내는 이번 변경 범위에 포함하지 않았다.

위 설명은 작성 예시입니다. 실제 실행하지 않았다면 검증했다고 적지 않습니다. 리뷰어는 처음 보는 사람 입장에서 모호한 경로·누락된 사전 준비·틀린 명령을 확인합니다. 수정 요청은 작업 브랜치에서 커밋하고 푸시하면 같은 PR에 반영됩니다.

충돌을 이해하는 안전한 연습

실제 팀 작업을 덮어쓰지 않도록 별도의 로컬 연습 저장소에서 같은 파일의 같은 줄을 두 브랜치에서 다르게 바꾸어 merge 충돌을 만들어 봅니다. 충돌 표시 <<<<<<<, =======, >>>>>>>의 양쪽 의도를 읽고 최종 내용을 결정합니다.

처리 흐름은 git status로 충돌 파일 확인→파일 편집→표시 제거와 결과 검증→git add <파일>→merge 커밋입니다. 진행 중 merge를 취소하려면 git merge --abort를 사용할 수 있지만 먼저 현재 상태와 보존할 작업을 확인합니다. 팀 브랜치에서 강제 push를 연습하지 않습니다.

충돌은 “내 코드 선택” 버튼으로 자동 해결되는 문제가 아닙니다. 두 변경을 모두 살려야 하는지, 같은 요구를 다르게 구현했는지 작성자와 문맥을 확인합니다.

세션 진행과 완료 기준

권장 80분: 저장소·브랜치 15분, 작은 문서 수정 20분, diff·커밋·PR 25분, 상호 리뷰 20분입니다. 충돌 연습은 별도 20분 확장으로 진행합니다.

완료 기준은 PR에 변경 이유·실제 검증이 있고 리뷰를 반영한 커밋을 남기며 관계없는 파일과 비밀값이 포함되지 않는 것입니다. merge는 팀의 리뷰 규칙에 따라 진행합니다. PR 생성과 merge는 다른 단계입니다.

더 읽어보기