Compare commits

..
1 Commits
Author SHA1 Message Date
sneak 0d9442c12d 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. Five `main_test.go` comments cite "Settings", two cite what
"Error handling" says about a failed write to stdout, and one comment
each in `scan_test.go`, `trees_test.go` and `exclude_test.go` cites what
the README now says.

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, and
an operand reached through a symlinked directory below another operand
is dropped (#144).

Model: fable-5-1
2026-10-26 18:54:13 +00:00
2 changed files with 8 additions and 9 deletions

No files matched your search

+6 -6
View File
@@ -369,8 +369,8 @@ default. An operand may be a directory or a regular file.
deleted.
- 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 dropped one is scanned all the
same. The scan keeps the records beneath a dropped operand, unless another
as skipped and drops it. An operand beneath a symlink operand is scanned all
the same. The scan keeps the records beneath a dropped operand, unless another
operand covers them.
- An operand at or inside a directory named `.zfs` is never scanned, whether
given alone or under another operand. The check looks at the path as given and
@@ -724,8 +724,8 @@ Two limitations are accepted:
They share storage, so removing one frees nothing. The scan uses the inode to
avoid reading a file twice, and does not store it.
- Only the regular files in the database define a tree. Empty directories are
invisible. A file skipped during the scan in one copy but not in the other
makes two otherwise identical trees differ.
invisible. When the scan skips a file in one copy but not in the other, the
two trees differ.
`trees` has four phases, each with its own progress display on stderr (see
"Progress"). `open` opens the database. `read` counts the records, then reads
@@ -836,7 +836,7 @@ the error for a missing database comes after it.
#### The scan lock
Only one `scan` runs against a database at a time.
Only one `scan` at a time can hold the lock.
- For its whole run, `scan` holds a lock on a lock file beside the database. The
lock is taken with the `flock(2)` system call, and only one process can hold
@@ -847,7 +847,7 @@ Only one `scan` runs against a database at a time.
Just before that, it creates the database file, empty, if it is missing. So
the lock file is named the same way before the first scan as after. A symlink
at the database path is followed, and its target is created.
- A second `scan` against the same database does not wait. It fails at once with
- A second `scan` that finds the lock held does not wait. It fails at once with
an error naming the lock file, and exits 1. It has walked nothing and has not
opened the database. The running scan carries on.
- The lock file is created on first use and never deleted. Only its owner may
+2 -3
View File
@@ -1279,9 +1279,8 @@ func holdScanLock(t *testing.T, path string) {
}
func TestRunSecondScanFails(t *testing.T) {
// README §Database: while one scan holds the lock, a second scan
// fails at once, naming the lock file, without opening the
// database.
// README §Database: a second scan that finds the lock held fails
// at once, naming the lock file, without opening the database.
path := testDBPath(t)
t.Setenv(databaseEnv, path)