Compare commits

..
1 Commits
Author SHA1 Message Date
sneak 0342307a9b Rewrite README.md sentence by sentence for a newcomer
check / check (push) Canceled after 0s
Rewrites `README.md` from scratch for
#135. Every statement was checked
against the code on `next` and against what the built binary prints on
small trees under `/var/tmp`. The headings that the code comments cite
are kept.

Where the old text and the repository disagreed, the new text states
what the code does: `@latest` installs the newest tagged release, ten
million files in both "Rationale" and "Design", no Windows excludes, a
relative operand is joined to the working directory as `pwd` prints it,
and an operand reached through a symlinked directory below another
operand is dropped (#144).

Dropped from "Constraints": the permission to add `github.com/spf13/viper`
if configuration-file support is ever needed.

Model: fable-5-1
2026-10-26 21:39:00 +00:00
+16 -13
View File
@@ -261,11 +261,13 @@ The reference below is also the program's specification.
## Non-goals ## Non-goals
- No byte-for-byte compare, and no deleting or linking of duplicates. The - No byte-for-byte compare, no deleting of duplicates, and no replacing a copy
reports are advisory. Acting on them is your job. with a hard link to another copy. The reports are advisory. Acting on them is
your job.
- The SQLite database is the only stored data. There are no export or import - The SQLite database is the only stored data. There are no export or import
formats. formats.
- No daemon or filesystem watcher. Scheduling rescans is `cron`'s job. - `sfdupes` does not run in the background or watch the filesystem for changes.
Scheduling rescans is `cron`'s job.
## Reference ## Reference
@@ -369,8 +371,7 @@ default. An operand may be a directory or a regular file.
symlinked directory below the outer operand is dropped too, without a line. symlinked directory below the outer operand is dropped too, without a line.
The outer operand's walk does not follow the symlink, so no file under the The outer operand's walk does not follow the symlink, so no file under the
inner operand is scanned. The records that an earlier scan left under it are inner operand is scanned. The records that an earlier scan left under it are
deleted. With `-x`, a directory operand reached that way is kept when the deleted. The `-x` case above also covers an operand reached that way.
symlink leads to another filesystem than the outer operand.
- An operand that is neither a regular file nor a directory is not scanned. - An operand that is neither a regular file nor a directory is not scanned.
`scan` prints a warning naming the path and what it is. It counts the operand `scan` prints a warning naming the path and what it is. It counts the operand
as skipped and drops it. An operand beneath a symlink operand is scanned all as skipped and drops it. An operand beneath a symlink operand is scanned all
@@ -427,12 +428,13 @@ phases.
1. `load` reads the existing records. Each record under the operands is kept in 1. `load` reads the existing records. Each record under the operands is kept in
memory by path, with its size and mtime, for the walk to compare against. memory by path, with its size and mtime, for the walk to compare against.
2. `walk` lists the trees under all operands. Several workers share one queue of 2. `walk` lists the trees under all operands. Several workers share one queue of
directories to read. A worker is one thread of the program, and "Concurrency" directories to read. A worker is one thread of the program. A thread is one
says how many there are. Each worker reads one directory at a time. It hands of several parts of a program that run at the same time and share its memory.
the subdirectories it finds back to the queue, and it stats each regular file "Concurrency" says how many workers there are. Each worker reads one
as it finds it. The walk compares each file with its record. An unchanged directory at a time. It hands the subdirectories it finds back to the queue,
file needs nothing more. Every new or changed file is passed to the hash and it stats each regular file as it finds it. The walk compares each file
phase. with its record. An unchanged file needs nothing more. Every new or changed
file is passed to the hash phase.
3. `hash` reads every new or changed file and computes its three hashes. Files 3. `hash` reads every new or changed file and computes its three hashes. Files
are read in inode order. An inode is the filesystem's own record of a file. are read in inode order. An inode is the filesystem's own record of a file.
Files with nearby inode numbers usually lie near each other on disk. Reading Files with nearby inode numbers usually lie near each other on disk. Reading
@@ -865,8 +867,9 @@ Only one `scan` at a time can hold the lock.
SQLite appends changes to a `-wal` file beside the database, and keeps a SQLite appends changes to a `-wal` file beside the database, and keeps a
lookup table for that file in a `-shm` file. Readers do not block the writer, lookup table for that file in a `-shm` file. Readers do not block the writer,
so running a report during a scan is safe. so running a report during a scan is safe.
- Every connection has a busy timeout of 10 seconds. That is how long it waits - Every subcommand opens the database with a busy timeout of 10 seconds. That is
for a database another connection has locked before it gives up. how long it waits for a database another process has locked before it gives
up.
- The filesystem is authoritative, and the database follows it. Hashed records - The filesystem is authoritative, and the database follows it. Hashed records
are written 10,000 at a time while the scan runs, so a report may see a scan's are written 10,000 at a time while the scan runs, so a report may see a scan's
changes partly applied. A scan that dies partway leaves a valid database changes partly applied. A scan that dies partway leaves a valid database