From 8d0a4024b76b7e85c0ccede853fc2cdcceea2afb Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Tue, 15 Sep 2026 22:32:35 +0200 Subject: check refuses an empty time format; krino.conf(5) corrected from the re-audit --- man/krino.conf.5 | 130 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 85 insertions(+), 45 deletions(-) (limited to 'man/krino.conf.5') diff --git a/man/krino.conf.5 b/man/krino.conf.5 index 14e473f..8f3668b 100644 --- a/man/krino.conf.5 +++ b/man/krino.conf.5 @@ -78,8 +78,11 @@ or with .Sy yes also those in subdirectories down to .Ic max-depth . -Symbolic links are never followed and anything that is not a regular file -is left out. +Symbolic links are never followed, and a symbolic link or anything else +that is not a regular file is counted and listed as +.Dq symlink +or +.Dq not a regular file . The walk does not enter a copy or move destination that lies inside the directory .Pq Sx Unscanned destinations , @@ -155,12 +158,17 @@ Then write rules in .Pa dirs/dl.conf and, before anything is applied, repeat: .Bl -tag -width Ds -.It Ic krino check Ar name -Reads the whole configuration and reports every mistake as +.It Ic krino check Op Ar name +Reads +.Pa krino.conf +and the named directory's file +.Pq every included directory's, with no name , +reports mistakes as .Ar file : Ns Ar line : Ns Ar col -.Pq Sx Mistakes check reports ; -lists each directory's exclusions and rules, and the extraction tools found. -A configuration with any mistake is refused as a whole: no run starts. +.Pq Sx Mistakes check reports , +and lists each directory's exclusions and rules and the extraction tools +found. +A run refuses to start while a file it reads has a mistake. .It Ic krino -n -v Ar name The plan, without changing any file: each file krino would act on with its steps, the rule and the tests that made it match, then the files excluded, @@ -205,7 +213,8 @@ and .Pa report.pdf beside a .Pa report.pdf.part -still downloading. +still downloading, all modified more than two minutes ago +.Pq the built-in Ic min-age . .Pa dirs/dl.conf : .Bd -literal -offset indent (path "~/dl") @@ -305,10 +314,14 @@ rule old-installers: not evaluated, stopped by rule screenshots rule images: not evaluated, stopped by rule screenshots .Ed .Ss Mistakes check reports -Every form is checked when the configuration is read, by +Every form is checked when a file is read, by .Ic krino check -and by every run; nothing is scanned until all of it is right. -Some of the messages, as printed (long ones wrapped here): +and by every run, and nothing is scanned while a file that run reads has a +mistake. +Several mistakes in one file are reported together, but only the first in +each rule: fix it and check again. +Some of the messages, as printed +.Pq the path shortened, long ones wrapped here : .Bd -literal -offset indent dl.conf: no (path ...): say which directory this file sorts dl.conf:2:11: rule "a": (when) needs a condition; leave it out @@ -338,7 +351,7 @@ dl.conf:2:24: rule "a" defined twice (first at line 2) A rule combining .Ic (duplicate) with a delete action, a placeholder that could never expand -.Pq Ic {foo} , Ic {mtime} No without a format, Ic {0} , Ic {10} , No an unclosed Ic { +.Pq Ic {foo} , Ic {mtime} No or Ic {mtime:} No without a format, Ic {0} , Ic {10} , No an unclosed Ic { and a .Ic {N} beyond the name test's groups are refused the same way. @@ -526,8 +539,8 @@ Built-in: .Sy 2m . .It Ic max-read A size. -No content is extracted from a file above this size, and a document or -tool whose text grows past it is content unreadable. +No content is extracted from a file above this size, and a pdf, zip-based +document or tool output whose text grows past it is content unreadable. .Sy 0 means unlimited. Built-in: @@ -671,13 +684,15 @@ Once this rule matches, evaluate no further rules for this file. .Pp A rule with only .Ic (stop) -keeps the files it matches from every later rule, and so does one whose -condition cannot be decided +keeps the files it matches from every later rule; so does a rule with +.Ic (stop) +whose condition cannot be decided .Pq Sx Operators . -It does not undo what earlier rules planned and is not listed as excluded; -an +A file left with no steps is counted and listed as excluded, with the rule +that stopped it; but a stop rule does not undo what earlier rules planned, +while an .Ic exclude -sets a file aside from every rule. +sets a file aside before any rule. .Pp A rule whose condition contains .Ic (duplicate) @@ -694,10 +709,17 @@ and every run refuse it .Pq Sx DUPLICATES . .Pp .Ar dest -is a directory: a relative path is relative to the root, a leading +is a directory: a relative path is relative to the root, .Ql ~ -is the home directory, an absolute path is allowed, and it is created if -missing. +alone or a leading +.Ql ~/ +is the home directory +.Po +.Ql ~foo/x +is a relative path under the root, though the plan shows it as +.Ql ~foo/x/ +.Pc , +an absolute path is allowed, and it is created if missing. .Ar dest and .Ar name @@ -714,15 +736,20 @@ placeholders produce an empty name, or .Ql \&.. . .Ss Unscanned destinations -The part of every +Every .Ic copy and .Ic move -destination before its first placeholder, cut back to the last -.Ql / , -is not scanned when it lies inside the directory, so files +destination that lies inside the directory is not scanned, so files .Nm krino -has filed are not sorted again: +has filed are not sorted again: a destination without placeholders is left +out whole, so +.Ql Pictures +leaves out +.Pa Pictures ; +one with placeholders is left out up to the last +.Ql / +before its first placeholder: .Ql Work/Acme/{mtime:%Y} leaves out .Pa Work/Acme , @@ -785,20 +812,28 @@ and .Ic or , and several conditions in one .Ic when , -are evaluated cheapest first: +are evaluated cheapest first. +A test costs, from least to most: .Ic type , size , age and -.Ic matched , +.Ic matched ; then .Ic name and -.Ic path , +.Ic path ; then -.Ic duplicate , +.Ic duplicate ; then -.Ic content ; -tests of equal cost keep their written order, and evaluation stops as soon -as the answer is known. +.Ic content . +A nested +.Ic (and ...) +or +.Ic (or ...) +costs the sum of its arguments, and a +.Ic (not ...) +costs what its argument costs. +Arguments of equal cost keep their written order, and evaluation stops as +soon as the answer is known. The order never changes whether a condition is true, but it decides which .Ic name test supplies the captures and whether a slow test runs at all. @@ -955,8 +990,9 @@ Groups overlap; a file can belong to several. .Bl -tag -width "presentation" .It Sy text txt md log csv tsv json yaml yml toml ini conf cfg rtf tex go c h cpp hpp -py sh js ts rs java rb pl lua css sql: read as text; bytes that are not -valid UTF-8 are read as Latin-1. +py sh js ts rs java rb pl lua css sql: read as text. +A file that is not valid UTF-8 as a whole is read as Latin-1, one character +per byte, so a single stray byte makes its UTF-8 letters no longer match. .It Sy pdf .Ic pdftotext .Pq 30 second timeout . @@ -974,8 +1010,8 @@ or .Ic catppt .Pq both from catdoc . .It Sy anything else -Detected from its first 8 KiB: valid UTF-8 with no NUL byte, or UTF-16 with a -byte-order mark, is read as text, if the rest of the file agrees. +Detected from its first 8 KiB: a UTF-16 byte-order mark is read as text; +valid UTF-8 with no NUL byte is read as text if the rest of the file is too. Otherwise it has no content: images, audio, archives and other binary files, and a file that turns binary further on, such as a self-extracting installer. .El @@ -985,7 +1021,8 @@ External tools are optional and looked up once per run; lists which were found. A file above .Ic max-read -is not extracted, and extraction that yields more text than +is not extracted, and a pdf, zip-based document or tool output whose text +grows past .Ic max-read stops as content unreadable. Tools run without a shell and are given absolute paths only, so a file @@ -1088,8 +1125,9 @@ or a move. .El .Pp Before each step, the executor checks that the source is still the file -planned: a regular file with the same inode, size and modification time; if -not, the step fails as +planned: a regular file with the same size and modification time, and, while +it is still at its scanned path, the same device and inode; if not, the step +fails as .Dq changed since plan and the rest of that file's chain is skipped. .Ss Placeholders @@ -1239,13 +1277,15 @@ The .Em original in each group is, in order of preference: a file under one of the given .Ar dir -arguments, then the oldest by modification time, then the shortest name, -then the name that sorts first, then the full path that sorts first. +arguments, then the oldest by modification time, then the shortest name in +bytes, then the name that sorts first, then the full path that sorts first. .Ic (duplicate) is true for every other scanned file in the group. Excluded files are candidates too, and can be the original. -A lookup that fails, because a file cannot be read, makes the test unknown -.Pq Sx Operators . +When the tested file itself cannot be read, the test is unknown +.Pq Sx Operators ; +another file of the same size that cannot be read is left out of the +comparison with a warning, so the test can still be false. .Pp .Sy Warning: .Ic (duplicate) -- cgit v1.3