GitHub 기초 & 원격 연계 매뉴얼

로컬에서 도는 git과 웹 플랫폼 GitHub가 어떻게 이어지는지 — 저장소를 만들고, 잇고, 올리고 받는 기본기  |  공식 문서: docs.github.com

개념 한눈에 보기

이 섹션의 핵심은 로컬 git(내 PC의 도구)과 원격 GitHub(웹 플랫폼)가 어떻게 이어지는지다. 같은 저장소가 두 곳에 존재하며, 원격은 관례상 origin이라는 이름으로 연결된다. 둘을 잇는 다리가 clone(처음 복제)·push(올리기)·pull·fetch(받기)다. 다루는 도구는 웹 화면·gh CLI·GitHub Desktop 세 갈래다.

로컬 git ↔ 원격 GitHub(origin)
│
├── 로컬 (내 PC, git 도구)
│   ├── git init / git add / git commit       인터넷 없이 커밋·이력 관리
│   └── .git 폴더                              내 커밋이 쌓이는 곳
│
├── 잇는 다리 (동기화 명령)
│   ├── git clone <url>             원격을 처음 통째로 복제(origin 자동 설정)
│   ├── git remote add origin <url>  로컬 저장소에 원격 주소를 연결
│   ├── git push                    로컬 커밋을 원격으로 올리기
│   └── git fetch / git pull        원격 변경을 받기 / 받아 합치기
│
├── 원격 (GitHub 서버, 웹 플랫폼)
│   ├── 저장소 (Repository)                    코드·파일·이력을 담는 한 단위
│   ├── 가시성: public / private              인터넷 누구나 / 나·공유 대상만
│   └── README.md · Add file · 협업 기능       웹에서만 되는 일(공개·백업·협업)
│
└── 다루는 도구
    ├── 웹 브라우저                            New repository·Add file로 GUI 작업
    ├── gh CLI                          터미널에서 gh repo create/clone 등
    └── GitHub Desktop                       명령줄 없이 쓰는 무료 GUI 앱

1. GitHub와 원격 저장소란?

로컬에서 하는 일 vs 웹에서만 되는 일

둘의 경계를 분명히 알면 "왜 커밋했는데 GitHub에 안 보이지?" 같은 혼란이 사라진다. 로컬은 git 도구로 혼자 처리하는 영역, 웹은 인터넷에 올라가야만 되는 영역이다.

이 문서에서 배우는 것

• 저장소 생성: 웹 New repository·gh repo create로 원격 저장소 만들기(Public/Private).
• 원격 연결: clone·gh repo clone·remote add origin으로 로컬과 잇기.
• 동기화: push·fetch·pull로 올리고 받기.
• 도구·웹: gh 설치·인증, GitHub Desktop, 웹 편집·README 마크다운.

※ Pull Request·이슈·코드 리뷰는 협업 매뉴얼, 인증 상세(SSH·PAT)·보안은 보안 매뉴얼, 브랜치는 브랜치 매뉴얼, 로컬 커밋 기본기는 git 기초 매뉴얼에서 다룬다.

2. 저장소 생성·가시성

New repository — 웹 화면에서 빈 저장소 만들기

로컬 git을 쓰지 않아도 브라우저만으로 원격 저장소를 만들 수 있다. 우상단의 + 버튼에서 New repository를 선택하고 Owner(소유 계정)와 이름을 정한 뒤, 공개 범위와 초기 파일 옵션을 고르면 끝이다. 처음 입문하는 바이브 코더에게 가장 부담이 적은 방법이다.

1. Owner·이름: 소유 계정을 고르고 저장소 이름을 입력한다(이름은 최대 100자).
2. 가시성: Public 또는 Private 중 하나를 선택한다.
3. 초기 파일: README·.gitignore·라이선스를 체크하면 빈 저장소가 아니라 바로 내용이 있는 상태로 시작된다.
4. 생성: Create repository 버튼을 눌러 마무리한다.

gh repo create — 터미널에서 원격 저장소 생성

GitHub CLI로 저장소를 만들면 생성·클론·푸시를 한 번에 처리할 수 있다. 인자 없이 실행하면 대화형으로 묻고, 옵션을 붙이면 한 줄로 끝난다. 특히 --source=.로 현재 로컬 폴더를 가리키고 --push를 붙이면 손에 있는 프로젝트를 즉시 원격으로 올릴 수 있다.

