Git restore 사용법

Git restore 사용법

git restore는 작업 트리 파일이나 스테이징 영역의 내용을 특정 기준 상태로 되돌릴 때 쓰는 명령이다. 2026년 6월 26일 기준 Git 공식 문서는 기본적으로 작업 트리는 index에서, --staged를 주면 index는 HEAD에서 복원된다고 설명한다.

실무에서 핵심은 세 가지다. 작업 트리만 되돌릴지, 스테이징만 되돌릴지, 아니면 특정 커밋의 내용으로 맞출지를 먼저 구분해야 한다. 이 글은 Git 공식 문서를 기준으로 git restore의 기본 동작과 자주 쓰는 옵션을 정리한다.

git restore는 언제 쓰는 명령일까?

Git 공식 문서에서 git restore의 설명은 "작업 트리 파일을 복원한다"에 가깝다. tracked 경로를 지정한 소스 상태로 되돌리는 역할이므로, 브랜치 전환이 목적일 때는 git switch나 git checkout의 다른 모드를 쓰는 편이 맞다.

즉 이 명령은 "브랜치를 바꾼다"보다 "파일 내용을 되돌린다"에 초점이 있다. 예를 들어 실수로 수정한 파일을 index 상태로 되돌리거나, 이미 git add한 변경을 다시 unstaged 상태로 되돌릴 때 가장 직접적이다.

기본 동작은 무엇을 기준으로 복원할까?

상황	권장 명령	복원 기준
작업 트리 수정만 취소하고 싶다	git restore path/to/file	index 내용을 작업 트리에 다시 쓴다.
스테이징만 취소하고 싶다	git restore --staged path/to/file	HEAD 내용을 index에 다시 쓴다.
작업 트리와 스테이징을 함께 되돌리고 싶다	git restore --staged --worktree path/to/file	HEAD 기준으로 index와 작업 트리를 함께 맞춘다.
특정 커밋 상태로 파일을 가져오고 싶다	git restore --source=<commit> --worktree path/to/file	지정한 commit, branch, tag를 소스로 삼는다.

Git 공식 문서 기준으로 아무 옵션이 없으면 작업 트리만 복원 대상이다. 반대로 --staged를 주면 index 복원으로 바뀌고, 이때 기본 소스는 HEAD다. 이 차이를 놓치면 "왜 예상한 내용이 안 돌아왔지?" 같은 혼란이 생기기 쉽다.

--source는 언제 붙여야 할까?

--source=<tree>는 복원 기준을 index나 HEAD 대신 특정 commit, branch, tag로 명시할 때 쓴다. 따라서 현재 작업 중인 브랜치의 최신 상태가 아니라, 이전 커밋의 특정 파일만 가져오고 싶을 때 유용하다.

예를 들어 설정 파일 한 개만 지난 릴리스 버전으로 비교 복원하고 싶다면 git restore --source=v1.2.0 --worktree config.yml처럼 쓰는 식이다. 문서상 tracked 경로가 소스에 없으면 해당 경로는 소스와 맞추기 위해 제거될 수 있으므로, 경로 단위 지정은 보수적으로 하는 편이 안전하다.

--staged와 --worktree는 어떻게 나눠야 할까?

--worktree는 실제 파일 시스템의 작업 트리를 복원 대상으로 삼고, --staged는 index를 복원 대상으로 삼는다. 둘 중 하나만 주면 그 대상만 바뀌고, 둘 다 주면 index와 작업 트리를 함께 복원한다.

실무에서는 "파일 편집은 유지하고 add만 취소"라면 --staged만, "편집 자체를 버리고 index 상태로 되돌림"이라면 기본 git restore, "add도 취소하고 파일 수정도 버림"이라면 --staged --worktree를 구분하면 된다.

--patch는 언제 더 안전할까?

Git 공식 문서는 --patch가 복원 소스와 대상의 차이를 hunk 단위로 보여 주고, 사용자가 선택적으로 복원할 수 있다고 설명한다. 전체 파일을 버리기에는 부담스럽고 일부 변경만 취소하고 싶을 때 적합하다.

