증분 빌드
증분 빌드는 파일 체크섬과 의존성 변경을 추적해 변경되지 않은 페이지를 건너뜁니다. 페이지가 많은 사이트에서 재빌드 시간이 크게 줄어듭니다.
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/ 아래에 있으면 전체 페이지) |
| 설정 파일 | 전체 재빌드 |
| 정적 파일만 | 변경된 파일만 복사 |
캐시 파일
캐시는 프로젝트 루트의 .hwaro_cache.json에 저장됩니다. 이 파일에는 다음이 들어 있습니다.
- 메타데이터 — 마지막 빌드의 템플릿·설정 체크섬
- 항목 — 파일별 레코드(경로, mtime, 콘텐츠 해시, 출력 경로)
.hwaro_cache.json은 .gitignore에 추가합니다.
.hwaro_cache.json
플래그 참조
| 플래그 | 설명 |
|---|---|
--cache |
증분 빌드 캐시 활성화 |
--full |
전체 재빌드 강제(캐시를 비우고 다시 채움) |
예시
# 첫 빌드 — 캐시 생성
hwaro build --cache
# 파일 몇 개 수정 후 재빌드 — 변경된 페이지만 다시 렌더링
hwaro build --cache
# 뭔가 이상할 때 — 깨끗하게 전체 재빌드
hwaro build --cache --full
# 다른 플래그와 조합
hwaro build --cache --minify --parallel