Compare commits

..
1 Commits
Author SHA1 Message Date
sneak b641024fc0 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 20:38:16 +00:00
+13 -16
View File
@@ -261,13 +261,11 @@ The reference below is also the program's specification.
## Non-goals
- No byte-for-byte compare, no deleting of duplicates, and no replacing a copy
with a hard link to another copy. The reports are advisory. Acting on them is
your job.
- No byte-for-byte compare, and no deleting or linking of duplicates. The
reports are advisory. Acting on them is your job.
- The SQLite database is the only stored data. There are no export or import
formats.
- `sfdupes` does not run in the background or watch the filesystem for changes.
Scheduling rescans is `cron`'s job.
- No daemon or filesystem watcher. Scheduling rescans is `cron`'s job.
## Reference
@@ -371,7 +369,8 @@ default. An operand may be a directory or a regular file.
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
inner operand is scanned. The records that an earlier scan left under it are
deleted. The `-x` case above also covers an operand reached that way.
deleted. With `-x`, a directory operand reached that way is kept when the
symlink leads to another filesystem than the outer operand.
- 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
as skipped and drops it. An operand beneath a symlink operand is scanned all
@@ -428,13 +427,12 @@ phases.
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.
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. A thread is one
of several parts of a program that run at the same time and share its memory.
"Concurrency" says how many workers there are. Each worker reads one
directory at a time. It hands the subdirectories it finds back to the queue,
and it stats each regular file as it finds it. The walk compares each file
with its record. An unchanged file needs nothing more. Every new or changed
file is passed to the hash phase.
directories to read. A worker is one thread of the program, and "Concurrency"
says how many there are. Each worker reads one directory at a time. It hands
the subdirectories it finds back to the queue, and it stats each regular file
as it finds it. The walk compares each file 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
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
@@ -867,9 +865,8 @@ Only one `scan` at a time can hold the lock.
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,
so running a report during a scan is safe.
- Every subcommand opens the database with a busy timeout of 10 seconds. That is
how long it waits for a database another process has locked before it gives
up.
- Every connection has a busy timeout of 10 seconds. That is how long it waits
for a database another connection has locked before it gives up.
- 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
changes partly applied. A scan that dies partway leaves a valid database