Git pull이 거부될 때: 갈라진 브랜치 확인과 merge·rebase·ff-only 선택 기준

Git pull이 거부될 때는 로컬과 원격 브랜치의 커밋이 갈라졌는지부터 확인해야 한다. 오류를 없애려고 전역 설정부터 바꾸면 저장소의 협업 규칙과 다른 방식으로 이력을 통합할 수 있다. 먼저 변경 상태와 커밋 관계를 확인한 뒤 merge·rebase·ff-only 중 맞는 방법을 선택하는 순서가 안전하다.

1. Git pull 오류 문구와 작업 상태부터 확인하기

git pull은 원격 변경을 가져오는 fetch를 실행한 다음, 가져온 브랜치를 현재 브랜치에 통합하는 명령이다. 따라서 pull 실패가 곧 다운로드 실패를 뜻하지는 않는다. fetch는 끝났지만 이후 이력 통합 단계에서 멈췄을 수 있다.

대표적인 오류인 Not possible to fast-forward, aborting.은 현재 조건에서 fast-forward로 통합할 수 없다는 뜻이다. 원격에만 새 커밋이 있으면 브랜치 포인터를 앞으로 옮기면 되지만, 로컬과 원격 양쪽에 서로 다른 커밋이 생겼다면 그 방식만으로는 합칠 수 없다.

2026년 기준으로 제시된 Git 공식 git-pull 2.55.0 문서는 통합 방식을 따로 지정하지 않았을 때 fast-forward 전용 동작을 기본으로 설명한다. 다만 설치 버전과 기존 설정에 따라 실제 동작이나 안내 문구가 달라질 수 있으므로 다음 명령으로 환경부터 확인한다.

git --version
git status
git branch -vv
git remote -v

git status에서 커밋하지 않은 변경이나 이미 진행 중인 merge·rebase가 있는지 살핀다. 작업 중인 변경은 내용을 확인한 뒤 커밋하거나 필요한 경우 stash로 보관한다. 이미 통합 작업이 진행 중이라면 새 pull을 반복하기보다 해당 작업을 마치거나 중단하는 것이 먼저다.

아래 예시는 현재 체크아웃한 브랜치가 main이고, 통합 대상이 origin/main인 상황을 전제로 한다. 실제 대상이 origin/develop이라면 확인 명령과 pull 인자도 그에 맞게 바꿔야 한다. 특히 git pull origin main은 main으로 이동하는 명령이 아니라, 원격 main을 현재 브랜치에 통합하는 명령이다.

Git pull이 거부될 때: 갈라진 브랜치 확인과 merge·rebase·ff-only 선택 기준

2. 갈라진 브랜치 확인: fetch와 좌우 커밋 비교

로컬의 원격 추적 브랜치는 마지막으로 가져온 시점의 상태를 담는다. 따라서 분기 여부를 판단하기 전에 fetch로 갱신해야 한다. 이 단계는 원격 추적 정보를 업데이트하며, 현재 브랜치에 변경을 통합하지 않는다.

git fetch origin
git log --left-right --graph --oneline HEAD...origin/main
git rev-list --left-right --count HEAD...origin/main

HEAD...origin/main은 양쪽 중 한쪽에만 존재하는 커밋을 비교한다. Git 공식 git-log 문서에 따르면 <는 왼쪽인 로컬 HEAD에만 있는 커밋, >는 오른쪽인 origin/main에만 있는 커밋이다. 양쪽 표시가 모두 나오면 커밋 이력이 갈라진 상태다.

개수를 보는 명령도 같은 방향으로 읽는다. 예를 들어 2 3이라는 출력은 로컬에만 2개, 원격 추적 브랜치에만 3개의 커밋이 있다는 뜻이다. 이는 명령 해석을 위한 예시이며, 실제 개수는 각 저장소의 출력으로 확인해야 한다.

  • 왼쪽 0, 오른쪽 1 이상: 로컬이 뒤처져 있어 fast-forward로 따라갈 수 있다.
  • 왼쪽 1 이상, 오른쪽 0: 로컬만 앞서 있다. 비교한 원격 브랜치에서 새로 통합할 커밋은 없다.
  • 양쪽 모두 1 이상: 분기 상태다. merge 또는 rebase 선택이 필요하다.
  • 양쪽 모두 0: 두 참조가 같은 커밋을 가리킨다.

여기서 “로컬에만 있다”는 표현은 지금 비교한 origin/main에는 없다는 뜻이다. 다른 원격 브랜치에 이미 push했거나 동료가 가져간 커밋일 수도 있으므로, 이 결과만으로 미공유 커밋이라고 판단해서는 안 된다.

