증분 빌드
증분 빌드는 파일 체크섬과 의존성 변경을 추적해 변경되지 않은 페이지를 건너뜁니다. 페이지가 많은 사이트에서 재빌드 시간이 크게 줄어듭니다.
hwaro build --cache
사용 시점
증분 빌드는 다음 상황에서 효과가 큽니다.
- 사이트에 페이지는 많지만 한 번에 몇 개만 수정하는 경우
- 수정-빌드-미리보기 사이클을 빠르게 돌리고 싶은 경우
- 템플릿이나 설정이 아니라 콘텐츠 위주로 작업하는 경우
사용 방법
캐시 활성화
hwaro build --cache
첫 실행에서는 모든 페이지를 빌드하고 체크섬을 .hwaro_cache.json에 저장합니다. 이후 빌드부터는 변경된 파일만 다시 처리합니다.
전체 재빌드 강제
hwaro build --cache --full
--full 플래그는 캐시를 비우고 모든 페이지를 처음부터 다시 빌드합니다. 빌드가 끝나면 새 캐시가 저장되므로, 다음에 --full 없이 빌드하면 다시 증분 빌드로 동작합니다.
동작 방식
변경 감지
캐시 항목마다 다음을 추적합니다.
- 파일 수정 시각(mtime) — 빠른 1차 확인
- 콘텐츠 체크섬(MD5) — mtime이 달라졌을 때 실제 변경 여부를 검증해, 파일을 touch만 한 경우 같은 오탐을 걸러냅니다
mtime이 그대로면 내용을 읽지 않고 변경 없음으로 판단합니다. mtime이 다르면 콘텐츠 해시를 계산해 비교하고, 실제로 변경됐는지 확인합니다.
의존성 무효화
파일별 체크섬 외에도, 각 페이지가 실제로 무엇에 의존하는지 추적합니다.
- 템플릿 클로저 — 페이지의 템플릿과 그 템플릿이
extends,include,import로 전이적으로 참조하는 모든 템플릿, 그리고 페이지 콘텐츠가 호출하는 숏코드 템플릿까지 포함합니다. 각 페이지의 캐시 항목에 이 클로저의 핑거프린트가 저장되므로,partials/footer.html을 수정하면 해당 파셜을 렌더링하는 템플릿 체인을 가진 페이지만 재빌드됩니다. - 캐스케이드 핑거프린트 — 페이지에 적용된 섹션
[cascade]병합값. 상위_index.md의 캐스케이드를 수정하면 하위 페이지가 재빌드됩니다. - 설정 체크섬 — 최종 병합된 설정의 해시. 설정이 바뀌면 모든 항목이 무효화됩니다.
- 렌더 훅 — 설정된 모든
templates/hooks/render-*템플릿의 핑거프린트(렌더 훅 참고)가 모든 페이지의 템플릿 클로저에 포함됩니다. 훅은 페이지의{% include %}/{% extends %}그래프로 도달하는 대상이 아니므로, 훅을 수정하면 좁혀진 집합이 아니라 모든 페이지가 다시 렌더링됩니다.
템플릿 의존성 추적은 모든 템플릿 참조가 문자열 리터럴이어야 동작합니다.
동적 참조({% include some_var %})를 쓰는 템플릿이 하나라도 있으면
사이트 전체 무효화로 전환되어, 템플릿이 하나라도 바뀌면 모든 페이지를
재빌드합니다. 명시적으로 끌 수도 있습니다.
[build]
template_deps = false # 템플릿이 바뀌면 모든 페이지를 재빌드
건너뛰는 작업
페이지와 그 의존성이 모두 변경되지 않았다면:
- 콘텐츠 파싱은 여전히 수행합니다(내비게이션, 택소노미 등을 구성하기 위해)
- 렌더링과 파일 쓰기는 건너뜁니다 — 기존 출력 파일을 재사용합니다
- SEO 파일(사이트맵, 피드 등)은 항상 다시 생성합니다
serve 모드
개발 서버(hwaro serve)는 더 정밀한 증분 전략을 사용합니다.
| 변경 유형 | 전략 |
|---|---|
| 콘텐츠 파일만 | 영향받는 페이지와 인접 페이지만 다시 파싱·렌더링 |
| 템플릿 파일만 | 수정된 템플릿이 템플릿 클로저에 포함된 페이지만 다시 렌더링 (추적이 꺼져 있거나, 그래프에 동적 참조가 있거나, 수정된 파일이 templates/hooks/ 아래에 있으면 전체 페이지) |
| 설정 파일 | 전체 재빌드 |
| 정적 파일만 | 변경된 파일만 복사 |
삭제된 페이지
콜드 빌드는 빈 출력 디렉터리에서 시작하므로 삭제한 페이지는 다음 빌드에서
public/에서도 사라집니다. --cache는 디렉터리를 그대로 두기 때문에(그게
목적입니다) 삭제는 캐시로 처리합니다. 모든 항목은 해당 페이지가 쓴 파일을
기록해 두고, 매 빌드마다 살아 있는 페이지가 주장하지 않는 항목의 출력물을
삭제합니다.
삭제된 페이지, 이름이 바뀐 페이지, URL이 옮겨진 페이지(slug, path,
퍼머링크 규칙), 초안으로 바뀐 페이지, expires 날짜가 지난 페이지,
render = false가 된 페이지가 모두 여기에 해당합니다.
제거된 페이지가 함께 만들어 낸 파일도 같이 사라집니다. aliases 리다이렉트
스텁, AMP 미러, 자동 생성된 OG 이미지, 더 이상 아무도 쓰지 않는 텀의 택소노미
페이지(그 텀의 피드 포함), 섹션이 더 이상 채우지 않는 페이지네이션 페이지가
모두 해당합니다. 기능 자체를 끄는 경우([amp] enabled = false)도 같은 이유로
다음 빌드에서 그동안 발행하던 파일이 정리됩니다.
따라서 --cache 빌드의 출력물은 깨끗한 빌드와 바이트 단위로 같고, 무언가를
정리하려고 hwaro build --full을 쓸 필요가 없습니다.
캐시 파일
캐시는 프로젝트 루트의 .hwaro_cache.json에 저장됩니다. 이 파일에는 다음이 들어 있습니다.
- 메타데이터 — 마지막 빌드의 템플릿·설정 체크섬
- 항목 — 파일별 레코드(경로, mtime, 콘텐츠 해시, 출력 경로). 출력 경로는 제거된 페이지의 오래된 파일을 찾는 데에도 쓰입니다
.hwaro_cache.json은 .gitignore에 추가합니다(hwaro init이 스캐폴드하는 .gitignore에는 이미 포함되어 있습니다).
.hwaro_cache.json
플래그 참조
| 플래그 | 설명 |
|---|---|
--cache |
증분 빌드 캐시 활성화 |
--full |
전체 재빌드 강제(캐시를 비우고 다시 채움) |
예시
# 첫 빌드 — 캐시 생성
hwaro build --cache
# 파일 몇 개 수정 후 재빌드 — 변경된 페이지만 다시 렌더링
hwaro build --cache
# 뭔가 이상할 때 — 깨끗하게 전체 재빌드
hwaro build --cache --full
# 다른 플래그와 조합
hwaro build --cache --minify