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 .
The box beside it filters the plan: type a few letters of a name or of a
rule, in order, and only the files they appear in are listed - capitals and
accents ignored, as a rule with
.Ic (fold yes)
would. While a filter is on,
.Cm Select all
checks what is on screen and the status line says how many checked files
the filter is hiding.
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, its size and age, the action in capitals and coloured by
what it does - the colours are the running GTK theme's own accent,
selection, success, warning and error - where the file would go, and the
rule that decided; a header names the columns, an outcome column appears
once a plan has been applied, and size, age and rule can each be turned off
under
.Cm Settings .
Selecting a row explains it beside the list: the name, how big and how old
the file is, and a line per step with its action, rule and reason. A file krino could not
decide about - unreadable content, a failed duplicate check - is listed with
the reason and cannot be selected.
.Pp
The explanation also 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. Every divider is kept where it is put: the one between the file list and
the explanation, and the one above the preview, each remembered for the
layout it belongs to, so the next window opens as this one was left. A PDF
page is rendered to suit the preview's 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;
.Cm With checked
does the same for every checked file at once. Either way the plan changes
and nothing else: the files move when
.Cm Apply
is pressed, and closing the window with a plan still unapplied says so
before it goes.
.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 - how the tab is arranged (the file
list beside the explanation, or above it with the preview to its side), how
tall the preview is, whether a scan starts with every file checked or none, whether the configuration is coloured, and whether the file behind a
row is shown. 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.