borg-match-archives(1)

Name
borg-match-archives - Details regarding match-archives

DESCRIPTION

The --match-archives option matches a given pattern against the list of all archives in the repository. It can be given multiple times.

The patterns can have a prefix of:

•   name: pattern match on the archive name (default)

•   aid: prefix match on the archive id (only one result allowed)

•   user: exact match on the username who created the archive

•   host: exact match on the hostname where the archive was created

•   tags: match on the archive tags

•   date: match on the archive creation timestamp

    In case of a name pattern match, it uses pattern styles similar to the ones described by borg help patterns:

Identical match pattern, selector id: (default)
    Simple string match, must fully match exactly as given.

Shell-style patterns, selector sh:
    Match like on the shell, wildcards like * and ? work.

Regular expressions <https://docs.python.org/3/library/re.html>, selector re:
    Full regular expression support. This is very powerful, but can also get rather complicated.

Date patterns, selector date:
    Match archives by creation timestamp. You can either match a single archive by passing its exact creation time, or all archives created within a given time interval.

    To match a single archive by its exact creation time, use the forms:

•   YYYY-MM-DDTHH:MM:SS.ffffff: ISO-8601-like date-time string

•   @1735732800.123456: UNIX timestamp

    To match a single archive, the pattern must specify the archive's complete creation timestamp, including any fractional seconds. Fractional-second patterns accept 1 to 6 digits.

    To match all archives created within a given time interval, use the forms:

•   YYYY: match all archives created within the given year

•   YYYY-MM: within the given month

•   YYYY-MM-DD: on the given day

•   YYYY-MM-DDTHH: in the given hour

•   YYYY-MM-DDTHH:MM: in the given minute

•   YYYY-MM-DDTHH:MM:SS: in the given second

•   @1735732800: within the 1 second interval from the given UNIX timestamp

    The T date-time separator may also be written as a space, e.g. date:2025-01-01 14:30.

    Date and time patterns match the interval implied by their precision, including the start and excluding the end. For example, date:2026-06 matches archives created on or after 2026-06-01T00:00:00 and before 2026-07-01T00:00:00.

    Date and time patterns may include a timezone suffix: Z (UTC), +HH:MM, -HH:MM, or [Region/City]. Patterns without a timezone are interpreted in the local timezone. Unix timestamps are always UTC and do not accept a timezone suffix.

    Be wary of Daylight Saving Time (DST) transitions, as they can make time intervals ambiguous or nonexistent. For example, named zones such as [Europe/Berlin] track DST, but the equivalent (winter) UTC offset of +01:00 does not. Use UTC to avoid such issues.

    Examples:

        # name match, id: style
        borg delete --match-archives 'id:archive-with-crap'
        borg delete -a 'id:archive-with-crap'  # same, using short option
        borg delete -a 'archive-with-crap'  # same, because 'id:' is the default
        # name match, sh: style
        borg delete -a 'sh:home-kenny-*'
        # name match, re: style
        borg delete -a 're:pc[123]-home-(user1|user2)-2022-09-.*'
        # archive id prefix match:
        borg delete -a 'aid:d34db33f'
        # host or user match
        borg delete -a 'user:kenny'
        borg delete -a 'host:kenny-pc'
        # tags match
        borg delete -a 'tags:TAG1' -a 'tags:TAG2'
        # archive creation date match
        borg delete -a 'date:2025-01'
        borg delete -a 'date:2025-01-01T14:30Z'
        borg delete -a 'date:2025-01-01T09:30[America/New_York]'

Author
The Borg Collective