git remote로 원격 저장소 관리하기

Git은 분산 버전 관리 시스템이라서 하나의 프로젝트에 여러 원격 저장소(remote repository)를 연결할 수 있습니다. git remote 명령어는 이런 원격 저장소들을 관리하는 데 사용하는데요. 원격 저장소를 추가하거나, 연결 상태를 확인하거나, 더 이상 필요 없는 원격을 삭제할 때 모두 이 명령어를 씁니다.

원격 저장소 목록 확인

가장 기본적인 사용법은 현재 등록된 원격 저장소의 이름을 확인하는 것입니다.

$ git remote
origin

git clone으로 저장소를 복제하면 기본적으로 origin이라는 이름으로 원격 저장소가 자동 등록됩니다.

-v 옵션을 붙이면 URL까지 함께 볼 수 있습니다.

$ git remote -v
origin  https://github.com/me/my-project.git (fetch)
origin  https://github.com/me/my-project.git (push)

fetch와 push URL이 따로 표시되는데, 대부분의 경우 같은 URL입니다. 특수한 상황에서 fetch와 push를 다른 저장소로 설정할 수 있긴 하지만, 흔한 경우는 아닙니다.

원격 저장소 추가

새로운 원격 저장소를 등록하려면 git remote add 명령어를 사용합니다.

$ git remote add <이름> <URL>

가장 흔한 활용 사례는 오픈소스 프로젝트를 fork했을 때 원본 저장소를 upstream으로 등록하는 것입니다.

$ git remote add upstream https://github.com/original-author/project.git

이렇게 등록하면 원본 저장소의 최신 변경분을 가져올 수 있습니다.

$ git remote -v
origin    https://github.com/me/project.git (fetch)
origin    https://github.com/me/project.git (push)
upstream  https://github.com/original-author/project.git (fetch)
upstream  https://github.com/original-author/project.git (push)

이름은 자유롭게 지을 수 있지만, origin은 내 저장소, upstream은 원본 저장소라는 관례가 있습니다.

원격 저장소 상세 정보

특정 원격 저장소의 상세 정보를 보려면 git remote show 명령어를 사용합니다.

$ git remote show origin
* remote origin
  Fetch URL: https://github.com/me/my-project.git
  Push  URL: https://github.com/me/my-project.git
  HEAD branch: main
  Remote branches:
    main           tracked
    develop        tracked
    feature/login  tracked
  Local branches configured for 'git pull':
    main    merges with remote main
    develop merges with remote develop
  Local refs configured for 'git push':
    main    pushes to main    (up to date)
    develop pushes to develop (local out of date)

원격 저장소의 URL, HEAD 브랜치, 추적 중인 브랜치 목록, pull/push 설정 등을 한눈에 확인할 수 있어서 연결 상태를 점검할 때 유용합니다.

원격 저장소 이름 변경

원격 저장소의 이름을 바꾸려면 git remote rename 명령어를 사용합니다.

$ git remote rename <기존이름> <새이름>

예를 들어 origin을 github로 바꾸고 싶다면 이렇게 합니다.

$ git remote rename origin github
$ git remote -v
github  https://github.com/me/my-project.git (fetch)
github  https://github.com/me/my-project.git (push)

이름이 바뀌면 해당 원격을 참조하는 명령어도 새 이름을 사용해야 합니다. 예를 들어 git push origin main 대신 git push github main이 됩니다.

원격 저장소 삭제

더 이상 필요 없는 원격 저장소를 제거하려면 git remote remove 명령어를 사용합니다.

$ git remote remove <이름>

$ git remote remove upstream
$ git remote -v
origin  https://github.com/me/my-project.git (fetch)
origin  https://github.com/me/my-project.git (push)

원격 저장소를 제거하면 해당 원격과 관련된 추적 브랜치와 설정도 함께 삭제됩니다.

URL 변경

원격 저장소의 URL을 변경해야 할 때가 있습니다. 예를 들어, HTTPS에서 SSH로 전환하거나, 저장소가 다른 조직으로 이전된 경우인데요.

$ git remote set-url origin git@github.com:me/my-project.git

$ git remote -v
origin  git@github.com:me/my-project.git (fetch)
origin  git@github.com:me/my-project.git (push)

HTTPS로 복제한 저장소를 SSH로 바꾸고 싶을 때 이 방법을 자주 사용합니다.

Fork 워크플로우

오픈소스 프로젝트에 기여할 때 git remote는 필수적으로 사용하게 됩니다. 전체 흐름을 정리하면 다음과 같습니다.

# 1. 원본 저장소를 GitHub에서 fork

# 2. 내 fork를 clone
$ git clone https://github.com/me/project.git
$ cd project

# 3. 원본 저장소를 upstream으로 등록
$ git remote add upstream https://github.com/original-author/project.git

# 4. 원본의 최신 변경분을 가져와서 내 main에 반영
$ git fetch upstream
$ git merge upstream/main

# 5. 기능 브랜치에서 작업 후 내 fork에 push
$ git switch -c fix/typo
# ... 작업 ...
$ git push origin fix/typo

# 6. GitHub에서 원본 저장소로 Pull Request 생성

이 워크플로우에서 origin은 내 fork, upstream은 원본 저장소를 가리킵니다. git fetch로 원본의 최신 변경분을 주기적으로 가져와서 내 fork를 최신 상태로 유지하는 게 중요합니다.

기본 push 원격 저장소 설정

원격 저장소가 두 개 이상이면 git push를 실행할 때 어디로 push할지 헷갈릴 수 있는데요. remote.pushDefault 설정을 사용하면 기본 push 대상 원격 저장소를 지정할 수 있습니다.

위처럼 내 fork를 clone한 경우에는 origin이 이미 내 fork이므로 기본값으로도 안전합니다. 하지만 원본 저장소를 직접 clone한 경우에는 origin이 원본을 가리키게 되어 실수로 원본에 push할 수 있어요. 😱

이때 내 fork를 별도로 등록하고 remote.pushDefault를 설정해두면 사고를 방지할 수 있습니다.

$ git remote add fork https://github.com/me/project.git
$ git config remote.pushDefault fork

이렇게 하면 git push를 인자 없이 실행해도 항상 내 fork로 push됩니다. pull은 origin(원본 저장소)에서 받고, push는 fork(내 fork)로 보내는 흐름이 되는 거죠.

Git이 push할 원격 저장소를 결정하는 우선순위는 다음과 같습니다.

1. 현재 브랜치의 branch.<name>.pushRemote 설정
2. remote.pushDefault 설정
3. 현재 브랜치의 트래킹 원격 저장소 (branch.<name>.remote)
4. 위 설정이 모두 없으면 origin

브랜치별로 push할 원격 저장소를 다르게 지정하고 싶다면 pushRemote를 설정하면 돼요.

$ git config branch.my-feature.pushRemote fork

대부분의 프로젝트에서는 원격 저장소가 origin 하나이기 때문에 이 설정을 따로 건드릴 일이 없지만, fork 기반 워크플로우에서는 알아두면 유용합니다.

push.default 설정과의 관계에 대해서는 git push 사용법을 참고하세요.

마치며

git remote는 원격 저장소와의 연결을 관리하는 명령어입니다. 대부분의 프로젝트에서는 origin 하나로 충분하지만, 오픈소스 기여나 여러 환경에서 작업할 때는 원격 저장소를 추가하고 관리하는 방법을 알아두면 큰 도움이 됩니다.

더 자세한 내용은 Git 공식 문서를 참고하세요.