PR review comments to be squashed before merge

Author: Jamstah

cmd/skopeo/copy.go

@@ -97,6 +97,9 @@ func parseMultiArch(multiArch string) (copy.ImageListSelection, error) {
 	// CopySpecificImages.
 	case "index-only":
 		return copy.CopySpecificImages, nil
+	// We don't expose CopySpecificImages other than index-only above, because
+	// we currently don't provide an option to choose the images to copy. That
+	// could be added in the future.
 	default:
 		return copy.CopySystemImage, fmt.Errorf("unknown multi-arch option %q. Choose one of the supported options: 'system', 'all', or 'index-only'", multiArch)
 	}

completions/bash/skopeo

@@ -40,6 +40,7 @@ _skopeo_copy() {
     --src-authfile
     --dest-authfile
     --format -f
+    --multi-arch
     --sign-by
     --src-creds --screds
     --src-cert-dir

docs/skopeo-copy.1.md

@@ -68,12 +68,14 @@ Print usage statement
 
 **--multi-arch**
 
-If _source-image_ refers to an index of images for multiple architectures, this option controls what is copied. Default is system.
+Control what is copied if _source-image_ refers to a multi-architecture image. Default is system.
 
 Options:
-- system: Copy the image that matches the system architecture instead of the index
-- all: Copy all of the images in the index and the index itself
-- index-only: Copy only the index itself
+- system: Copy only the image that matches the system architecture
+- all: Copy the full multi-architecture image
+- index-only: Copy only the index
+
+The index-only option usually fails unless the referenced per-architecture images are already present in the destination, or the target registry supports sparse indexes.
 
 **--quiet**, **-q**