1 GitHub 기본 기능 정리

프로젝트를 시작할 때 보통 github에서 repository를 생성 후 로컬에서 clone을 한 후 개발을 시작한다.
하지만, 간혹가다 local에서 작업한 것을 github에 올리는 경우도 종종 있다.
이번 블로그에서 local 폴더를 github repository와 연결하는 내용을 정리한다.

1.1 Git 초기화 (git init)

로컬에서 프로젝트 폴더를 만들고 버전 관리를 시작할 때 git init을 사용한다.
이 명령은 해당 디렉토리에 .git 폴더를 생성해 Git으로 관리할 준비를 한다.

git init

Initialized empty Git repository in /Users/user/my-project/.git/

.git 폴더가 이미 존재할 때 다시 실행하면:

Reinitialized existing Git repository in /Users/user/my-project/.git/

“Reinitialized”가 뜨면 기존 버전 관리 정보가 그대로 보존된 채로 재초기화된 것이다. 커밋 히스토리나 설정이 삭제되지 않으므로 걱정하지 않아도 된다.

1.2 원격 저장소 연결 (Remote Add)

로컬 저장소와 GitHub 원격 저장소를 연결하려면 다음 명령을 사용한다.

git remote add origin https://github.com/username/repo-name.git

성공하면 아무 출력도 나오지 않는다. 연결이 됐는지 확인하려면:

git remote -v

origin  https://github.com/username/repo-name.git (fetch)
origin  https://github.com/username/repo-name.git (push)

fetch 와 push 두 줄이 나타나면 원격 저장소 연결이 정상이다. fetch 는 원격에서 가져오는 주소, push 는 원격에 올리는 주소이다. 보통 같은 주소를 사용한다.

이 과정에서 로컬 Git과 GitHub 저장소가 연결되고 push/pull이 가능해진다.

1.3 브랜치와 기본 브랜치(main/master)

GitHub는 기본적으로 main 브랜치를 사용한다.
반면 일부 로컬 환경은 여전히 master를 기본으로 사용할 수 있다.
이 둘이 서로 다른 경우 push 시 충돌이 발생할 수 있다.
master와 main은 깃 저장소의 기본 브랜치 이름의 변화다.
- 기능적 차이는 전혀 없고, 이름만 다른 동일한 개념이다.
- 원래 기본 브랜치는 master: GitHub, GitLab 등 대부분의 플랫폼은 오랫동안 기본 브랜치를 master로 설정했다.
- 2020년 이후 기본 브랜치를 main으로 전환
- 더 중립적이고 직관적인 용어 사용을 선호하는 방향으로 정책이 바뀌었기 때문이다.
- 지금 GitHub에서 새로운 리포를 만들면 기본 브랜치는 보통 main이다.

1.3.1 관련 기능

기존 master를 main으로 바꾸고 싶다면 브랜치 이름을 변경한다.

git branch -m master main

성공하면 아무 출력도 없다. git branch 를 입력해 이름이 바뀐 것을 확인할 수 있다:

* main

git push -u origin main

Enumerating objects: 12, done.
Counting objects: 100% (12/12), done.
Delta compression using up to 8 threads
Compressing objects: 100% (8/8), done.
Writing objects: 100% (12/12), 3.21 KiB | 3.21 MiB/s, done.
Total 12 (delta 1), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), done.
To https://github.com/username/repo-name.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

Branch 'main' set up to track remote branch 'main' from 'origin'. 줄이 나타나면 -u 옵션이 정상 동작한 것이다. 이후 git push 만 입력해도 origin main 으로 자동 전송된다.

git push origin --delete master

To https://github.com/username/repo-name.git
 - [deleted]         master

[deleted] 줄이 나타나면 원격의 master 브랜치가 삭제된 것이다.

git push -u origin main
- 여기서 -u는 upstream 브랜치를 설정해 이후 push 명령을 단순화해준다.

1.4 Remote 관리 기능

원격 저장소 주소가 잘못되었거나 변경이 필요할 때 사용하는 기능은 다음과 같다.

원격 주소 확인: git remote -v
주소 변경: git remote set-url origin <repository URL>
기존 원격 삭제: git remote remove origin

