git checkout 사용법

git checkout은 Git에서 브랜치를 전환하고, 파일을 복원하고, 특정 커밋으로 이동하는 등 다양한 작업을 수행할 수 있는 만능 명령어입니다. 마치 도서관에서 책을 check out, 즉 대여하는 것처럼 특징 브랜치나 커밋의 내용을 작업 디렉토리로 가져온다고 생각하시면 됩니다.

브랜치 전환

가장 기본적인 사용법은 이미 존재하는 브랜치로 전환하는 것입니다.

$ git checkout <브랜치명>

예를 들어, main 브랜치로 전환하려면 다음과 같이 입력합니다.

$ git checkout main
Switched to branch 'main'

feature/user-auth라는 이름의 feature 브랜치로 전환할 수도 있습니다.

$ git checkout feature/user-auth

몇 가지 유용한 팁을 드릴께요.

- 기호를 사용하면 바로 직전에 있던 브랜치로 빠르게 전환할 수 있습니다. 두 브랜치를 자주 오가며 작업할 때 매우 유용합니다.

$ git checkout -

대부분의 최신 쉘 환경에서는 Git 자동 완성이 기본으로 제공됩니다. 우선 브랜치 이름을 입력할 때는 TAB 키를 사용하여 자동 완성 기능을 활용하면 편리합니다.

브랜치 생성 후 전환

git checkout 명령어로 이미 존재하지 않는 브랜치로 전환하려고 하면 다음과 같은 오류가 발생합니다.

$ git checkout unknown
error: pathspec 'unknown' did not match any file(s) known to git

그래서 새로운 브랜치를 만들면서 동시에 해당 브랜치로 전환하려면 -b 옵션을 사용해야합니다.

$ git checkout -b <브랜치명>

예를 들어, feature/login-page라는 새 브랜치를 만들고 바로 전환하려면 다음과 같이 입력합니다.

$ git checkout -b feature/login-page
Switched to a new branch 'feature/login-page'

이는 다음 두 명령어를 한 번에 실행하는 것과 같습니다.

$ git branch feature/login-page
$ git checkout feature/login-page

브랜치 생성, 삭제, 이름 변경 등 브랜치 관리에 대해서는 git branch 사용법에서 자세히 다루고 있으니 참고하세요.

특정 커밋이나 태그로 이동

git checkout은 브랜치뿐만 아니라 특정 커밋으로도 직접 이동할 때도 사용할 수 있습니다. 이전 커밋을 코드를 임시로 확인하거나 테스트할 때 유용하죠.

$ git checkout <커밋-해시>

예를 들어, 특정 커밋을 확인하려면 다음과 같이 입력합니다.

$ git checkout a1b2c3d
Note: switching to 'a1b2c3d'.

You are in 'detached HEAD' state...

태그로도 이동할 수 있습니다.

$ git checkout v1.0.0
Note: switching to 'v1.0.0'.

You are in 'detached HEAD' state...

이때 HEAD 포인터가 브랜치에서 떨어지는 소위 Detached 상태가 됩니다.

최근 커밋으로 이동할 때는 HEAD~ 또는 HEAD^과 같은 표현식을 사용할 수 있습니다.

# 3개 커밋 이전 상태로 이동
$ git checkout HEAD~3

Git에서 HEAD가 무엇을 의미하는지에 대해서는 별도 포스팅에서 자세히 다루고 있으니 참고 바랍니다.

특정 지점에서 브랜치 생성

현재 브랜치가 아닌 다른 브랜치나 특정 커밋이나 태그에서 새로운 브랜치를 따고 싶을 때가 있습니다. 이럴 때는 두 번째 인자에 새로운 브랜치를 시작하고 싶은 지점을 명시해주면 됩니다.

$ git checkout -b <브랜치명> <시작-지점>

예를 들어, v1.2.0 태그를 기반으로 릴리스 브랜치를 만들려면 다음과 같이 입력합니다.

$ git checkout -b release/v1.2.0 v1.2.0

특정 커밋 해시를 기반으로 버그 수정 브랜치를 만들 수도 있습니다.

$ git checkout -b fix/123 a1b2c3d

이 방법은 어떤 피쳐 브랜치에서 작업을 하다가 갑자기 디폴트 브랜치를 기반으로 다른 피쳐 브랜치를 만들어야 할 때 특히 유용합니다.

# 현재 feat1 브랜치에 있음
$ git branch --show-current
feat1
# main 브랜치 기준으로 feat2 브랜치를 생성 후 이동
$ git checkout -b feat2 main

이는 다음 두 명령어를 한 번에 실행하는 것과 같습니다.

$ git checkout main
$ git checkout -b feat2

브랜치 강제 전환