# 새 public 저장소를 만들고 곧바로 로컬에 클론
gh repo create my-project --public --clone

# 현재 폴더(.)를 private 저장소로 만들고 origin으로 연결한 뒤 push
gh repo create my-project --private --source=. --remote=origin --push

--public / --private — 공개 범위 결정

gh repo create의 가시성 플래그다. 셋 중 하나를 지정한다. 웹에서 만들 때 라디오 버튼을 고르는 것과 같은 선택이며, 생성 후에도 저장소 설정에서 바꿀 수 있다.

gh repo create 주요 옵션 — 설명·템플릿·초기 파일

생성과 동시에 설명, .gitignore, 라이선스, README를 붙이거나, 다른 저장소를 템플릿 삼아 시작할 수 있다. 자주 쓰는 플래그를 묶어 정리하면 다음과 같다.

💡 핵심 한 줄: 이미 만들던 로컬 프로젝트가 있다면 --source=. --remote=origin --push 조합으로 한 번에 원격까지 올린다.

3. 원격 연결 (clone · remote)

git clone — 원격 저장소를 통째로 복제

원격 저장소의 전체 이력을 포함한 사본을 로컬로 가져온다. 저장소의 Code 버튼에서 URL을 복사해 사용하며, 클론한 순간 그 원격이 자동으로 origin 이름으로 연결된다(별도 init·remote add 불필요). AI에게 코드를 수정시키려면 먼저 이 단계로 손에 코드를 가져와야 한다.

# 저장소 Code 버튼에서 복사한 URL을 그대로 사용
git clone https://github.com/OWNER/REPO.git
git clone https://github.com/OWNER/REPO.git my-folder   # 다른 폴더명으로 받기

gh repo clone — 단축 클론과 자동 remote 구성

전체 URL 대신 OWNER/REPO 형식만으로 클론한다. OWNER/를 생략하면 본인 계정의 저장소로 간주한다. 포크한 저장소를 클론하면 부모 저장소가 upstream이라는 이름으로 자동 추가되어, 원본의 최신 변경을 따라가기 쉽다.

# 공개 저장소 단축 클론
gh repo clone cli/cli

# git 옵션은 -- 뒤에 전달 (예: 얕은 클론)
gh repo clone cli/cli -- --depth=1

git remote -v — 연결된 원격 확인

현재 저장소가 어떤 원격에 연결돼 있는지, 그 URL이 무엇인지 보여 준다. 올리기 전에 '어디로 올라가는지' 확인할 때 유용하다.

git remote -v
# origin  https://github.com/OWNER/REPO.git (fetch)
# origin  https://github.com/OWNER/REPO.git (push)

git remote add origin — 로컬에 원격 연결하기

이미 로컬에 있는 저장소(git init으로 시작한 폴더 등)에 원격 주소를 origin이라는 이름으로 연결한다. GitHub에 빈 저장소를 만든 뒤 그 URL을 붙이는 흐름이며, 연결한 주소를 나중에 바꾸려면 git remote set-url을 쓴다.

# 원격을 origin으로 연결
git remote add origin https://github.com/OWNER/REPO.git

# 연결된 주소 변경
git remote set-url origin https://github.com/OWNER/NEW-REPO.git

💡 핵심 한 줄: git clone·gh repo clone은 origin을 자동으로 잡아 주므로, git remote add origin은 "로컬에서 먼저 만든 저장소"를 원격에 붙일 때 쓴다.

4. 올리고 받기 (push · fetch · pull)

여기가 git ↔ GitHub 동기화의 심장이다. 로컬 커밋을 원격으로 올리고(push), 원격 변경을 로컬로 받는다(fetch·pull).

git push — 로컬 커밋을 원격에 올리기

내 컴퓨터에 쌓인 커밋을 원격(origin)으로 업로드한다. 처음 올릴 때는 -u origin main으로 업스트림(추적 관계)을 설정한다. 한 번 설정해 두면, 이후로는 git push만 쳐도 같은 곳으로 올라간다.

git push -u origin main   # 처음 한 번: 업스트림 설정하며 올리기 (-u = --set-upstream)
git push                  # 이후엔 인자 없이 올리기

git fetch — 받아 두기만(합치지 않음)

원격에 새로 올라온 커밋을 내 컴퓨터로 내려받기만 한다. 내가 작업 중인 브랜치와는 합치지 않으므로, 무엇이 새로 들어왔는지 안전하게 먼저 확인할 때 쓴다.

