SUBST(1)

💖 SUBST(1) — the substitute-definitions-into-files girlie 💖

okay bestie, gather round, because this one is a manual page for subst, and she is genuinely so useful once you get her vibe. no cap.

---

✨ NAME ✨

subst — substitute definitions into file(s). that's it, that's the whole job. she takes your definitions and she puts them in your files. slay.

---

🎀 SYNOPSIS 🎀

subst [ -e editor ] -f substitutions victim ...

yes the -f is mandatory, yes the victims are plural, yes she eats multiple files for breakfast. 💅

---

🌸 DESCRIPTION 🌸

so subst makes substitutions into files, in a way that is suitable for customizing software to local conditions. like, you wrote your program for your machine, and now it needs to run on someone else's machine, and instead of hand-editing every single value like a Victorian orphan, you let subst do it. every victim file gets altered according to the contents of the substitutions file. 🦋

the substitutions file contains one line per substitution. a line consists of two fields separated by one or more tabs. field one = the name of the substitution. field two = the value. neither should contain the character #, and honestly, using text-editor metacharacters like & and \' is also unwise — the name in particular is best restricted to be alphanumeric. like, keep it cute and simple, okay? 😌 a line starting with # is a comment and is ignored. periodt.

now here's the part where you have to pay attention, bestie, because this is the whole mechanic:

in the victims, each line on which a substitution is to be made (a target line) must be preceded by a prototype line. the prototype line should be delimited in such a way that it will be taken as a comment by whatever program processes the file later — so like, whatever language you're in, make it look like a comment to that language. sneaky? no, iconic. 👑

the prototype line must contain a ``prototype'' of the target line bracketed by =()< and >()=. everything else on the prototype line is ignored. then subst:

1. extracts the prototype,
2. changes all instances of substitution names bracketed by @< and >@ to their values,
3. and then replaces the target line with the result. 🪄

it's giving "template engine but make it 1990".

---

✨ OPTIONS ✨

• -e — substitutions are done using the sed(1) editor, which must be found in either the /bin or /usr/bin directories. to specify a different executable, use the ``-e'' flag. (yes, the flag that picks the editor is also described by the flag. she contains multitudes. 💀)

---

🍓 EXAMPLE 🍓

if the substitutions file is

FIRST     111
SECOND    222

and the victim file is

x = 2;
/* =()<y = @<FIRST>@ + @<SECOND>@;>()= */
y = 88 + 99;
z = 5;

then ``subst -f substitutions victim'' changes victim to:

x = 2;
/* =()<y = @<FIRST>@ + @<SECOND>@;>()= */
y = 111 + 222;
z = 5;

see how the prototype line stayed exactly the same and only the target line got the glow-up? that's the whole trick. the prototype is the receipt, the target is the purchase. 🔥

---

🧚 FILES 🧚

• victimdir/substtmp.new — new version being built
• victimdir/substtmp.old — old version during renaming

she builds the new one, renames the old one, it's a whole backstage situation. 🎭

---

🌈 SEE ALSO 🌈

• sed(1)

---

💀 DIAGNOSTICS 💀

complains and halts if it is unable to create its temporary files or if they already exist. so if you've got stale substtmp files lying around, she will simply refuse. respectfully. 😭

---

👑 HISTORY 👑

written at U of Toronto by Henry Spencer.

Rich $alz added the ``-e'' flag July, 1991.

a legacy. a lineage. we love to see it. 💜

---

🙈 BUGS 🙈

when creating a file to be substed, it's easy to forget to insert a dummy target line after a prototype line; if you forget, subst ends up deleting whichever line did in fact follow the prototype line.

okay so this is the jump scare. ⚠️ a prototype with no target under it means the next actual line of your file gets yeeted into the void. so always, always, always put a dummy target line right after your prototype line. protect your lines, bestie. 🫶

---

this has been SUBST(1) from the General Commands Manual, dated 25 Feb 1990 — yeah she's vintage, she's older than your fave, and she still runs. mwah. 💅✨