SYSTEMD-VPICK(1)

💖 SYSTEMD-VPICK 💖

okay bestie, welcome to the systemd-vpick manual page, she's a little icon and she's about to make your versioned-directory life SO much easier 🎀

---

✨ NAME ✨

systemd-vpick — resolving paths to those cute .v/ versioned directories 🦋

---

🌸 SYNOPSIS 🌸

systemd-vpick [OPTIONS...] [PATH...]

---

👑 DESCRIPTION 👑

so like, here's the vibe: systemd-vpick takes a file system path that points at a .v/ versioned directory and resolves it to a path pointing at the newest file inside it (newest by version, obviously, we're not animals 💅). Basically it's a command line interface for all that systemd.v(7) logic you've heard about. No cap.

The tool wants a path to a .v/ directory as its argument — either handed to it directly, or with a triple underscore pattern as the final component. Then it figures out the newest file chillin' inside that directory and writes that path straight to standard output. Iconic behaviour, honestly.

unless you pass that triple underscore pattern as the last component of the path, you're typically gonna need to at least specify the --suffix= switch to configure the file suffix you're looking for. fr fr, don't skip this.

And here's the plot twist 🫶 — if the path you specified does not reference a .v/ path (meaning: neither the final component ends in .v, nor does the penultimate one, nor does the final one contain a triple underscore), then your specified path just gets written unmodified to standard output. It's giving "no notes, moving on."

---

💅 OPTIONS 💅

The following options are understood, babes:

• --basename=, -B — Overrides the "basename" of the files to look for, aka the part sitting to the left of the variable part of the filenames. Normally this gets derived automatically from the filename of the .v component of the specified path, or from the triple underscore pattern in the last component of the specified path. Added in version 256.
• -V — Explicitly configures the version to select. If you specify it, a filename with the version string you gave will be looked for, instead of just grabbing the newest version available. Added in version 256.
• -A — Explicitly configures the architecture to select. If specified, a filename with the architecture identifier you gave will be looked for. If you don't specify it, only filenames with a locally supported architecture are considered — or those with no architecture identifier at all. Added in version 256.
• --suffix=, -S — Configures the suffix of the filenames to consider. For the .v/ logic you gotta specify the suffix to look for, and the .v/ component must also carry that suffix immediately before .v in its name. Added in version 256.
• --type=, -t — Configures the inode type to look for in the .v/ directory. Takes one of "reg", "dir", "sock", "fifo", "blk", "chr", "lnk" as its argument, each one identifying an inode type. Peep inode(7) for the deets on inode types. If you use this option, inodes that don't match the type you specified get filtered out and are not taken into consideration. Added in version 256.
• --print=, -p — Configures what precisely gets written to standard output. If you don't specify it, it prints the full, resolved path of the newest matching file in the .v/ directory. This switch can be set to one of the following:
  • If set to "filename", it will print only the filename instead of the full path of the resolved file.
  • If set to "version", it will print only the version of the resolved file.
  • If set to "type", it will print only the inode type of the resolved file (i.e. a string such as "reg" for regular files, or "dir" for directories).
  • If set to "arch", it will print only the architecture of the resolved file.
  • If set to "tries", it will print only the tries left/tries done of the resolved file.
  • If set to "all", it will print all of the above in a simple tabular output.
  • Added in version 256.
• --resolve= — Takes a boolean argument. If true, the path to the versioned file is fully canonicalized (symlinks resolved, redundant path components removed, the whole glow-up ✨) before it's shown. If false — which is the default — that does not happen, and the path is shown without canonicalization. Added in version 256.
• -h, --help — Print a short help text and exit. Short and sweet, we love that.
• --version — Print a short version string and exit.

---

🌈 EXAMPLES 🌈

Wanna automatically pick the newest raw disk image out of a .v/ directory? Run something like this:

$ systemd-vpick --suffix=.raw --type=reg /var/lib/machines/quux.raw.v/

What this does: enumerates all regular files matching /var/lib/machines/quux.raw.v/quux*.raw, filters and sorts them according to the rules described over in systemd.v(7), and then writes the path to the newest (by version) file to standard output. Slay.

Wanna automatically pick the newest OS directory tree out of a .v/ directory? Try something like this instead:

$ systemd-vpick --type=dir /var/lib/machines/waldo.v/

What this does: enumerates all directory inodes matching /var/lib/machines/waldo.v/waldo*, filters and sorts them according to the rules described in systemd.v(7), and then writes the path to the newest (by version) directory to standard output. Chef's kiss 😭

For even further examples, go peek at systemd.v(7) — she's got lore.

---

⭐ EXIT STATUS ⭐

On success, 0 is returned. A non-zero failure code otherwise. That's it, that's the whole story.

---

🫶 SEE ALSO 🫶

systemd(1), systemd.v(7)

---

and that's the whole page bestie, you ate it up 💖 this was systemd 262.1, and yeah, this is SYSTEMD-VPICK(1) signing off — go resolve some versioned directories, you main character 🎀✨🦋