3. merge·rebase·ff-only 선택 기준과 실행 명령

세 방식의 차이는 새 커밋을 받아오는 속도보다 기존 이력을 어떻게 유지하고 연결하는가에 있다. ff-only는 포인터 이동만 허용하고, merge는 분기된 이력을 합치며, rebase는 로컬 커밋을 새 기준 위에 다시 적용한다.

판단 항목 merge rebase ff-only
실행 옵션 --no-rebase --rebase --ff-only
분기된 이력 merge 커밋으로 연결 로컬 커밋 재적용 통합 거부
기존 커밋 해시 유지 재작성 시 변경 유지
적합한 상황 공유 이력과 분기 관계 보존 미공유 작업의 선형 정리 단순히 원격을 따라가기
주의점 분기 시 merge 커밋 생성 공유 커밋 재작성 주의 분기를 자동 해결하지 않음

원격 변경만 따라가려면 ff-only

git pull --ff-only origin main

로컬에 독자적인 커밋이 없을 때 적합하다. 분기 상태에서는 실패하므로, 예상하지 못한 merge 커밋이나 이력 재작성을 막는 확인 장치로도 쓸 수 있다. 실패했다면 같은 명령을 반복하기보다 앞 단계의 커밋 비교로 돌아간다.

공유된 커밋 관계를 보존하려면 merge

git pull --no-rebase origin main

일반적인 --ff 동작에서는 fast-forward가 가능하면 포인터만 이동하고, 이력이 갈라졌으면 merge 커밋을 만든다. 따라서 merge 방식을 선택했다고 항상 새 merge 커밋이 생기는 것은 아니다. 기존 커밋을 다시 만들지 않아 공유 브랜치의 관계를 보존하기에 적합하다.

기존에 pull.ff=only가 설정되어 있다면 그 조건도 확인해야 한다. 이번 실행에서 fast-forward 전용 제약을 해제하고 merge 방식을 쓰기로 결정했다면 git -c pull.ff=true pull --no-rebase origin main처럼 실행 범위의 설정을 명시할 수 있다.

아직 공유하지 않은 커밋을 정리하려면 rebase

git pull --rebase origin main

rebase는 원격 변경을 기준으로 로컬 작업을 다시 적용해 선형 이력을 만들 때 유용하다. 다만 재적용된 커밋은 부모 관계가 달라지므로 해시도 달라질 수 있다. Git 공식 문서가 공개한 이력에 대한 rebase를 주의하라고 설명하는 이유다.

실무 판단에서 먼저 볼 것은 커밋의 공유 여부다. 개인 작업 브랜치라도 이미 동료가 그 커밋을 기반으로 작업하고 있다면 재작성의 영향이 생긴다. 반대로 아직 공유하지 않은 변경이고 팀이 선형 이력을 요구한다면 rebase가 자연스러운 선택이 될 수 있다.

4. git config 설정 범위와 충돌하는 기본값 점검

한 번의 오류를 해결하는 옵션과 앞으로 계속 사용할 기본값은 구분해야 한다. Atlassian 지원 문서도 merge·rebase·fast-forward 전용 설정을 안내하지만, 어느 방식을 저장할지는 저장소의 작업 규칙에 맞춰 결정해야 한다.

git config --show-origin --get-all pull.rebase
git config --show-origin --get-all pull.ff
git config --show-origin --get-regexp '^branch\..*\.rebase$'

--show-origin은 설정이 어느 파일에서 왔는지 함께 보여준다. 조회 결과가 없으면 해당 항목이 명시적으로 설정되지 않았을 수 있다. 브랜치별 rebase 설정도 영향을 줄 수 있어 pull 설정 두 줄만 확인하고 판단하지 않는 편이 좋다.

다음은 저장소 안에서 실행하는 기본값 설정 예시다. 세 줄을 모두 실행하는 절차가 아니라, 원하는 정책에 맞는 항목을 선택하는 예시다. 특히 pull.rebase와 pull.ff는 별도 항목이므로 하나를 바꿨다고 다른 설정까지 없어지지는 않는다.

# merge 방식 선택
git config --local pull.rebase false

# rebase 방식 선택
git config --local pull.rebase true

# fast-forward 전용 조건 설정
git config --local pull.ff only

--local은 현재 저장소에 적용되며, 저장소 안에서 범위를 생략한 설정 쓰기도 기본적으로 로컬 설정을 사용한다. --global은 해당 사용자 계정의 다른 저장소에도 기본값으로 영향을 준다. 프로젝트마다 통합 규칙이 다르다면 저장소별 설정이 더 적합하다.

