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