plakar-query.7

.Dd November 28, 2025
.Dt PLAKAR-QUERY 7
.Os
.Sh NAME
.Nm plakar-query
.Nd query flags shared among many Plakar subcommands
.Sh DESCRIPTION
What follows is a set of command line arguments that many
.Xr plakar 1
subcommands provide to filter snapshots.
.Pp
There are two kind of flags:
.Bl -tag -width matchers
.It matchers
These allow to select snapshots.
If combined, the result is the union of the various matchers.
.It filters
These instead filter the output of the matchers by yielding snapshots
matching only certain criterias.
If combined, the result is the intersection of the various filters.
.El
.Pp
If no matcher is given, all the snapshots are implicitly selected,
and then filtered according to the given filters, if any.
.Pp
The matchers are divided into:
.Bl -bullet -offset Ds
.It
matchers that select snapshots from the last
.Ar n
unit of time:
.Pp
.Bl -tag -width Ds -compact -offset Ds
.It Fl minutes Ar n
.It Fl hours Ar n
.It Fl days Ar n
.It Fl weeks Ar n
.It Fl months Ar n
.It Fl years Ar n
.El
.Pp
Or that selects snapshots that were done during the last
.Ar n
days of the week:
.Pp
.Bl -tag -width Ds -compact -offset Ds
.It Fl mondays Ar n
.It Fl thuesdays Ar n
.It Fl wednesdays Ar n
.It Fl thursdays Ar n
.It Fl fridays Ar n
.It Fl saturdays Ar n
.It Fl sundays Ar n
.El
.It
matchers that select at most
.Ar n
snapshots per time period:
.Pp
.Bl -tag -width Ds -compact -offset Ds
.It Fl per-minute Ar n
.It Fl per-hour Ar n
.It Fl per-day Ar n
.It Fl per-week Ar n
.It Fl per-month Ar n
.It Fl per-year Ar n
.It Fl per-monday Ar n
.It Fl per-thuesday Ar n
.It Fl per-wednesday Ar n
.It Fl per-thursday Ar n
.It Fl per-friday Ar n
.It Fl per-saturday Ar n
.It Fl per-sunday Ar n
.El
.El
.Pp
The filters are:
.Bl -tag -width tenletters
.It Fl before Ar date
Select snapshots older than given
.Ar date .
The date may be in RFC3339 format, as
.Dq Ar YYYY Ns - Ns Ar mm Ns - Ns Ar DD Ar HH : Ns Ar MM ,
.Dq Ar YYYY Ns - Ns Ar mm Ns - Ns Ar DD Ar HH : Ns Ar MM : Ns Ar SS ,
.Dq Ar YYYY Ns - Ns Ar mm Ns - Ns Ar DD ,
or
.Dq Ar YYYY Ns / Ns Ar mm Ns / Ns Ar DD
where
.Ar YYYY
is a year,
.Ar mm
a month,
.Ar DD
a day,
.Ar HH
a hour in 24 hour format number,
.Ar MM
minutes and
.Ar SS
the number of seconds.
.Pp
Alternatively, human-style intervals like
.Dq half an hour ,
.Dq a month
or
.Dq 2h30m
are also accepted.
.It Fl category Ar name
Select snapshot whose category is
.Ar name .
.It Fl environment Ar name
Select snapshot whose environment is
.Ar name .
.It Fl job Ar name
Select snapshot whose job is
.Ar name .
.It Fl latest
Select only the latest snapshot.
.It Fl name Ar name
Select snapshots whose name is
.Ar name .
.It Fl perimeter Ar name
Select snapshots whose perimeter is
.Ar name .
.It Fl root Ar path
Select snapshots whose root directory is
.Ar path .
May be specified multiple time, snapshots are selected if any of the
given paths matches.
.It Fl since Ar date
Select snapshots newer than the given
.Ar date .
The accepted format is the same as
.Fl before .
.It Fl tag Ar name
Select snapshots tagged with
.Ar name .
May be specified multiple times, and multiple tags may be given at the
same time if comma-separated.
If a tag name is prefixed with an exclamation mark
.Sq \&! ,
the matching is inverted and the snapshot is ignored if it contains
said tag.
.El