git fetch origin                    # 원격의 새 커밋을 가져오되, 작업에는 손대지 않음
git fetch origin && git merge origin/main   # 확인한 뒤 직접 병합

git pull — 받아서 합치기 (fetch + merge)

원격의 변경을 받아 현재 브랜치에 곧바로 합친다. 즉 git fetch 후 git merge를 한 번에 하는 명령이다. 업스트림이 설정돼 있으면 인자 없이 git pull만으로 동작하며, --rebase를 쓰면 병합 커밋 대신 내 커밋을 원격 위로 재배치해 이력을 선형으로 유지한다.

git pull             # 원격 변경을 받아 현재 브랜치에 합치기 (= fetch + merge)
git pull --rebase    # 병합 대신 리베이스로 통합(선형 이력)

5. 도구 설치·인증

brew install gh / winget install — GitHub CLI 설치

GitHub CLI(gh)는 터미널에서 GitHub를 다루는 공식 도구다. 운영체제별 패키지 관리자로 설치하며, 설치 후에는 gh auth login으로 한 번 인증해야 한다.

gh auth login — GitHub CLI 인증

설치한 gh를 내 GitHub 계정과 연결한다. 기본은 웹 브라우저 방식으로, 안내에 따라 브라우저에서 로그인하면 자격 증명이 시스템 자격 증명 저장소에 안전하게 저장된다. 인증을 마쳐야 gh repo create 같은 명령이 동작한다.

# 브라우저 인증 플로우로 로그인
gh auth login --web

※ SSH 키 생성·등록, Personal Access Token(PAT) 발급 등 인증 방식의 상세는 보안 매뉴얼에서 다룬다.

GitHub Desktop — 명령줄 없는 GUI 대안

명령줄이 부담스러운 입문자를 위한 무료·오픈소스 GUI 앱이다(Windows·macOS). 클론, 브랜치 만들기, 커밋(변경 줄을 골라 담거나 공동작성자 추가), 푸시, PR 체크아웃을 화면에서 클릭만으로 처리한다. 터미널 대신 시각적으로 git을 익히고 싶을 때 좋은 출발점이다.

웹 UI gh CLI GitHub Desktop 입문자 친화

6. 웹 편집·README

Add file → Upload files — 웹에서 파일 올리기

로컬 git 없이 브라우저에서 파일을 올린다. 저장소 화면의 Add file → Upload files로 들어가 파일을 드래그앤드롭하고 커밋하면 된다. 다만 브라우저 업로드에는 용량·개수 제한이 있다.

• 경로: 저장소 → Add file → Upload files → 드래그앤드롭 → 커밋
• 제한: 파일당 25 MiB, 한 번에 최대 100개
• 큰 파일: 제한을 넘으면 명령줄(git) 또는 Git LFS를 사용

Add file → Create new file — 웹에서 파일 생성·편집

업로드 대신 브라우저에서 직접 새 파일을 만들거나 기존 파일을 고칠 수 있다. Add file → Create new file로 새 파일을 작성하고, 기존 파일은 우측 상단 연필 아이콘으로 편집한 뒤 커밋한다. 웹에서 누른 "Commit changes"는 곧 로컬에서 git add + git commit을 한 것과 같은 결과를 원격에 남기므로, 로컬 git이 없어도 이력이 차곡차곡 쌓인다.

README.md — 저장소 홈에 표시되는 설명서

README는 저장소 홈 화면 아래에 자동으로 렌더링되는 마크다운 문서다. .github, 루트, docs 중 한 곳에 있으면 표시되며, 여러 곳에 있으면 .github → 루트 → docs 순서로 우선한다. 프로젝트가 무엇이고 어떻게 쓰는지 가장 먼저 보여 주는 얼굴이다.

# 제목

**굵게**, *기울임*, `인라인 코드`

- 목록 항목
- [링크](https://example.com)
- ![이미지](image.png)

> 인용문

```
코드 블록
```

참고 링크

• 📖 GitHub Docs — Repositories
• 🚀 GitHub Docs — Get started
• ⚙️ GitHub CLI Manual — gh repo create
• ⚙️ GitHub CLI Manual — gh repo clone
• ⚙️ GitHub CLI Manual — gh auth login
• 🔗 git push 공식 문서 · git pull 공식 문서
• 📝 이 섹션의 실습 예시로 이동

GitHub 웹/CLI · gh 2.x 기준 | 2026년 6월