Compare commits

..
Author SHA1 Message Date
sneak f373b7d9e4 Carry the README changes from next into the rewrite
check / check (push) Canceled after 0s
`next` changed the old README after this branch was cut, in
#146 (the `totals` table, commit
98193b2) and #147 (`disk_size`,
commit 4ed2e37). This commit states the same facts in the rewritten
README, in the places #140 (comment)
lists, and changes nothing else. Every statement was checked against the
code on `next`.

Model: fable-5-1
2026-11-02 22:02:50 +00:00
+22 -19
View File
@@ -408,8 +408,8 @@ operands:
- When such a file's size on disk differs from its recorded `disk_size`, `scan` - When such a file's size on disk differs from its recorded `disk_size`, `scan`
updates `disk_size` alone. It still does not read the file, and counts it as updates `disk_size` alone. It still does not read the file, and counts it as
unchanged. ZFS, for example, counts a new file's blocks only seconds after the unchanged. ZFS, for example, counts a new file's blocks only seconds after the
write. A file scanned within those seconds gets its real `disk_size` at the write. A block is the unit in which a filesystem allocates disk space. A file
next scan. scanned within those seconds gets its real `disk_size` at the next scan.
- `scan` hashes a file again when its size differs or its mtime is newer. The - `scan` hashes a file again when its size differs or its mtime is newer. The
mtime is compared to the nanosecond, as finely as the filesystem records it. A mtime is compared to the nanosecond, as finely as the filesystem records it. A
same-size rewrite counts as a change whenever the filesystem gives it a later same-size rewrite counts as a change whenever the filesystem gives it a later
@@ -777,10 +777,11 @@ first dupe files size disk_size
A file's `disk_size` is the space its blocks take on disk. It can be more than A file's `disk_size` is the space its blocks take on disk. It can be more than
the file's size, because space is allocated in whole blocks. It is less than the the file's size, because space is allocated in whole blocks. It is less than the
file's size on a compressed or sparse file. So two copies of one tree can differ file's size on a compressed or sparse file. A sparse file has gaps that take no
in `disk_size`. When a file in one copy is a hard link to one in the other, both space on disk. So two copies of one tree can differ in `disk_size`. When a file
copies count its blocks in full. Removing it from one copy then frees nothing, in one copy is a hard link to one in the other, both copies count its blocks in
as the limitation under "`trees` mode" says. full. Removing it from one copy then frees nothing, as the limitation under
"`trees` mode" says.
The paths are escaped as described under "Report output format". The root The paths are escaped as described under "Report output format". The root
directory's path is `/`. directory's path is `/`.
@@ -941,16 +942,17 @@ Only one `scan` at a time can hold the lock.
#### Schema #### Schema
The schema is the database's layout, its table and its index. The schema is the database's layout: its tables, its index and its triggers. A
trigger is a statement SQLite runs by itself when a table changes.
`PRAGMA user_version` holds the schema version, currently 1. An empty database `PRAGMA user_version` holds the schema version, currently 1. An empty database
is at version 0, and `scan` sets it up. Any other version is a fatal error. is at version 0, and `scan` sets it up. Any other version is a fatal error.
`report`, `trees` and `info` set nothing up, so for them version 0 is a fatal `report`, `trees` and `info` set nothing up, so for them version 0 is a fatal
error too. `scan` creates the table and the index and sets the version in one error too. `scan` creates the tables, the index and the triggers and sets the
transaction (see "`info` mode"). So the three land together or not at all. A version in one transaction (see "`info` mode"). So they all land together or not
first scan stopped while doing so leaves an empty database, which the next scan at all. A first scan stopped while doing so leaves an empty database, which the
sets up. A database at version 0 that already has a `files` table was not made next scan sets up. A database at version 0 that already has a `files` table was
by `sfdupes`. Every subcommand refuses it, with an error telling you to remove not made by `sfdupes`. Every subcommand refuses it, with an error telling you to
the file and rescan. remove the file and rescan.
```sql ```sql
CREATE TABLE files ( CREATE TABLE files (
@@ -982,9 +984,10 @@ END;
- `path` is a BLOB, a column of raw bytes, because Unix paths are bytes and not - `path` is a BLOB, a column of raw bytes, because Unix paths are bytes and not
necessarily UTF-8 text. necessarily UTF-8 text.
- `disk_size` is the space the file's blocks take on disk, `st_blocks` × 512 - `disk_size` is the space the file's blocks take on disk. `lstat` is the system
from lstat. It is less than `size` on a compressed or sparse file (see "Trees call that stats a file without following a symlink. Its `st_blocks` field
output format"). counts that space in units of 512 bytes. `disk_size` is less than `size` on a
compressed or sparse file (see "Trees output format").
- `mtime` holds the whole seconds of the file's mtime, rounded down, and - `mtime` holds the whole seconds of the file's mtime, rounded down, and
`mtime_nsec` the nanoseconds past that second. Split this way, they hold any `mtime_nsec` the nanoseconds past that second. Split this way, they hold any
mtime a filesystem can record, even one before 1678 or after 2262. One 64-bit mtime a filesystem can record, even one before 1678 or after 2262. One 64-bit
@@ -1002,9 +1005,9 @@ END;
`scan` and the `read` phase of `report` and `trees` read the number of records `scan` and the `read` phase of `report` and `trees` read the number of records
from it as their total. Counting the records in `files` would read every from it as their total. Counting the records in `files` would read every
record. That takes minutes on a database of tens of millions. The triggers record. That takes minutes on a database of tens of millions. The triggers
make each write to `files` slower, so a first scan of many small files takes make each insert, each delete and each change of a record's `size` slower, so
about two fifths longer. On large files, reading them takes most of the time, a first scan of many small files takes about two fifths longer. On large
so the difference is small. files, reading them takes most of the time, so the difference is small.
### Progress ### Progress