borg-placeholders(1)

🎀 NAME 🎀

okay bestie, gather round — this is borg-placeholders, the little manual page that spills ALL the tea on placeholders. It's borg-placeholders (section 1 of the borg backup tool manual), and honestly? It's giving "tiny page, huge power". Let's go 💅

---

✨ DESCRIPTION ✨

so, the thing is: placeholders are these lil curly-brace magic words you can drop into stuff, and borg will swap them out for real values when it runs. no cap.

Here's exactly where they work — and this is the full list, don't sleep on any of them:

• Repository URLs
• the archive name arguments (NAME, OLDNAME, NEWNAME, ARCHIVE1, ARCHIVE2)
• -a / --match-archives
• --comment
• and BORG_REMOTE_PATH values

All of those support every placeholder below. 🫶

🌸 The placeholders, in order, no skips 🌸

• {hostname} — the (short) hostname of the machine. lil name, main character energy.
• {fqdn} — the full name of the machine. government name vibes.
• {reverse-fqdn} — the full name of the machine in reverse domain name notation. yes, backwards, that's the point, iconic.
• {now} — the current local date and time, by default in ISO-8601 format. and listen, you can also supply your own format string over at https://docs.python.org/3.11/library/datetime.html#strftime-and-strptime-behavior, e.g. {now:%Y-%m-%d_%H:%M:%S} 💖
• {utcnow} — the current UTC date and time, by default in ISO-8601 format. same deal: you can also supply your own format string at https://docs.python.org/3.11/library/datetime.html#strftime-and-strptime-behavior, e.g. {utcnow:%Y-%m-%d_%H:%M:%S} 🌈
• {unixtime} — the current time as a UNIX timestamp, i.e. whole seconds since the epoch, e.g.: 1735732800
• {user} — the user name (or UID, if no name is available) of the user running borg. her identity, revealed 💅
• {pid} — the current process ID.
• {uuid4} — a random UUID (version 4), freshly generated each time placeholders are replaced. fresh out the box every single time, obsessed.
• {borgversion} — the version of borg, e.g.: 1.0.8rc1
• {borgmajor} — the version of borg, only the major version, e.g.: 1
• {borgminor} — the version of borg, only major and minor version, e.g.: 1.0
• {borgpatch} — the version of borg, only major, minor and patch version, e.g.: 1.0.8

---

🦋 Escaping, bestie 🦋

what if you need literal curly braces in your text and you don't want borg touching them? easy. double them. that's the escape move, fr fr:

borg create --repo /path/to/repo {{literal_text}}

---

⭐ Examples, because we love a visual ⭐

borg create --repo /path/to/repo {hostname}-{user}-{utcnow} ...
borg create --repo /path/to/repo {hostname}-{now:%Y-%m-%d_%H:%M:%S%z} ...
borg prune -a 'sh:{hostname}-*' ...

---

👑 Note 👑

okay this is the important part, pay attention 🚨 systemd uses a difficult, non-standard syntax for command lines in unit files (refer to the systemd.unit(5) manual page). When invoking borg from unit files, pay particular attention to escaping, especially when using the now/utcnow placeholders, since systemd performs its own %-based variable replacement even in quoted text. To avoid interference from systemd, double all percent signs ({hostname}-{now:%Y-%m-%d_%H:%M:%S} becomes {hostname}-{now:%%Y-%%m-%%d_%%H:%%M:%%S}).

like, systemd will honestly just do its own thing with % and not even tell you. double those percent signs or perish (emotionally). 💀

---

💜 AUTHOR 💜

The Borg Collective. yes queen, they wrote the whole thing, we thank them for their service 🫶

---

aaaaand that's the page!! mwah 💋 this was borg-placeholders, page 1 of the borg backup tool manual, dated 2026-10-07, straight from The Borg Collective. stay escaped, double your braces, and go make some archives, bestie 🌸✨