git fetch --unshallow

• shallow clone 된 저장소에 전체 커밋 히스토리를 복원하는 git 명령어.
• CI/CD 환경에서 빌드 속도를 위해 shallow clone을 사용하지만, git 히스토리가 필요한 작업에서 문제가 발생할 때 사용

해당 개념이 필요한 이유

• CI/CD 플랫폼(Cloudflare Pages, GitHub Actions, Vercel 등)은 빌드 속도 최적화를 위해 기본적으로 git clone --depth 1 (shallow clone)을 수행
• shallow clone 상태에서는 git log, git blame, 태그 기반 버전 계산 등 히스토리 의존 작업이 실패하거나 부정확한 결과를 반환
• git fetch --unshallow로 전체 히스토리를 복원하면 이러한 제약을 해결할 수 있음

AS-IS: Shallow Clone

sequenceDiagram
    autonumber
    participant CI as CI/CD 플랫폼
    participant Git as Git Remote

    CI->>Git: git clone --depth 1
    Note over CI: 커밋 1개만 존재<br/>히스토리 조회 불가
    CI->>CI: git log → 최신 커밋 1개만 반환
    CI->>CI: git log --diff-filter=A → 부정확
    CI->>CI: git describe --tags → 실패

TO-BE: unshallow로 복원

sequenceDiagram
    autonumber
    participant CI as CI/CD 플랫폼
    participant Git as Git Remote

    CI->>Git: git clone --depth 1
    CI->>Git: git fetch --unshallow
    Note over CI: 전체 커밋 히스토리 복원
    CI->>CI: git log → 전체 히스토리 조회 가능
    CI->>CI: git log --diff-filter=A → 정확한 최초 커밋
    CI->>CI: git describe --tags → 정상 동작

Shallow Clone이란

git 히스토리의 일부만 가져오는 clone 방식이다.

git clone --depth 1  # 최신 커밋 1개만
git clone --depth 5  # 최신 커밋 5개만
git clone            # 전체 히스토리 (full clone)

장점: clone 속도가 빠르고 디스크 사용량이 적음 단점: 히스토리 의존 작업이 불가능하거나 부정확

shallow clone에서 실패하는 작업들

작업	명령어	실패 원인
파일 최초 생성일 조회	git log --diff-filter=A	히스토리가 없어 최초 커밋을 찾을 수 없음
코드 blame	git blame	작성자/시점 추적 불가
태그 기반 버전	git describe --tags	태그가 shallow 범위 밖이면 실패
커밋 수 계산	git rev-list --count	부정확한 결과

git fetch —unshallow 동작 원리

git fetch --unshallow

• shallow clone 상태에서만 동작 (이미 full clone이면 에러)
• remote에서 나머지 모든 커밋 히스토리를 추가로 fetch
• 실행 후 .git/shallow 파일이 제거되며 full clone과 동일한 상태가 됨

관련 명령어 비교:

명령어	용도
git clone --depth 1	최신 커밋 1개만 clone
git fetch --unshallow	shallow → full clone으로 확장
git fetch --depth N	shallow 깊이를 N으로 조정

실제 사례: Quartz 날짜별 보기

배경

Quartz 정적 사이트의 “날짜별 보기(DateIndex)“에서 파일을 생성 날짜 기준으로 그룹핑하려고 했다.

Quartz 기본 제공 플러그인 CreatedModifiedDate(lastmod.ts)가 파일의 날짜를 결정한다:

// quartz.config.ts
Plugin.CreatedModifiedDate({
  priority: ["frontmatter", "git", "filesystem"],
})

우선순위	소스	created	modified
1	frontmatter	created 필드	modified 필드
2	git	최초 커밋 날짜	최근 커밋 날짜
3	filesystem	birthtimeMs	mtimeMs

문제 1: 플러그인이 git에서 created를 가져오지 않음

원래 CreatedModifiedDate 플러그인은 git에서 modified만 가져왔다:

// 원본 - git에서 modified만 조회
modified ||= await repo.getFileLatestModifiedDateAsync(relativePath)
// created는 조회하지 않음

Obsidian에서 작성한 파일 중 frontmatter에 created가 없는 파일이 존재하여, git → filesystem으로 fallback되었다.

수정: git log --diff-filter=A로 최초 커밋 날짜를 created로 설정하는 로직 추가:

// 수정 - git에서 created도 조회
modified ||= await repo.getFileLatestModifiedDateAsync(relativePath)
 
if (!created) {
  const result = execSync(
    `git log --follow --diff-filter=A --format=%at -- "${relativePath}"`,
    { cwd: repositoryWorkdir, encoding: "utf-8" },
  ).trim()
  if (result) {
    created = parseInt(result) * 1000
  }
}

• --follow: 파일명 변경 추적
• --diff-filter=A: “Added” 커밋만 필터링
• --format=%at: Unix timestamp 출력
• 빌드 타임에 정적 계산 → 런타임 성능 영향 없음

문제 2: Cloudflare Pages shallow clone

코드를 수정해도 Cloudflare Pages 빌드 환경에서 44개 파일이 같은 날짜로 표시되었다.

원인: Cloudflare Pages가 --depth 1 shallow clone을 사용하여:

1. frontmatter.created → 없는 파일 존재 (undefined)
2. git log --diff-filter=A → 커밋 1개뿐이라 부정확
3. filesystem birthtimeMs → clone 시점 = 모든 파일 동일 날짜

해결: 빌드 명령어에 git fetch --unshallow 추가:

# 변경 전
npm ci && npx quartz build

# 변경 후
git fetch --unshallow && npm ci && npx quartz build

설정 위치: Cloudflare Dashboard → Workers & Pages → 프로젝트 → Settings → Build command

참고 문서

• git-fetch Documentation
• git-clone —depth Documentation
• Cloudflare Pages Build Configuration