HOWTO · Git
Git 리포지토리의 복제 하위 디렉터리
이 튜토리얼은 Git 리포지토리의 하위 디렉토리를 복제하는 방법에 관한 것입니다.
이 페이지의 내용
Git 프로젝트의 디렉터리 하나에서 작업하려면 sparse-checkout으로 작업 트리에 표시할 경로를 선택하세요. 이 방법은 원래 리포지토리 안에서 작업하게 해 주며, 해당 디렉터리만 포함하는 별도의 리포지토리를 만들지는 않습니다.
Sparse Checkout의 기능과 한계
일반적인 clone은 리포지토리의 파일을 작업 트리에 체크아웃합니다. Git sparse-checkout을 사용하면 작업 트리에 표시할 추적 중인 경로를 선택할 수 있습니다. 이때 체크아웃은 기존 리포지토리 및 그 기록에 계속 연결됩니다. backend와 documentation 디렉터리도 있는 프로젝트에서 frontend 같은 한 모듈을 중심으로 작업할 때 유용합니다.
경로를 선택해도 다운로드 크기가 줄어든다고 보장되지는 않습니다. Sparse checkout은 작업 트리를 제어하며, 가져오는 리포지토리 데이터의 양은 clone 옵션과 Git 설정에 따라 달라집니다. 자체 기록을 가진 독립 프로젝트가 필요하다면 원본 프로젝트에서 해당 모듈을 위한 별도 리포지토리를 제공해야 합니다.
Sparse Checkout으로 리포지토리 복제하기
먼저 설치된 Git에서 sparse-checkout 명령을 사용할 수 있는지 확인하세요. 예를 들어 git help -a로 확인할 수 있습니다. 아래 명령은 해당 인터페이스를 사용할 수 있을 때만 실행하세요. 이 명령은 작업 트리를 채우지 않은 상태로 리포지토리를 복제한 다음 frontend를 선택합니다. 예시의 리포지토리 URL과 디렉터리 이름은 자신의 값으로 바꾸세요. 아래 URL과 경로는 자리표시자입니다.
다음은 작은 로컬 리포지토리를 만들고 frontend 디렉터리를 선택하는 독립 실행형 Bash 예제입니다.
set -eu
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT
git init --quiet "$work/source"
git -C "$work/source" config user.name "Example User"
git -C "$work/source" config user.email "example@example.com"
mkdir -p "$work/source/frontend" "$work/source/backend"
printf 'app source\n' > "$work/source/frontend/app.txt"
printf 'service source\n' > "$work/source/backend/service.txt"
git -C "$work/source" add frontend backend
git -C "$work/source" commit -m "Add project modules" >/dev/null
branch=$(git -C "$work/source" branch --show-current)
git clone --no-checkout --branch "$branch" "$work/source" "$work/project" >/dev/null 2>&1
git -C "$work/project" sparse-checkout init --cone
git -C "$work/project" sparse-checkout set frontend
git -C "$work/project" sparse-checkout list
frontend
원격 프로젝트에서는 git clone --no-checkout <repository-url> my_project, cd my_project, git sparse-checkout init --cone, git sparse-checkout set frontend 순서로 실행합니다. 선택한 경로는 리포지토리 루트를 기준으로 합니다. 로컬 Bash 예제의 출력에는 선택한 디렉터리 이름인 frontend가 표시되며, 이 표기는 코드 블록과 마찬가지로 영어로 유지됩니다. 설치된 Git에서 sparse-checkout을 제공하지 않으면 전체 작업 트리를 받도록 git clone <repository-url> my_project를 사용하세요.
선택한 디렉터리 변경하기
선택 경로를 backend와 documentation으로 바꾸려면 리포지토리에서 git sparse-checkout set backend documentation을 실행하세요. frontend를 선택된 상태로 유지하면서 다른 디렉터리를 추가하려면 git sparse-checkout add backend를 사용합니다. Cone 모드는 디렉터리 선택을 위한 기능이므로 개별 파일이 아니라 디렉터리 경로를 지정하세요.
리포지토리 루트를 기준으로 경로를 지정하고, 추적 중인 경로와 철자 및 대소문자를 똑같이 맞추세요. 선택한 경로에 예상한 파일이 보이지 않으면 git ls-tree --name-only HEAD로 최상위 항목을 확인한 다음 올바른 디렉터리를 설정하세요. frontend/components처럼 루트부터의 경로를 지정하면 중첩된 경로도 선택할 수 있습니다.
체크아웃 확인 및 일반적인 문제 해결
선택한 경로는 git sparse-checkout list로 확인하고, 작업 트리 상태는 git status --short로 살펴보세요. git rev-parse --show-toplevel을 실행해 의도한 리포지토리 안에 있는지 확인하세요. 선택한 디렉터리 이름은 이 루트를 기준으로 해석해야 합니다.
명령을 사용할 수 없거나 해당 Git 설치에서 sparse-checkout 인터페이스를 지원하지 않는 경우, 또는 리포지토리 작업 흐름에서 이를 허용하지 않는 경우에는 전체 clone을 사용하세요. 디렉터리를 선택했는데 예상한 파일이 없다면 체크아웃된 커밋에 해당 경로가 있는지, 경로 철자가 정확한지 확인하세요. 작업 트리에 이미 있는 추적되지 않는 파일은 sparse 선택 범위 밖에 있더라도 계속 표시될 수 있습니다.
자세한 내용은 Git sparse-checkout 문서, git clone 문서, git help 문서를 참고하세요.