💡 참고: 개인의 로컬 설정은 저장소를 clone한 동료에게 자동 배포되지 않는다. 팀의 merge·rebase 정책은 기여 문서나 개발 안내에도 적어야 같은 오류와 설정 혼선을 줄일 수 있다.

운영 관점에서 유용한 기준은 일회성 판단을 전역 정책으로 확대하지 않는 것이다. 우선 실행 옵션으로 해당 상황을 해결하고, 반복되는 작업 방식과 팀 규칙이 확인된 뒤 저장소 기본값을 정하면 다른 프로젝트에 미치는 영향을 줄일 수 있다.

5. Git pull 충돌 해결과 merge·rebase 중단 방법

fast-forward 불가와 파일 충돌은 다른 문제다. 전자는 브랜치 포인터 이동만으로 통합할 수 없다는 뜻이고, 후자는 merge나 rebase 과정에서 변경 내용을 자동으로 합치지 못했다는 뜻이다. 통합 방식을 선택한 뒤 충돌이 생겼다면 git status로 현재 진행 상태를 확인한다.

merge 충돌을 해결하거나 중단하기

충돌 파일의 내용을 정리하고 해결한 파일을 stage에 올린 뒤 merge를 계속한다. 아래의 path/to/file은 실제로 해결한 파일 경로로 바꿔야 한다. 파일이 여러 개라면 각각 확인해 추가한다.

git status
git add path/to/file
git merge --continue

현재 merge를 취소하려면 다음 명령을 사용한다. 다만 통합 전부터 커밋하지 않은 변경이 있었다면 원래 상태를 완벽히 복구하기 어려울 수 있어, 시작 전 작업 상태 정리가 중요하다.

git merge --abort

rebase 충돌을 해결하거나 중단하기

rebase는 커밋을 순서대로 재적용하므로 서로 다른 단계에서 충돌이 반복될 수 있다. 각 단계에서 내용을 해결하고 stage에 올린 뒤 계속한다. 현재 커밋을 건너뛰는 --skip은 변경을 제외할 수 있으므로 단순한 충돌 해결용으로 사용하지 않는다.

git add path/to/file
git rebase --continue

# 현재 rebase 전체 중단
git rebase --abort

중단 명령은 아직 진행 중인 통합 작업에 사용한다. 이미 완료한 merge나 rebase를 되돌리는 절차와는 다르다. 공유 이력을 rebase한 뒤 push가 거부되더라도 강제 push부터 실행하지 말고, 영향을 받는 브랜치와 공동 작업자의 사용 여부를 먼저 확인해야 한다.

6. Git pull 재시도 전후에 확인할 실전 체크리스트

  1. 현재 위치 확인: 브랜치, upstream, 커밋하지 않은 변경을 확인한다.
  2. 원격 상태 갱신: git fetch origin을 실행하고 실제 통합 대상과 비교한다.
  3. 분기 판단: 좌우 로그와 커밋 개수로 한쪽만 앞섰는지 양쪽이 갈라졌는지 확인한다.
  4. 통합 방식 결정: 단순 추적은 ff-only, 공유 이력 보존은 merge, 미공유 커밋 정리는 팀 규칙에 따라 rebase를 선택한다.
  5. 완료 결과 점검: git status와 최근 로그를 확인하고 프로젝트의 관련 테스트나 빌드를 실행한다.

통합이 끝난 뒤에는 git log --graph --oneline -n 15처럼 최근 이력을 확인하면 의도한 형태로 연결됐는지 살피기 쉽다. Git이 충돌 없이 합쳤다고 애플리케이션의 동작까지 검증된 것은 아니므로, 변경된 기능에 맞는 확인도 필요하다.

Git pull 거부를 해결하는 핵심은 오류 문구를 없애는 설정 한 줄이 아니라, 커밋 관계와 공유 범위를 확인하는 순서다. 원격을 갱신하고 분기 상태를 읽은 뒤 통합 방식을 명시하면, 기존 작업을 보존하면서 다음 행동을 결정할 수 있다.

근거: Git 공식 git-pull 문서 2.55.0의 fetch 후 통합 동작, --rebase·--no-rebase·--ff-only 및 충돌 중단 설명, Git 공식 git-log 문서의 --left-right 설명, Atlassian Bitbucket Cloud 지원 문서의 divergent branches 설정 안내. 커밋 개수 예시는 명령 해석을 위한 것으로, 이용률이나 성능 통계가 아니다.