예를 들어 한 파일 안에서 디버그 로그만 되돌리고 실제 기능 수정은 남기고 싶다면 git restore -p app.js가 더 안전하다. 이는 git add -p와 비슷한 상호작용 모델을 사용하므로, 패치 선택 워크플로에 익숙한 팀에서 특히 편하다.

머지 충돌 중에는 무엇을 조심해야 할까?

문서 기준으로 --ours와 --theirs는 unmerged 경로를 index에서 작업 트리로 복원할 때만 쓸 수 있고, --source와 함께는 사용할 수 없다. 즉 충돌 해결 중 특정 쪽 버전을 작업 트리에 꺼낼 때 쓰는 옵션이다.

또 Git 공식 문서는 rebase나 pull --rebase 중에는 ours와 theirs가 뒤바뀐 것처럼 보일 수 있다고 분명히 적고 있다. rebase 중 충돌을 다룰 때는 평소 merge 때의 감각만 믿지 말고 현재 워크플로를 기준으로 확인하는 편이 안전하다.

체크아웃과는 무엇이 다를까?

Git 문서 구조상 restore는 기본 스냅샷 조작 명령, checkout은 브랜치 전환과 경로 교체까지 함께 품은 명령으로 정리되어 있다. 최근 Git 사용법에서 파일 복원은 restore, 브랜치 전환은 switch로 의도를 나누는 이유가 여기에 있다.

팀 문서나 교육 자료를 새로 쓴다면 "브랜치 이동은 git switch, 파일 복원은 git restore"처럼 역할을 분리해 적는 편이 실수를 줄인다. 특히 초보자가 checkout의 여러 모드를 한 번에 외우려다 혼란을 겪는 문제를 줄이기 좋다.

이런 상황에서는 어떤 명령이 무난할까?

상황	권장 명령	이유
수정한 파일을 add 전 상태로 되돌리고 싶다	git restore src/app.py	index 기준으로 작업 트리만 복원한다.
실수로 git add한 파일을 unstaged로 돌리고 싶다	git restore --staged src/app.py	HEAD 기준으로 index만 복원한다.
이전 커밋 버전의 파일을 현재 작업 트리에 가져오고 싶다	git restore --source=HEAD~1 --worktree src/app.py	특정 커밋을 소스로 명시한다.
변경 일부만 골라서 취소하고 싶다	git restore -p src/app.py	hunk 단위로 선택 복원할 수 있다.

FAQ

Q. git restore는 untracked 파일도 지우나?

아니다. Git 공식 문서의 설명 대상은 tracked 경로 복원이다. untracked 파일 정리는 git clean 계열로 구분해야 한다.

Q. git restore --staged는 파일 수정분까지 같이 버리나?

아니다. --staged만 주면 index만 복원하고 작업 트리 수정은 남는다. 수정까지 버리려면 --worktree를 함께 써야 한다.

Q. 특정 브랜치의 파일을 현재 브랜치에서 가져오고 싶으면 가능할까?

가능하다. git restore --source=main --worktree path/to/file처럼 branch 이름을 소스로 줄 수 있다. 다만 해당 경로가 소스 브랜치에 실제로 있는지 먼저 확인하는 편이 안전하다.

정리

git restore의 선택 기준은 단순하다. 작업 트리만 되돌릴지, index만 되돌릴지, 특정 commit을 소스로 삼을지를 먼저 정하면 된다. 그 다음에 --worktree, --staged, --source, --patch를 붙이면 대부분의 실무 상황을 설명할 수 있다.

한 줄 기준으로 줄이면 이렇다. 수정 취소는 git restore, 스테이징 취소는 git restore --staged, 특정 커밋 기준 복원은 git restore --source=<tree>를 우선 검토하면 된다.

참고 자료

• Git Documentation: git-restore
• Git Documentation: git-checkout
• Git Documentation: git