Skip to content

Hidden Entities

An entity can be hidden, which keeps it out of lists and bulk operations without deleting it or changing what it does, much as a file whose name starts with a dot is left out of ls. Units, Spaces, Filters, Triggers, Targets, Tags, ChangeSets, and most other entities can be hidden. ConfigHub hides some entities itself, such as backing Units, and you can hide others that you want out of the way, such as Units you have retired but want to keep.

Hiding an entity

An entity is hidden when its HiddenReason is set. The reason is a name of your choosing, spelled like a slug: letters, digits, -, _, and ., up to 64 characters, such as Archived or Deprecated. Set it with --hidden-reason on an entity's create or update command, and clear it with -, which shows the entity again:

cub unit update --space my-space --patch old-cache --hidden-reason Archived
cub unit update --space my-space --patch old-cache --hidden-reason -

ConfigHub uses the reason BackingUnit for the backing Units that hold the configuration of other entities: a ConfigHub/YAML Unit is created hidden with that reason unless it is given another.

What hiding changes

A hidden entity is left out of:

  • Lists and searches, such as cub unit list and the lists in the UI.
  • Bulk operations, such as cub unit update --patch --where ..., bulk delete, clone, move, tag, and running functions with cub function do --where .... An operation acts only on what a list with the same selection would show, so it can't change an entity you couldn't see it select.

Hiding changes nothing else about the entity. Getting it by name, with cub unit get for example, works as before. Triggers keep running on hidden Units, and hidden entities are still selected by what other entities store: a Space's WhereTrigger and TriggerFilter, a Trigger's WhereUnit, a Target's Trigger selection, and the selections of ChangeOrders and promotion.

Selecting hidden entities

A list or bulk operation includes hidden entities when asked to:

  • --include-hidden=<reasons> includes those hidden for the given reasons, separated by commas, such as --include-hidden=Archived. --include-hidden with no value includes entities hidden for any reason. Every command that takes --where takes it.
  • A --where that names entities, by Slug or ID with = or IN, selects them whether hidden or not, so a command that names the entities it acts on finds them. A --where that names HiddenReason selects hidden entities too, so --where "HiddenReason = 'Archived'" lists the archived ones.
  • A Filter can include hidden entities wherever it is applied to a list or bulk operation, through its IncludeHidden, which takes reasons as --include-hidden does:
cub filter create --space my-space with-archived Unit --include-hidden-field Archived
cub unit list --space my-space --include-hidden=Archived
cub unit list --space my-space --where "HiddenReason = 'Archived'"

A hidden entity's HiddenReason is shown by cub <entity> get, as the Hidden Reason row.