로컬에 커밋하지 않은 변경사항이 있을 때 git checkout 명령어를 실행하면 경고가 발생하면서 브랜치 전환이 되지 않는데요.

$ git checkout main
error: Your local changes to the following files would be overwritten by checkout:
        src/app.js
Please commit your changes or stash them before you switch branches.

이 때 -f 옵션을 사용하면 경고을 무시하고 강제로 브랜치를 전환할 수 있습니다.

$ git checkout -f <브랜치명>

이 옵션을 사용하면 작업 디렉토리(working directory)와 스테이징 영역(staging area)에 있는 모든 변경사항이 영구적으로 손실됩니다. 한번 손실된 변경사항은 복구할 수 없으므로 매우 신중하게 사용해야 하겠습니다.

예를 들어, 현재 브랜치에서 작업한 내용을 버리고 main 브랜치로 전환하려면 다음 명령어를 날리면 됩니다.

$ git checkout -f main

일반적인 상황에서는 변경사항을 커밋한 하거나 git stash로 임시 보관한 후 브랜치 전환하는 것이 권장됩니다.

# 방법 1: 변경사항 커밋
$ git add .
$ git commit -m "Work in progress"
$ git checkout main

# 방법 2: 변경사항 임시 저장
$ git stash
$ git checkout main
$ git checkout -
$ git stash pop

파일 복원

git checkout은 브랜치 전환뿐만 아니라 파일을 이전 상태로 복원하는 데도 사용할 수 있습니다. 작업 디렉토리에서 수정한 파일을 최신 커밋 상태로 되돌리고 싶을 때는 다음과 같이 입력합니다.

$ git checkout -- <파일명>

여기서 -- 기호는 이후에 오는 것이 브랜치명이 아닌 파일명임을 명확히 하기 위해 사용됩니다.

예를 들어, src/app.js 파일의 변경사항을 취소하고 마지막 커밋 상태로 되돌리려면 다음과 같이 실행합니다.

$ git checkout -- src/app.js

특정 커밋이나 브랜치의 파일 상태를 가져올 수도 있습니다. 이 경우 커밋 해시나 브랜치명을 명시하면 됩니다.

$ git checkout <커밋-해시 또는 브랜치> -- <파일명>

예를 들어, main 브랜치의 특정 파일을 현재 브랜치로 가져올 수 있습니다.

$ git checkout main -- README.md

또는 3개 커밋 이전의 config.js 파일을 가져오려면 다음과 같이 입력합니다.

$ git checkout HEAD~3 -- config.js

git checkout의 문제점

git checkout은 오랫동안 Git의 핵심 명령어로 사용되어 왔지만 문제점이 있었습니다. 바로 하나의 명령어가 브랜치 전환, 파일 복원, HEAD 분리 등 너무 다양한 용도로 쓰인다는 것이 였는데요.

이로 인해 의도하지 않은 작업을 실수로 수행할 가능성이 높고, 복잡한 옵션 구조로 인해 학습 곡선도 다른 명령어에 비해서 가파른 편입니다.

예를 들어, 다음과 같은 상황에서 혼란이 발생할 수 있습니다.

# 브랜치로 전환하려고 했는데...
$ git checkout feature

# feature라는 파일이 존재하면 실수로 파일을 복원할 수도 있음
$ git checkout feature.js

이러한 문제를 해결하기 위해 Git 2.23 버전(2019년 8월)부터는 git checkout의 기능을 두 개의 명령어로 분리되었습니다. 브랜치 전환은 git switch가, 파일 복원은 git restore가 전담하도록 한 것입니다.

자주 사용되는 git checkout 명령어를 git switch나 git restore 명령어로 재작성해보면 다음과 같습니다.

작업	git checkout	현대적 방식
브랜치 전환	git checkout main	git switch main
브랜치 생성 및 전환	git checkout -b new	git switch -c new
Detached HEAD	git checkout <커밋>	git switch --detach <커밋>
특정 지점에서 생성	git checkout -b new v1.0.0	git switch -c new v1.0.0
강제 전환	git checkout -f main	git switch -f main
파일 복원	git checkout -- file.js	git restore file.js

git switch 명령어의 구체적인 사용법은 관련 포스팅을 참고하세요.

git restore 명령어의 구체적인 사용법은 관련 포스팅을 참고하세요.

마치며

지금까지 한 때는 Git에서 가장 많이 사용되었지만 이제는 레거시(legacy) 명령어가 된 git checkout에 대해서 살펴보았습니다. git checkout은 하위 호환성 때문에 앞으로도 계속 지원되겠지만, 가급적 git switch와 git restore를 사용해보시려고 노력하시면 좋을 것 같습니다.

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