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

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

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.

Identifiers

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 commands.

Session identifiers can be provided to session management commands as arguments, providing the most reliable way to uniquely identify sessions.