borg alias -- create additional names/aliases for an existing archive

[billyc]

I put together a first stab at a new borg tag command in a fork at
https://github.com/billyc/borg

The commit itself is at:
billyc@9cbcddb

Before I do a PR, I assume a much broader discussion needs to happen! Please consider this code a starting point to help frame the conversation. I tried to make the least-invasive changes possible to implement tags; I hope it's easy to follow. I also want to note that this is my first attempt at hacking Borg so I'm very open to changes or improvements in how I've done things.

I am now writing tests to match the new code I've written -- but I don't want to get too far if the main project authors think this is a bad idea or has major design problems.

Having said that, the good news is: it seems to work! I'm excited. =)

User Interface

usage: borg tag [-h] [--critical] [--error] [--warning] [--info] [--debug]
                [--debug-topic TOPIC] [--log-json] [--lock-wait N]
                [--show-version] [--show-rc] [--no-files-cache] [--umask M]
                [--remote-path PATH] [--remote-ratelimit rate]
                [--consider-part-files] [--list]
                [REPOSITORY_OR_ARCHIVE] [TAGS [TAGS ...]]

Create or manage repository tags

positional arguments:
  REPOSITORY_OR_ARCHIVE         repository or archive to tag
  TAGS                          tags to add to archive

optional arguments:
  --list, -l                    list existing tags

Common options:
  [-snip-]

The tag command creates additional names which point to existing archives.

Once created, a tag can be used in place of the archive name anywhere that an
archive name is required in Borg.

Tag names must be unique. Multiple tags can point to the same archive.

Archives with associated tags cannot be deleted until those tags are deleted first.

Internal Design

At first I thought tags should be new properties in the metadata for the Archive elements. After experimenting with that and having some trouble, a different design emerged which felt a bit cleaner: I added a "tags" dictionary property to the repository Manifest itself.

I think that in real usage, a tag will be created once and then referred to many times in borg extract commands. The tag dictionary in the manifest makes this straightforward: the dict uses the tag name as key and the archive name as value. This means that going in the other direction (getting a list of tags which are linked to a specific archive) requires scanning the dict. I'm open to suggestions on how to improve this.

Questions and comments

• There is a new "tags" property in the repository manifest. I am not sure what consequences will arise for old versions of Borg accessing new repositories, or vice-versa. All existing unit tests passed in the test suite, but I don't know how much coverage there is for old borg versions.

• The word "tag" is already used in the borg usage guide, referring to tagging data for pruning/deleting. Is it confusing to have a new tag command that is something different? I feel like the usage I've created is strongly parallel to the functionality of git tag in source control systems. We could use a different command name such as borg alias to avoid the overlap, but I think that would actually be more confusing for end-users who are already familiar with git.

• I modified the output of borg list to show a --> pointing from a tag to the archive name, to make clear that it's a tag. Is that sufficient? Is there a better or more standard way of conveying this information?

• I modified the list, info, rename, and delete commands to handle tags.

• Attempting to delete an archive that has associated tags will result in an error, unless you use --force --force

I hope others find this addition useful, and I look forward to the discussion!

[billyc]

Rereading issue #846 "Tagging archives for prune" -- I've implemented something fairly different. This is more like git tags, and less like Gmail labels. I think a labeling feature is what's discussed in #846.

[ThomasWaldmann]

Hmm, why did you do tag -> name and not tag -> id?

• archive name can be renamed, id stays same (usually)
• but: recreate changes an archive, creating a new one. here id changes, name might be same.

[billyc]

@ThomasWaldmann no specific reason for using the name instead of ID. I thought the archive name would be most identifiable for the user. I could switch to using the ID or have the archive rename command also fix up any tags pointing to it... whichever makes the most sense.

[ThomasWaldmann]

@billyc Guess we'll implement this in master branch, just filed #8425 before re-discovering this ticket.

I did think of tags a bit differently, rather as an archive attribute with a user-defined set of strings. These tags can just be used as an additional selection criteria when selecting archives using --match-archives / -a.

So, not like git, where a tag is just a pointer to some specific commit hash.

[ThomasWaldmann]

Hmm, considering this issue is something rather different, I suggest of talking of it as borg alias (not: borg tag, which will soon be implemented).