Merge branch '281695-docs-feedback-registry-garbage-collector' into 'master'

Resolve "Docs feedback: registry garbage collector"

See merge request gitlab-org/gitlab!47860

doc/administration/packages/container_registry.md

@@ -829,11 +829,11 @@ If you changed the location of the Container Registry `config.yml`:
 sudo gitlab-ctl registry-garbage-collect /path/to/config.yml
 ```
 
-You may also [remove all unreferenced manifests](#removing-unused-layers-not-referenced-by-manifests),
+You may also [remove all untagged manifests and unreferenced layers](#removing-untagged-manifests-and-unreferenced-layers),
 although this is a way more destructive operation, and you should first
 understand the implications.
 
-### Removing unused layers not referenced by manifests
+### Removing untagged manifests and unreferenced layers
 
 > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/3097) in Omnibus GitLab 11.10.
 
@@ -841,11 +841,11 @@ DANGER: **Warning:**
 This is a destructive operation.
 
 The GitLab Container Registry follows the same default workflow as Docker Distribution:
-retain all layers, even ones that are unreferenced directly to allow all content
-to be accessed using context addressable identifiers.
+retain untagged manifests and all layers, even ones that are not referenced directly. All content
+can be accessed by using context addressable identifiers.
 
-However, in most workflows, you don't care about old layers if they are not directly
-referenced by the registry tag. The `registry-garbage-collect` command supports the
+However, in most workflows, you don't care about untagged manifests and old layers if they are not directly
+referenced by a tagged manifest. The `registry-garbage-collect` command supports the
 `-m` switch to allow you to remove all unreferenced manifests and layers that are
 not directly accessible via `tag`:
 
@@ -853,6 +853,8 @@ not directly accessible via `tag`:
 sudo gitlab-ctl registry-garbage-collect -m
 ```
 
+Without the `-m` flag, the Container Registry only removes layers that are not referenced by any manifest, tagged or not.
+
 Since this is a way more destructive operation, this behavior is disabled by default.
 You are likely expecting this way of operation, but before doing that, ensure
 that you have backed up all registry data.
@@ -946,6 +948,8 @@ PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
 5 4 * * 0  root gitlab-ctl registry-garbage-collect
 ```
 
+You may want to add the `-m` flag to [remove untagged manifests and unreferenced layers](#removing-untagged-manifests-and-unreferenced-layers).
+
 ## Troubleshooting
 
 Before diving in to the following sections, here's some basic troubleshooting:

doc/user/packages/container_registry/index.md

@@ -447,7 +447,7 @@ For the project where it's defined, tags matching the regex pattern are removed.
 The underlying layers and images remain.
 
 To delete the underlying layers and images that aren't associated with any tags, administrators can use
-[garbage collection](../../../administration/packages/container_registry.md#removing-unused-layers-not-referenced-by-manifests) with the `-m` switch.
+[garbage collection](../../../administration/packages/container_registry.md#removing-untagged-manifests-and-unreferenced-layers) with the `-m` switch.
 
 ### Enable the cleanup policy