OSTREE-REFS(1)

✨ OSTREE-REFS 💅

okay so bestie, this is the manual page for ostree refs from the ostree suite, and I'm gonna walk you through it like we're texting in the group chat. no cap, it's actually super useful. let's get into it 🫶

---

🌸 NAME 🌸

ostree-refs — literally just list refs, that's it, that's the whole vibe ✨

---

🦋 SYNOPSIS 🦋

ostree refs [OPTIONS...] [PREFIX]

ostree refs {EXISTING} {--create=NEWREF}

---

💖 DESCRIPTION 💖

So basically this command lists all the refs chillin' on your host. if you pass a PREFIX, it assigns the refspec prefix — and the default prefix is null, which means it just lists all the refs, no filter, the whole buffet 🍓.

and here's the plot twist: this command can also create or delete refs. it's giving multitalented main character energy, honestly 👑

---

🎀 OPTIONS 🎀

• --list — okay so for historical reasons (iykyk), if you don't pass this option, refs get the specified prefix stripped from the output. but bestie, normally you wanna see the full ref, right? so passing this option means the refs are printed in full instead of truncated. slay 💅
• --create=NEWREF — creates a ref pointing to the commit EXISTING. important: NEWREF must not already exist, and EXISTING must be an existing commit. also, more than one ref can point to the same commit, so no jealousy there 💖
• --delete — deletes refs that match PREFIX instead of listing them. and heads up: if you're trying to reclaim space, you'll then need to run ostree prune or ostree admin cleanup. like, this option is not the whole cleanup, it's just step one, okay? 🧚
• --revision, -r — when you're listing refs, this also prints their revisions. the revisions get separated by a tab character. cute and organized ✨
• --alias, -A — if you use this with --create, it creates an alias. otherwise it just lists aliases. simple as that 🎀
• --collections, -c — enables interactions with refs using the combo of their collection IDs and ref names. when listing refs, this changes the output format to include collection IDs, and it enables listing remote mirrored refs. when creating refs, the refspec value you pass to --create gets treated as COLLECTION-ID:REF-NAME and a mirrored ref is created — and yes, the manpage itself calls this "(This is an abuse of the refspec syntax.)" so like, iconic but chaotic 💀. when deleting refs, all refs whose collection ID equals PREFIX get deleted. periodt.
• --force — when creating NEWREF with --create, this allows an existing ref to be updated instead of erroring out. like a "yeah yeah I know it's there, overwrite it anyway" button 🔥

---

🌈 EXAMPLE 🌈

$ ostree refs

            my-branch
            gnome-ostree/buildmain/x86_64-runtime

see? just a lil list of refs, living their best lives 🌸

---

ngl bestie, the --collections option is doing the most, but the manpage literally admits it's an abuse of the refspec syntax, so we respect the honesty 💜

---

and that's the whole page! written by the OSTree girlies, dated OSTREE REFS(1), and delivered to you with love 🫶✨