diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/krino.conf.5 | 123 |
1 files changed, 72 insertions, 51 deletions
diff --git a/man/krino.conf.5 b/man/krino.conf.5 index fbd1c06..0778779 100644 --- a/man/krino.conf.5 +++ b/man/krino.conf.5 @@ -254,6 +254,20 @@ A rule with only .Ic (stop) is an exclusion: files it matches receive no actions from later rules. .Pp +A rule whose condition contains +.Ic (duplicate) +anywhere, including inside +.Ic or +or +.Ic not , +cannot contain +.Ic (delete) +or +.Ic (delete permanent) ; +.Ic krino check +and every run refuse it +.Pq Sx DUPLICATES . +.Pp .Ar dest is a directory: a relative path is relative to the root, .Ql ~ @@ -462,6 +476,11 @@ its directory, and later steps use the new path; .Ic delete ends the chain, and steps after it are shown in the plan as .Dq skipped: deleted by rule Ar x . +A +.Ic delete +of a duplicate is itself skipped +.Pq Sx DUPLICATES +and does not end the chain. .Pp The plan warns when a chain moves a file more than once; that is usually a missing @@ -609,54 +628,62 @@ between and .Dq this should not exist twice exists only in the user's intent, not in the files. -Pairing -.Ic (duplicate) -with -.Ic (delete) -over a directory that may hold intentional copies +A +.Ic move +rule over a directory that holds intentional copies .Pq a mirror, a staging queue, anything another tool manages -will delete things the user meant to keep. -Keep such a rule on a directory scoped narrowly enough that every -byte-identical pair in it really is an accident. +will move things the user meant to keep there; keep such a rule on a +directory scoped narrowly enough that every byte-identical pair in it really +is an accident. .Pp -.Sy Warning: -each +.Sy Duplicates are found, never deleted. +Deciding which copy to remove is left to the user, or to a tool built for it +such as +.Xr jdupes 1 . +A rule combining .Ic (duplicate) -or -.Ic (duplicate Ar dir ) -condition elects its own original from its own candidates; two conditions -with different scopes can therefore elect -.Em different -originals for the same content. -Within one directory's rules -.Pq one rule combining conditions with Ic or , or two separate rules , -this can make every copy in a group selected by some condition, and with -.Ic (delete permanent) -every copy selected is gone for good. -.Ic krino -plans and applies one directory at a time, so a directory already applied -in the run stays applied while a later directory is planned; a -.Fl n -run only ever plans, so it shows every directory's plan as if none of the -others had been applied. -Two files in different directories that a -.Fl n -plan each lists as a duplicate of the other are therefore not necessarily -both deleted when the same run is applied with -.Fl y : -deleting the first can remove the very original the second file was a -duplicate of, leaving the second no longer a duplicate by the time its own -directory is planned. -Use one duplicate scope for rules that delete within a directory; prefer -.Ic (delete) -to -.Ic (delete permanent) -with -.Ic (duplicate) ; -and within one directory's rules, two files each listed as a duplicate of -the other in the -.Fl n -plan means both would be deleted. +with a delete action is refused +.Pq Sx RULES . +And in a directory whose rules use +.Ic (duplicate) , +a file that is a duplicate under any of the duplicate scopes those rules use +\(em each distinct set of +.Ar dir +arguments, and the plain +.Ic (duplicate) , +looked up for the file whether or not evaluation reached that test \(em gets +no delete step from any rule. +The plan shows the step as +.Dq skipped: a duplicate is never deleted , +or, when that lookup fails, +.Dq skipped: duplicate check failed, so not deleted: Ar reason ; +the rest of the chain continues from the file's current path. +This covers what the refusal cannot see: a later rule deleting through +.Ic (matched) +or through a condition of its own. +.Pp +Together they mean no rule can delete every copy of content a duplicate test +in that directory can see. +A file displaced by +.Ic (on-conflict overwrite) +is not covered; it goes to the trash, and +.Ic krino undo +restores it. +.Pp +The way to deal with duplicates is to move them aside and decide later: +.Bd -literal -offset indent +(rule "dupes" + (when (duplicate "~/docs/Archive")) + (move "~/.dupes/") + (stop)) +.Ed +.Pp +Every move is logged, so +.Ic krino undo +puts them back. +Duplicate conditions with different scopes do not share an original, so two +such rules can between them move every copy of a group aside; nothing is +deleted. .Sh KNOWN LIMITATIONS A .Ar dest @@ -682,12 +709,6 @@ Give such a rule its own narrow pattern, or a .Ar dest whose first path component is a literal string, when that matters. -.Pp -.Ic (duplicate) -conditions with different scopes do not share an original: two conditions -electing from different candidate sets can each treat a different file as -the original of the same content -.Pq Sx DUPLICATES . .Sh SEE ALSO .Xr krino 1 .Pp |