Git push 시 발생하는 non-fast-forward 오류 해결 방법

증상 및 오류 메시지

Git을 사용하다 보면 git push 명령어를 실행할 때 ! [rejected] master -> master (non-fast-forward)와 같은 오류 메시지를 접할 수 있습니다. 이 오류는 로컬 브랜치의 상태가 원격 브랜치보다 뒤처져 있을 때 발생합니다. 즉, 원격 저장소에 이미 다른 커밋이 존재하는데, 로컬 저장소가 이를 반영하지 않고 푸시를 시도했기 때문에 발생하는 문제입니다. 이럴 경우 Git은 데이터 손실을 방지하기 위해 푸시를 거부합니다.

참고 이미지

이미지 출처: https://hanyda.tistory.com/36

원인

이 오류의 주요 원인은 다음과 같습니다:

로컬 브랜치가 원격 브랜치의 최신 상태를 포함하지 않음: 다른 개발자가 원격 브랜치에 커밋을 추가한 경우, 로컬 브랜치가 이를 반영하지 않으면 충돌이 발생합니다.
로컬 저장소와 원격 저장소 간의 이력 불일치: 로컬에서 작업한 내용이 원격 저장소의 내용과 다를 경우, Git은 이를 병합할 수 없다고 판단합니다.

이러한 상황은 특히 팀 프로젝트에서 자주 발생할 수 있습니다. 따라서, 푸시하기 전에 항상 원격 저장소의 변경 사항을 확인하는 것이 중요합니다.

확인 명령어

문제를 확인하기 위해 다음 명령어를 사용할 수 있습니다:

git fetch origin
git status

git fetch 명령어는 원격 저장소의 최신 변경 사항을 로컬로 가져오고, git status 명령어는 현재 로컬 브랜치의 상태를 보여줍니다. 이 명령어를 통해 로컬 브랜치가 원격 브랜치보다 뒤처져 있는지 확인할 수 있습니다.

해결 절차

non-fast-forward 오류를 해결하기 위한 절차는 다음과 같습니다:

원격 저장소의 변경 사항 가져오기: 먼저, 원격 저장소의 변경 사항을 로컬로 가져옵니다.
```
git fetch origin
```
로컬 브랜치와 병합하기: 로컬 브랜치에 원격 브랜치의 변경 사항을 병합합니다.
```
git merge origin/master
```
만약 병합 과정에서 충돌이 발생하면, 충돌을 해결한 후 커밋을 완료해야 합니다.
푸시하기: 병합이 완료되면 다시 푸시를 시도합니다.
```
git push origin master
```

이 과정을 통해 non-fast-forward 오류를 해결할 수 있습니다.

흔한 실수

직접 푸시를 시도하기 전에 pull을 하지 않음: 팀원들이 이미 원격 저장소에 변경 사항을 푸시했을 수 있으므로, 항상 푸시 전에 git pull로 변경 사항을 확인해야 합니다.
충돌 해결을 소홀히 함: 병합 과정에서 발생하는 충돌을 제대로 해결하지 않으면, 이후에도 오류가 발생할 수 있습니다.

재발 방지 체크리스트

정기적으로 원격 저장소의 변경 사항을 확인: git fetch 또는 git pull을 자주 실행하여 원격 저장소의 상태를 확인합니다.
푸시 전 항상 pull 실행: 푸시하기 전에 항상 git pull을 실행하여 로컬 브랜치가 최신 상태인지 확인합니다.
충돌 발생 시 즉시 해결: 충돌이 발생하면 즉시 해결하고 커밋하여 상태를 정리합니다.

이렇게 하면 non-fast-forward 오류를 예방하고, 팀원들과의 협업을 원활하게 진행할 수 있습니다.

실무 적용 체크리스트

Git non-fast-forward rejected 해결을 적용하기 전에 현재 운영 환경의 기준값과 예외 상황을 먼저 정리합니다.
변경 전후로 확인할 지표를 정하고, 문제가 생겼을 때 되돌릴 수 있는 절차를 문서화합니다.
한 번에 모든 서버나 서비스에 적용하기보다 작은 범위에서 검증한 뒤 점진적으로 확대합니다.
담당자, 확인 시간, 장애 판단 기준을 명확히 남겨 같은 문제가 반복될 때 빠르게 대응할 수 있게 합니다.