bupstash-query-language
SYNOPSIS
The bupstash query language used by bupstash commands.
DESCRIPTION
The bupstash query language is used to filter and select items from a bupstash repository. Check
the examples section for practical uses, or read the language section for a more precise description.
EXAMPLES
Glob matching:
$ bupstash list name="*.tar"
... name=foo.tar
... name=bar.tar
Literal matching:
$ bupstash list name=="*.tar"
...
Age based matching:
$ bupstash list newer-than "1 month"
$ bupstash list older-than 2d
$ bupstash list older-than 1y
...
And condition matching:
$ bupstash list type=backup and hostname=server1 hostname=server2
...
Or condition matching:
$ bupstash list hostname=server1 or hostname=server2
...
Precedence grouping:
$ bupstash list [hostname=server1 or hostname=server2] and date=2020-*
...
Quote using your shell's builtin quoting:
$ bupstash rm name="my files.tar"
LANGUAGE
Delimiters
As queries may span multiple command line arguments, the gap between arguments is treated as a special
delimiting character for the sake of query parsing.
A tag name is a string containg a set of characters matching the regular
expression [A-Za-z0-9-_]+.
A values is a set of any characters except a delimiter.
Durations
A duration is a concatenation of time spans, where each time span is an integer number and a suffix.
Supported suffixes:
- seconds, second, sec, s
- minutes, minute, min, m
- hours, hour, hr, h
- days, day, d
- weeks, week, w
- months, month, M -- defined as 30.44 days
- years, year, y -- defined as 365.25 days
Globbing
Some operators accept a glob to match against, the following describes the valid globbing meta characters.
? matches any single character.
* matches any (possibly empty) sequence of characters.
** matches the current directory and arbitrary subdirectories. This sequence must form a single path component, so both **a and b** are invalid and will result in an error. A sequence of more than two consecutive * characters is also invalid.
[...] matches any character inside the brackets. Character sequences can also specify ranges of characters, as ordered by Unicode, so e.g. [0-9] specifies any character between 0 and 9 inclusive. An unclosed bracket is invalid.
[!...] is the negation of [...], i.e. it matches any characters not in the brackets.
The metacharacters ?, *, [, ] can be matched by using brackets (e.g. [?]). When a ] occurs immediately following [ or [! then it is interpreted as being part of, rather then ending, the character set, so ] and NOT ] can be matched by []] and [!]] respectively. The - character can be specified inside a character sequence pattern by placing it at the start or the end, e.g. [abc-].
(Documentation taken from the underlying glob software library).
Binary operators
Check a tag matches a glob:
TAGNAME = GLOB
Check a tag matches a literal value.
TAGNAME == VALUE
Match if either expression matches.
EXPR or EXPR
Match if both expressions match.
EXPR and EXPR
Age matching
older-than DURATION
newer-than DURATION
Take care that system clocks are configured correctly on both the querying machine, and devices sending backups, as incorrect
system clocks could cause accidental removal of items.
Unary operators
Invert an expression.
~ EXPR
grouping
Use brackets to alter the default precedence.
[ EXPR ]
Note, This differs from the typical tradition of using () for grouping so queries are
easier to write in shell scripts where () already has design a designated meaning.
SEE ALSO
bupstash, bupstash-put, bupstash-list, bupstash-rm