Improve the (skopeo delete) man page #1597
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
vrothberg
reviewed
Mar 18, 2022
docs/skopeo-delete.1.md
Outdated
| ## DESCRIPTION | ||
|
|
||
| Mark _image-name_ for deletion. | ||
| The effect of this is registry-specific; many registries don’t this operation, or don’t allow it in some circumstances / configurations. |
There was a problem hiding this comment.
Suggested change
| The effect of this is registry-specific; many registries don’t this operation, or don’t allow it in some circumstances / configurations. | |
| The effect of this is registry-specific; many registries don’t support this operation, or don’t allow it in some circumstances / configurations. |
| Mark _image-name_ for deletion. | ||
| The effect of this is registry-specific; many registries don’t this operation, or don’t allow it in some circumstances / configurations. | ||
|
|
||
| **WARNING**: If _image-name_ contains a digest, this affects the referenced manifest, and may delete all tags (within the current repository?) pointing to that manifest. |
There was a problem hiding this comment.
Suggested change
| **WARNING**: If _image-name_ contains a digest, this affects the referenced manifest, and may delete all tags (within the current repository?) pointing to that manifest. | |
| **WARNING**: If _image-name_ contains a digest, this affects the referenced manifest, and may delete all tags pointing to that manifest. |
I am quite confused by that. In case it's important, could you rephrase?
There was a problem hiding this comment.
After pushing the same image (same digest) to
- repo1:tag1A
- repo1:tag1B
- repo2:tag2A
- repo2:tag2B
the distribution/distribution implementation of deleting repo1@digest is to untag repo1:tag1A and repo1:tag1B, but not repo2:tag2A and repo2:tag2B.
The specification does not describe any of this in detail.
Should the text say something like “all tags within the relevant repository that point to the manifest in question” without the parentheses and the question mark? That’s probably the most reasonable behavior, I just don’t have any data about what various registries do.
docs/skopeo-delete.1.md
Outdated
|
|
||
| **WARNING**: If _image-name_ contains a digest, this affects the referenced manifest, and may delete all tags (within the current repository?) pointing to that manifest. | ||
|
|
||
| **WARNING**: If _image-name_ contains a tag (but not a digest), currently this resolves the tag into a digest, and then deletes the manifest by digest, as described above (possibly deleting all tags pointing to that manifest, not just the provided tag.) This behavior may change in the future. |
There was a problem hiding this comment.
Suggested change
| **WARNING**: If _image-name_ contains a tag (but not a digest), currently this resolves the tag into a digest, and then deletes the manifest by digest, as described above (possibly deleting all tags pointing to that manifest, not just the provided tag.) This behavior may change in the future. | |
| **WARNING**: If _image-name_ contains a tag (but not a digest), currently this resolves the tag into a digest, and then deletes the manifest by digest, as described above (possibly deleting all tags pointing to that manifest, not just the provided tag). This behavior may change in the future. |
docs/skopeo-delete.1.md
Outdated
|
|
||
| **WARNING**: If _image-name_ contains a digest, this affects the referenced manifest, and may delete all tags (within the current repository?) pointing to that manifest. | ||
|
|
||
| **WARNING**: If _image-name_ contains a tag (but not a digest), currently this resolves the tag into a digest, and then deletes the manifest by digest, as described above (possibly deleting all tags pointing to that manifest, not just the provided tag.) This behavior may change in the future. |
There was a problem hiding this comment.
Minor tweak for consideration
Suggested change
| **WARNING**: If _image-name_ contains a tag (but not a digest), currently this resolves the tag into a digest, and then deletes the manifest by digest, as described above (possibly deleting all tags pointing to that manifest, not just the provided tag.) This behavior may change in the future. | |
| **WARNING**: If _image-name_ contains a tag (but not a digest), this resolves the tag into a digest and then deletes the manifest by digest, as described above (possibly deleting all tags pointing to that manifest, not just the provided tag). This behavior may change in the future. |
There was a problem hiding this comment.
The intent of “currently” was to give us an opportunity to change this problematic design. I have replaced that with “in the current version of Skopeo”, is that clearer?
Actually add a DESCRIPTION heading. Warn about deleting by digest - it affects an unknown set of tags. Warn about deleting by tag - it currently works by the resolved digest. Signed-off-by: Miloslav Trmač <mitr@redhat.com>
|
LGTM |
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
… per containers/image#1010 , at least as a short-term stopgap. Compare that issue, and #1432, for much more about possible code improvements.