Names, labels, and identifiers
Mutagen provides three mechanisms for identifying and selecting sessions: names, labels, and session identifiers. These mechanisms can be used to identify sessions in listings and to select sessions when using session management commands.
Names are user-provided identifiers that can be attached to sessions. Names are
optional and aren’t guaranteed to be unique. Each session can have only a single
name. Names are particularly useful for manual usage, where a simple identifier
for selecting sessions is desirable and the chance of name collisions is low.
Names can currently contain any Unicode letter (Unicode category L), number
(Unicode category N), or a dash (
-), though they must start with a letter.
Names, if provided, must also be non-empty and must not be “defaults”.
Names can be provided to session management commands as arguments, in which case all sessions with a matching name will be selected.
Labels are user-provided key/value pairs that are attached to sessions, allowing sessions to be selected via a query. Mutagen re-uses the Kubernetes label and selector implementation and thus shares the same syntax/semantics and selector format.
Label selectors can be provided to session management commands using the
--label-selector flag, in which case all sessions with labels matching the
selector will be selected.
Each Mutagen session is also assigned a unique identifier that allows it to be
addressed unambiguously. These values are printed at session creation time and
can also be found via the
mutagen sync list and
mutagen forward list
Session identifiers can be provided to session management commands as arguments, providing the most reliable way to uniquely identify sessions.