+
+
+
+Change report format specification
+
+
+
+Run with --changes (-%d), HTTrack writes hts-changes.json
+in the project directory, next to hts-log.txt, describing what the crawl
+left new, changed, unchanged and gone compared to the previous mirror. The file is
+rewritten from scratch at the end of every run, and the log carries a one-line
+summary of the same counts.
+
+
+
+What "changed" means
+
+A resource is changed when its bytes differ, not when the server merely re-sent
+it. HTTrack compares the payload it just received against the copy the previous
+run left behind: for pages it parses, the previous payload comes from the cache
+(the file on disk carries the mirror footer and its crawl date, so its bytes
+differ on every run); for everything else, the mirrored file is the payload
+verbatim and is compared directly.
+
+
+
+Where no digest can be taken on either side, because the cache is disabled or
+the previous copy is gone, the report falls back to the transfer signal, and a
+server that answers 200 rather than 304 reads as changed. Keeping the cache on
+(the default) is what makes the report precise.
+
+
+
+With the cache off
+
+--cache=0 costs the report more than the digest of a parsed page. The
+mirror's file index (hts-cache/new.lst) is what records which files a
+run produced, so without it there is no previous mirror to subtract from: nothing
+is reported gone, and whether the run is a first crawl cannot be decided
+at all, which first_crawl states as null rather than guess. What
+is on disk is still compared byte for byte, so the other three lists stay
+meaningful, except for the pages HTTrack parses: those have no cached payload to
+compare against and fall back to the transfer signal.
+
+
+
+Fields
+
+
+- schema: format version, currently 1. It is bumped only
+on an incompatible change; new fields may appear without one.
+- generator: the HTTrack build that wrote the file.
+- date: when the report was written, UTC, YYYY-MM-DDThh:mm:ssZ.
+- first_crawl: true when no index of a previous mirror
+(hts-cache/old.lst) was found, so there was nothing to compare against and
+everything is listed as new. Null when the run kept no index at all and the
+question cannot be answered (see above).
+- partial: true when the report ran out of memory and lists only
+part of the mirror.
+- purged: true when --purge-old was in effect, so the
+files under gone were also deleted from disk.
+- counts: the size of each of the four lists.
+- new, changed, unchanged, gone: the
+lists themselves. Every mirrored file appears in exactly one of them.
+
+
+Each entry is an object:
+
+
+- url: the absolute URL the file came from. Empty under
+gone: deletions are computed from the mirror's file index, which records
+paths, not URLs.
+- file: the path relative to the mirror root, with forward
+slashes. This is the entry's identity: a URL and a redirect that resolve to the
+same local file are one entry, not two.
+- size: the mirrored file's size in bytes, absent when the file
+is not on disk.
+- previous_size: under changed only, the size of the
+copy the previous run left.
+
+
+
+
+Encoding
+
+The file is JSON, UTF-8. URLs and local paths reach HTTrack as raw bytes and are
+not guaranteed to be valid UTF-8; any byte sequence that is not becomes
+U+FFFD (\ufffd), so the file always parses. Compare on file
+rather than on url when a mirror is known to carry legacy-charset URLs.
+
+
+
+Example
+
+
+{
+ "schema": 1,
+ "generator": "HTTrack Website Copier/3.49-14",
+ "date": "2026-07-26T15:29:03Z",
+ "first_crawl": false,
+ "partial": false,
+ "purged": true,
+ "counts": { "new": 1, "changed": 1, "unchanged": 1, "gone": 1 },
+ "new": [
+ { "url": "http://example.com/d.html", "file": "example.com/d.html", "size": 280 }
+ ],
+ "changed": [
+ { "url": "http://example.com/a.html", "file": "example.com/a.html", "size": 281, "previous_size": 273 }
+ ],
+ "unchanged": [
+ { "url": "http://example.com/b.html", "file": "example.com/b.html", "size": 277 }
+ ],
+ "gone": [
+ { "url": "", "file": "example.com/c.html" }
+ ]
+}
+
+
+
+
+Notes
+
+
+- A file listed under gone is only deleted when --purge-old is
+on. Left in place it drops out of the mirror's index, so it is reported once and
+not again.
+- A resource whose local file name changed since the previous mirror (a new
+MIME type, say) is reported as new under its new name; the old name is
+reported as gone only if the file is still on disk. The two entries are
+not paired.
+- A resource this run tried and failed to transfer also drops out of the
+mirror's index, but its previous copy is untouched, so it is reported
+unchanged. Under --purge-old that copy is deleted anyway, and
+the report says gone to match.
+- A run that transfers no data at all is rolled back: HTTrack restores the
+previous cache generation and leaves the previous report in place, so a lost
+connection does not overwrite a good report with an empty one.
+- Content diffs, and keeping the previous copy of a changed page, are out of
+scope: both change what a mirror directory contains.
+
+
+
+
+
+ |
+
+ 