path: root/man/krino-gui.1

.\" SPDX-License-Identifier: GPL-3.0-or-later
.Dd September 17, 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, and shows the file itself underneath: a picture for an image, the
first page for a PDF, the first lines for anything that is text. Nothing
else is opened, and the file is only read. The divider above the preview
sets how tall it is - drag it, and the next window opens the same way; a
PDF page is rendered to suit that size, and
.Cm Settings
has the number for setting it exactly. 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
This tab edits a directory's own file,
.Pa dirs/NAME.conf ;
the includes and excludes of
.Pa krino.conf
are edited by hand, and its defaults under
.Cm Settings .
.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, with line numbers and the forms coloured: comments,
strings, the head of each form, and the actions that move or delete a file.
.Pp
Either way the configuration is checked as it is edited, about a second
after typing stops, and
.Cm Check
asks for it at once. Problems are listed under both, 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;
.Cm Test rule
scans the directory and lists the files the selected rule would take.
.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.
.Ss Settings
.Cm Settings ,
at the top right of the window, holds two things. The first is krino's own
defaults - case, fold, recursive, min-age, max-read, max-size, busy,
on-conflict and the log path - which every directory inherits and its own
file may override; they are written to
.Pa krino.conf
by the rules above: refused while the configuration would not load, the
previous text kept as
.Pa krino.conf.bak .
The second is how this window behaves - the editor's font size, how tall the
preview is, whether the configuration is coloured, whether the file behind a
row is shown, and whether a scanned plan starts with every file checked. Those take effect as
they are changed and are kept in
.Pa gui.json ,
which krino itself never reads.
.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;
.Pa krino.conf.bak
likewise for the main file.
.It Pa ~/.config/krino/gui.json
How this window behaves. Deleting it restores the defaults.
.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.