krino-gui(1), README and changelog for 0.0.10v0.0.10

1 files changed, 136 insertions, 0 deletions

diff --git a/man/krino-gui.1 b/man/krino-gui.1
new file mode 100644
index 0000000..5f7b803
--- /dev/null
+++ b/man/krino-gui.1
@@ -0,0 +1,136 @@
+.\" SPDX-License-Identifier: GPL-3.0-or-later
+.Dd September 16, 2026
+.Dt KRINO-GUI 1
+.Os
+.Sh NAME
+.Nm krino-gui
+.Nd review, undo and edit krino's rules in a window
+.Sh SYNOPSIS
+.Nm
+.Op Fl c Ar file
+.Op Fl version
+.Sh DESCRIPTION
+.Nm
+is a GTK 4 window onto the same engine
+.Xr krino 1
+uses: it plans a directory, shows what would happen to each file, applies
+what you choose, undoes a run, and edits a directory's rules. Every
+decision - what matches, what is excluded, where a file lands, what may be
+deleted - is the engine's, so the window and the command line always agree.
+.Pp
+It is a separate program from
+.Xr krino 1 ,
+built and installed separately
+.Pq Cm make gui , Cm make install-gui ,
+because it needs GTK 4 and cgo, which the command line does not.
+.Pp
+The options are:
+.Bl -tag -width Ds
+.It Fl c Ar file
+Use
+.Ar file
+instead of
+.Pa ~/.config/krino/krino.conf .
+.It Fl version
+Print the version and exit.
+.El
+.Pp
+A configuration that does not load is reported the way
+.Xr krino 1
+reports it, and no window opens.
+.Ss Plan
+Pick one of the directories
+.Pa krino.conf
+includes and press
+.Cm Scan .
+Scanning takes that directory's lock, which is held while the plan is
+shown, so nothing moves underneath it; a directory another krino is working
+in is reported rather than waited for. Each row is a file, what would
+happen to it and where, and the rule that decided. A file krino could not
+decide about - unreadable content, a failed duplicate check - is listed with
+the reason and cannot be selected.
+.Pp
+Selecting a row explains it: every step with its rule and reason, and any
+warning. The right button offers
+.Cm Trash instead
+and
+.Cm Delete permanently instead ,
+the second only after a confirmation naming the file, as the
+.Cm t
+and
+.Cm d
+keys do in the terminal review.
+.Pp
+.Cm Apply
+acts on the checked files and logs the rest as declined, exactly as
+approving file by file in the terminal does. The run is written to the log
+under its own run id, so
+.Xr krino 1
+can list and undo it.
+.Ss History and undo
+The runs, newest first, with what each did and whether it has been undone.
+Selecting one shows its reversal: a row per file, refused files with the
+reason and never checkable, and the counts. Undoing takes the locks of
+every directory involved, reverses the checked files, and logs the rest as
+declined. Selecting an undo run offers what is left of the run it reversed,
+as plain
+.Cm krino undo
+does.
+.Ss Rules
+Only a directory's own file,
+.Pa dirs/NAME.conf ,
+is edited;
+.Pa krino.conf
+is not.
+.Pp
+.Cm Forms
+lists the directory itself, its excludes and its rules. A rule's form holds
+its name, its conditions, its actions in order,
+.Ic (stop) ,
+and the three rule settings; the directory's form holds the settings
+.Xr krino.conf 5
+documents, an empty field meaning krino's default. A condition is its kind
+and its arguments as the file writes them, so no test is out of reach and
+none is silently rewritten.
+.Cm Add rule
+inserts after the selected rule,
+.Cm Delete
+asks first, and
+.Cm Up
+and
+.Cm Down
+move a rule with the comment lines directly above it.
+.Pp
+.Cm Text
+is the whole file. Either way the configuration is checked as it is edited,
+about a second after typing stops: problems are listed with
+.Ar file : Ns Ar line : Ns Ar column ,
+and clicking one goes to that line.
+.Cm Test on file
+answers what the unsaved rules would do to one file, with the trace, the
+captures and the chain.
+.Pp
+.Cm Save
+is refused while the check reports anything, so a window cannot leave krino
+unable to run. It writes atomically, keeps what was there as
+.Pa NAME.conf.bak ,
+and, if the file changed on disk since it was opened, offers to reload,
+overwrite or cancel. Nothing on disk changes until Apply, Undo or Save.
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa ~/.config/krino/krino.conf
+The main configuration, as for
+.Xr krino 1 .
+.It Pa ~/.config/krino/dirs/NAME.conf
+A directory's rules, and what the Rules tab edits.
+.It Pa ~/.config/krino/dirs/NAME.conf.bak
+The text a save replaced.
+.El
+.Sh EXIT STATUS
+.Ex -std
+It exits 2 when the configuration does not load.
+.Sh SEE ALSO
+.Xr krino 1 ,
+.Xr krino.conf 5
+.Sh AUTHORS
+krino is free software under the GPL, version 3 or later.