GitHub 저장소 생성과 첫 커밋 푸시 절차

저장소 생성 전 결정 사항

저장소 생성 화면에서 나중에 바꾸기 번거로운 선택은 이름과 공개 범위 두 가지입니다. 이름은 URL의 일부가 되므로, 변경하면 기존 주소로 연결된 링크와 로컬 원격 설정을 함께 수정해야 합니다.

공개 범위는 비용이 아니라 노출 여부로 판단합니다. GitHub Free는 공개 저장소를 전체 기능으로 무제한 사용할 수 있고, 비공개 저장소도 개수 제한 없이 만들 수 있지만 일부 기능이 제한됩니다. 따라서 개인 학습용 코드에 접속 정보나 실제 데이터가 섞여 있으면 비공개를, 포트폴리오로 공개할 목적이면 공개를 선택해야 합니다.

공개 저장소와 비공개 저장소의 접근 범위와 기능을 비교한 표입니다.

저장소 생성과 로컬 연결 절차

아래 순서는 웹에서 저장소를 만든 뒤, 이미 작업하던 로컬 폴더를 그 저장소에 연결하는 방법입니다. README 추가를 켜면 저장소에 커밋이 하나 생기므로, 로컬에도 커밋이 있다면 두 이력을 합치는 단계가 필요합니다.

1. 화면 우측 상단의 더하기 아이콘을 누르고 New repository 메뉴를 선택합니다.
2. Repository name 입력란에 영문 소문자와 하이픈으로 이름을 적고 공개 범위를 지정합니다.
3. Add README 항목을 켜면 저장소 첫 화면에 설명 파일이 생기므로 켠 상태로 Create repository 버튼을 누릅니다.
4. 로컬 작업 폴더에서 터미널을 열고 git init 명령으로 저장소를 초기화한 뒤 git add 명령으로 파일을 담습니다.
5. git commit 명령에 -m 옵션으로 변경 내용을 적어 첫 커밋을 만듭니다.
6. 저장소 화면에 표시된 주소를 git remote add origin 명령에 붙여 원격 저장소를 연결합니다.
7. git push --set-upstream origin HEAD 명령으로 올리고, 웹 화면을 새로 고쳐 파일 목록이 보이는지 대조합니다.

첫 연결 점검표: 원격 주소가 본인 계정인지, 올리려는 폴더에 접속 정보 파일이 섞이지 않았는지, 기본 브랜치 이름이 로컬과 원격에서 같은지 세 가지를 푸시 전에 확인합니다.

파일 용량 상한

파일 크기 제한은 경고, 차단, 브라우저 업로드의 세 단계로 나뉩니다. 50MiB를 넘는 파일은 경고가 표시되지만 푸시는 성공하고, 100MiB를 넘으면 GitHub가 차단합니다. 브라우저에서 직접 올리는 경우의 상한은 25MiB입니다.

용량 때문에 차단되는 파일은 Git Large File Storage로 옮기고, 배포용 바이너리라면 릴리스 기능으로 올려야 합니다. 저장소 전체 크기는 1GB 미만이 권장되고 5GB 미만이 강하게 권장됩니다. 외부 라이브러리를 저장소에 그대로 담으면 이 크기를 빠르게 넘기므로 패키지 관리자를 사용해야 합니다.

상황별 용량 기준과 그 결과를 정리한 표입니다.

푸시 거부 원인과 조치

푸시 실패의 원인은 화면에 표시되는 문구로 구분합니다. 인증을 지적하는 문구는 계정 권한 문제, 원격이 앞서 있다는 문구는 이력 충돌, 파일 크기를 지적하는 문구는 앞 절의 용량 상한 문제입니다.

원격이 앞서 있다는 문구는 README를 추가하면서 생긴 커밋이 로컬에 없을 때 나타납니다. 이 경우 원격 이력을 먼저 받아 합친 뒤 다시 올립니다. 강제 푸시로 덮으면 원격 커밋이 사라지고 복구되지 않으므로, 협업 중인 저장소에서는 사용하지 않아야 합니다.

인증 오류가 반복되면 조직 계정의 권한 정책을 확인해야 합니다. 조직이 특정 인증 방식만 허용하도록 설정한 경우에는 개인 설정과 무관하게 거부되므로 관리자에게 정책 확인을 요청합니다. 회사 저장소에 개인 계정으로 접근하는 경우에도 같은 증상이 나타납니다.

업로드 결과 확인과 대안

푸시가 완료되면 저장소 화면의 파일 목록에 방금 올린 파일이 나타나고, 커밋 개수와 최근 커밋 메시지가 로컬에서 입력한 내용과 일치합니다. 파일 목록은 갱신되었는데 일부 파일이 빠져 있다면 .gitignore 규칙에 걸린 것이므로 해당 규칙을 확인합니다.

터미널을 사용하기 어려운 경우에는 GitHub Desktop 같은 다른 도구로 같은 작업을 화면에서 진행할 수 있고, 파일이 몇 개뿐이라면 웹 화면에서 직접 올리는 방법도 있습니다. 다만 웹 업로드에는 25MiB 상한이 그대로 적용됩니다.