# 주소가 잘못 등록된 경우 확인
git remote -v

origin  https://github.com/username/wrong-repo.git (fetch)
origin  https://github.com/username/wrong-repo.git (push)

# 주소 변경
git remote set-url origin https://github.com/username/correct-repo.git
git remote -v

origin  https://github.com/username/correct-repo.git (fetch)
origin  https://github.com/username/correct-repo.git (push)

set-url 은 성공해도 출력이 없다. git remote -v 로 변경된 주소를 재확인하는 것이 좋다.

2 실제로 발생한 문제 및 해결 과정

2.1 상황

로컬에서 먼저 디렉토리를 생성한 뒤 GitHub 저장소를 나중에 만든 상황
프로젝트 디렉토리를 먼저 만들고 GitHub에 저장소를 나중에 생성했기 때문에, 로컬 Git 구조가 GitHub 저장소와 자연스럽게 연결되지 않았다.

2.2 이미 `.git` 폴더가 존재해 `git init`을 다시 실행해도 새로 초기화되지 않음

로컬에 git init을 실행해 .git을 만들어준다.
만약 로컬 폴더에 .git 디렉토리가 남아 있는 경우 git init 실행 시 “Reinitialized” 메시지가 표시된다.
이는 기존 버전 관리 정보가 그대로 존재한다는 뜻이다.

2.3 `git remote add origin` 명령을 실행했을 때 오류 발생할 경우

기존에 존재하던 origin 항목 때문에 다음 오류가 발생할 수 있다.

error: remote origin already exists.

이는 이전에 잘못 연결된 origin 정보가 남아 있던 것이 원인이다.

2.4 해결 방식

2.4.1 원격 저장소 정보 확인

git remote -v

origin  https://github.com/username/old-repo.git (fetch)
origin  https://github.com/username/old-repo.git (push)

잘못된 URL이 등록되어 있는 것을 확인할 수 있다.

2.4.2 기존 origin 삭제 또는 주소 변경

둘 중 하나를 선택해 해결할 수 있다.

2.4.2.1 방법 A: 주소 변경

git remote set-url origin https://github.com/kmink3225/agent.git

성공 시 출력 없음. 이후 git remote -v 로 변경됐는지 확인한다.

2.4.2.2 방법 B: origin 삭제 후 재등록

git remote remove origin  
git remote add origin https://github.com/kmink3225/agent.git

두 명령 모두 성공 시 출력 없음. git remote -v 로 새 주소가 등록됐는지 확인한다:

origin  https://github.com/kmink3225/agent.git (fetch)
origin  https://github.com/kmink3225/agent.git (push)

2.4.3 브랜치 정리

로컬이 master, GitHub 기본 브랜치는 main이어서 충돌 위험이 있었다. 이를 정리했다.

git branch -m master main

성공 시 출력 없음. git branch 로 브랜치 이름이 main 으로 바뀐 것을 확인한다.

2.4.4 GitHub로 최종 업로드

git push -u origin main

To https://github.com/kmink3225/agent.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'.

2.5 자주 발생하는 에러와 해결법

2.5.1 `fatal: The current branch main has no upstream branch`

$ git push
fatal: The current branch main has no upstream branch.
To push the current branch and set the remote as upstream, use

    git push --set-upstream origin main

-u 옵션 없이 push를 처음 시도하면 발생한다. Git이 메시지 안에 해결 명령어를 직접 알려준다:

git push --set-upstream origin main
# 또는 짧게
git push -u origin main

2.5.2 `fatal: repository 'https://...' not found`

$ git push origin main
fatal: repository 'https://github.com/username/typo-repo.git/' not found

URL이 잘못됐거나 저장소가 삭제된 경우이다. GitHub에서 저장소 URL을 복사해 git remote set-url origin <올바른URL> 로 수정한다.

2.5.3 `error: src refspec main does not match any`

$ git push origin main
error: src refspec main does not match any
error: failed to push some refs to 'https://github.com/username/repo.git'

로컬에 main 브랜치가 존재하지 않을 때 발생한다. git branch 로 현재 브랜치 이름을 확인하고, 브랜치가 master 인 경우 git branch -m master main 으로 이름을 바꾼 뒤 push한다.