update rebase.md docs

cmd/crane/rebase.md

@@ -1,7 +1,7 @@
 ### This code is experimental and might break you if not used correctly.
 
 The `rebase` command efficiently rewrites an image to replace the base image it
-is FROM with a new base image.
+is `FROM` with a new base image.
 
 ![rebase visualization](./rebase.png)
 
@@ -48,20 +48,55 @@ layers in your image with the patched base image layers, without requiring a
 full rebuild from source.
 
 ```
-$ crane rebase \
-  --original=my-app:latest \
+$ crane rebase my-app:latest \
   --old_base=ubuntu@sha256:deadbeef... \
   --new_base=ubuntu:latest \
-  --rebased=my-app:rebased
+  --tag=my-app:rebased
 ```
 
 This command:
 
-1. fetches the manifest for `original`, `old_base` and `new_base`
-1. checks that `old_base` is indeed the basis for `original`
-1. removes `old_base`'s layers from `original`
+1. fetches the manifest for the original image `my-app:latest`, and the
+   `old_base` and `new_base` images
+1. checks that the original image is indeed based on `old_base`
+1. removes `old_base`'s layers from the original image
 1. replaces them with `new_base`'s layers
-1. computes and uploads a new manifest for the image, tagged as `rebased`.
+1. computes and uploads a new manifest for the image, tagged as `--tag`.
+
+If `--tag` is not specified, its value will be assumed to be the original
+image's name. If the original image was specified by digest, the resulting
+image will be pushed by digest only.
+
+`crane rebase` will print the rebased image name by digest to `stdout`.
+
+### Base Image Annotation Hints
+
+The OCI image spec includes some [standard image
+annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md)
+that can provide hints for the `--old_base` and `--new_base` flag values, so
+these don't need to be specified:
+
+- **`org.opencontainers.image.base.digest`** specifies the original digest of
+  the base image
+- **`org.opencontainers.image.base.name`** specifies the original base image's
+  reference
+
+If the original image has these annotations, you can omit the `--old_base` and
+`--new_base` flags, and their values will be assumed to be:
+
+- `--old_base`: the `base.name` annotation value, plus the `base.digest`
+  annotation value
+- `--new_base`: the `base.name` annotation value
+
+If these annotation values are invalid, and the flags aren't set, the operation
+will fail.
+
+Whether or not the annotation values were set on the original image, they
+_will_ be set on the resulting rebased image, to ease future rebase operations
+on that image.
+
+`crane append` also supports the `--set-base-image-annotations` flag, which, if
+true, will set these annotations on the resulting image.
 
 ## Caveats
 
@@ -78,9 +113,9 @@ layers should expect from base layers.
 In the example above, for instance, we assume that the Ubuntu base image is
 adhering to some contract with downstream app layers, that it won't remove or
 drastically change what it provides to the app layer. If the `new_base` layers
-removed some installed package, or made a breaking change to the version of some
-compiler expected by the uppermost app layers, the resulting rebased image might
-be invalid.
+removed some installed package, or made a breaking change to the version of
+some compiler expected by the uppermost app layers, the resulting rebased image
+might be invalid.
 
 In general, it's a good practice to tag rebased images to some other tag than
 the `original` tag, perform some sanity checks, then tag the image to the