Compare commits

..
1 Commits
Author SHA1 Message Date
sneak d7f54a8705 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. #140 lists
every such point. Among them: `@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 23:41:05 +00:00
+20 -16
View File
@@ -262,9 +262,10 @@ 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.
- No deleting of duplicates.
- No replacing a copy 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
formats.
- `sfdupes` does not run in the background or watch the filesystem for changes.
@@ -352,7 +353,9 @@ default. An operand may be a directory or a regular file.
stored under that absolute path.
- All operands belong to one scan, and one walk covers them all at once (see
"Concurrency").
- An operand that repeats another is dropped before the walk, without a line.
- The warnings and the line described below come first, even for an operand that
repeats or lies under another. After them, an operand that repeats another is
dropped before the walk, without a line.
- An operand under another operand is dropped the same way, unless one of the
cases below applies. No path is then walked twice.
- An operand under another is kept, and walked on its own, when the inner
@@ -366,10 +369,10 @@ default. An operand may be a directory or a regular file.
such a directory, so the inner operand is walked on its own.
- No other case keeps an operand under another. An operand reached through a
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.
symlinked directory below the outer operand is dropped too. 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.
- 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
@@ -478,9 +481,9 @@ walk practical on large or busy storage pools.
- By default the walk enters directories on other filesystems than its
operand's. With `-x`, it never enters a directory on a different filesystem
than its operand. `scan` prints no line for that directory and does not count
it as skipped. The records below it are kept, as described under "What a scan
does to the database".
than its operand. `scan` prints no line for a directory that only `-x` leaves
out, and does not count it as skipped. The records below it are kept, as
described under "What a scan does to the database".
- The walk never records anything on a filesystem that is not persistent. A
filesystem is not persistent when the kernel makes it up or keeps it in
memory. These are the types, as `sfdupes scan --help` lists them on Linux and
@@ -586,8 +589,8 @@ from a thread of its own and never blocks the workers.
- one line naming the database (see "Database");
- for each dropped operand, in operand order, the warning or the line described
under "Operands". `scan` prints neither for an operand that repeats another or
lies under another;
under "Operands". An operand dropped only because it repeats another or lies
under another gets neither;
- the progress display of each phase (see "Progress"). `scan` prints each
warning for a skipped path as it happens. It prints a line the same way for
each path left out as a default exclude or as not on a persistent filesystem;
@@ -1014,7 +1017,7 @@ phase waits, in place of the rate. That happens while one large file is read, or
while a disk or the database is slow. Each phase names the places it may wait
in, and a phase that may wait in two places names both, as `disk/db`:
- `walk` says `disk`, for files.
- `walk` says `disk`, because it reads directories and stats files.
- `hash` says `disk/db`, because it reads files and writes their records to the
database between them.
- `load`, `update` and the `read` phase of `trees` say `db`.
@@ -1080,8 +1083,9 @@ showing the count it stopped at.
- an operand that does not exist, or whose details `scan` cannot read;
- a list of mounted filesystems that `scan` cannot read;
- another `scan` holding the lock (see "The scan lock");
- a database that cannot be created or opened, or whose reads or writes
fail, its directory and its lock file included;
- a database, its directory or its lock file that cannot be created or
opened;
- a read or write of the database that fails;
- a relative database path when the working directory cannot be read;
- a database at a schema version other than 0 or 1;
- a database at version 0 read by `report`, `trees` or `info`;