umoci-repack(1)(#)

💖 umoci-repack — the manual page, bestie edition 💖

okay so this is umoci-repack(1), part of the umoci family, written by Aleksa Sarai back in DECEMBER 2016 and honestly? iconic from day one. it's the "put my changes BACK" command. the glow-up command. the repackaging. sit down, grab a strawberry 🍓, let's go.

---

✨ NAME ✨

umoci repack — repacks an OCI runtime bundle into an image tag

like... you took an image apart, you did your little edits, and now you're putting it back together as a whole new tag. slay. 💅

---

✨ SYNOPSIS ✨

umoci repack --image=image[:tag] [--compress=compression-type] [--no-
history] [--history.comment=comment] [--history.created_by=created_by]
[--history.author=author] [--history-created=date] [--refresh-bundle]
bundle

---

✨ DESCRIPTION ✨

so here's the vibe 🌸 — you've got a modified OCI bundle that you extracted earlier with umoci-unpack(1), sitting at the path bundle. umoci-repack(1) looks at the rootfs inside that bundle, computes the filesystem delta (aka everything you changed), turns that delta into a delta layer, and appends it to the original image manifest — the exact one you handed to umoci-unpack(1) — and tags the result as a new image tag. new you, same soul. ✨

🚨 real talk: between calling umoci-unpack(1) and umoci-repack(1), you SHOULD NOT touch the OCI image in any way. and specifically? you MUST NOT run umoci-gc(1). do not. i'm serious. that's the one thing that ruins the whole fit. 😭

all your --uid-map and --gid-map settings are implied from the saved values you gave in umoci-unpack(1), so they're not even available here on umoci-repack(1). no notes, they're just handled. 💅

if --no-history was not specified, a history entry gets appended to the tagged OCI image for this change (and the various --history. flags control the values that go in it). wanna go look at that history later? see umoci-stat(1). 👑

also important: the original image tag (the one you used with umoci-unpack(1)) will not be modified — unless the target of umoci-repack(1) is that original image tag. then yeah, it's getting rewritten, that's on you bestie. 🙈

---

✨ OPTIONS ✨

the global options live in umoci(1), fyi.

• --image=image[:tag] — the destination tag for the repacked OCI image. image has to be a path to a valid OCI image (and it must be the same image you used in umoci-unpack(1) to make the bundle), and tag has to be a valid tag name. if another tag already has that same name as tag, it gets overwritten, no cap. if you don't pass tag at all, it defaults to "latest".
• --compress=compression-type — tells umoci what compression type to use when it creates a new layer. the supported compression types are none, gzip, and zstd. and good news: umoci-unpack(1) transparently supports every compression method you can specify with --compress, so no stress there. 🦋

the special value auto makes umoci(1) auto-select the most appropriate compression algorithm based on what the previous layers are compressed with — it tries to use the most recent layer's compression algorithm that it supports. note that auto will never select none automatically, because not compressing tar(1) archives is genuinely really not advisable. don't do it. 💀

if you don't provide a compression-type at all, it defaults to auto.

• --no-history — causes no history entry to be added for this operation. this is not recommended with umoci-repack(1), because it means the history won't include all of the image layers — and that will cause confusion with tools that look at image history. like, messy. don't. 😭
• --history.comment=comment — the comment for the history entry corresponding to this modification of the image. if you leave it unspecified, umoci(1) will generate an implementation-dependent value.
• --history.created_by=created_by — the CreatedBy entry for the history entry corresponding to this modification of the image. if unspecified, umoci(1) will generate an implementation-dependent value.
• --history.author=author — the Author value for the history entry corresponding to this modification of the image. if unspecified, this value will be the image's author value after any modifications were made by this call of umoci-config(1).
• --history-created=date — the creation date for the history entry corresponding to this modification of the image. this has to be an ISO8601 formatted timestamp (see date(1)). if unspecified, the current time is used. ⭐
• --refresh-bundle — whether to update the OCI bundle's metadata (i.e. mtree and umoci metadata) after repacking the image. if it's set, then the new state of the bundle should be equivalent to unpacking the new image tag. very "keep everything in sync" of it. 🫶

---

✨ EXAMPLE ✨

this one downloads an image from a docker(1) registry using skopeo(1), unpacks it with umoci-unpack(1), modifies it, and then repacks it. the full arc. 🌈

% skopeo copy docker://opensuse/amd64:42.2 oci:image:latest
# umoci unpack --image image bundle
# touch bundle/rootfs/a_new_file
# umoci repack --image image:new-42.2 bundle

look at that. one tiny new file, one whole new tag. main character energy. 👑

---

✨ SEE ALSO ✨

umoci(1), umoci-unpack(1)

---

and that's the page!! 🎀 this was repack from the umoci manual, umoci-repack(1)(#) — shoutout to Aleksa Sarai, DECEMBER 2016, we stan a classic. now go repack something, bestie, you've got this. 💖✨🦋