name: Add tag.WithDigest.

Adds a new function to tags to allow appending a digest to the string
output. This allows users to output strings of the form
`repo:tag@digest`, which can often be used to display concise tag +
digest strings.

NOTE: Most clients parsing this string will ignore the tag in favor of the
digest (though there are a few exceptions like dependabot that will
place meaning in the tag). This is still useful for displaying resolved
tags to humans.

pkg/name/tag.go

@@ -54,6 +54,13 @@ func (t Tag) Name() string {
 	return t.Repository.Name() + tagDelim + t.TagStr()
 }
 
+// WithDigest returns the tag string with the given digest appended.
+// This allows for string creation like "my/repo:tag@sha256:abc123".
+// **Note**: this does not validate the digest matches the tag.
+func (t Tag) WithDigest(digest string) string {
+	return strings.Join([]string{t.Repository.Name(), tagDelim, t.TagStr(), digestDelim, digest}, "")
+}
+
 // String returns the original input string.
 func (t Tag) String() string {
 	return t.original

pkg/name/tag_test.go

@@ -160,3 +160,17 @@ func TestOverrideDefault(t *testing.T) {
 		t.Errorf("Name() was incorrect for %v. Wanted: `%s` Got: `%s`", tag, expectedName, actualName)
 	}
 }
+
+func TestWithTag(t *testing.T) {
+	tagNameStr := "ubuntu"
+	tag, err := NewTag(tagNameStr)
+	if err != nil {
+		t.Fatalf("`%s` should be a valid Tag name, got error: %v", tagNameStr, err)
+	}
+
+	expectedName := "index.docker.io/library/ubuntu:latest@sha256:deadbeef"
+	actualName := tag.WithDigest("sha256:deadbeef")
+	if actualName != expectedName {
+		t.Errorf("Name() was incorrect for %v. Wanted: `%s` Got: `%s`", tag, expectedName, actualName)
+	}
+}