GUARDS(1)

💖 guards — bestie's guide to picking files by vibe check 💖

okay so this is GUARDS(1), from the User Contributed Perl Documentation collection, and honestly? it's giving ✨file-selection-gatekeeper✨ and I'm obsessed. sit down, grab a strawberry 🍓, we're doing this.

---

🎀 NAME 🎀

guards — the icon, the moment: it selects from a list of files that are guarded by conditions. periodt 💅

---

🌸 SYNOPSIS 🌸

guards [--prefix=dir] [--path=dir1:dir2:...] [--default=<0|1>]
[--check|--list] [--invert-match] [--with-guards] [--config=<file>]
symbol ...

like… look at her. gorgeous. all those little options and then just a pile of symbols at the end. no cap 🫶

---

✨ DESCRIPTION ✨

so basically, bestie: the script reads a configuration file. that file can contain so-called guards, file names, and comments — a whole little mixed-content situation 🙈 — and then it writes out to standard output all the file names that satisfy every single guard. all of them. no exceptions. she's ✨selective✨.

the script takes a list of symbols as its arguments, and every line in the configuration file gets processed separately, one at a time. lowkey methodical.

lines may start with a number of guards. here are the guards that are defined, and I need you to actually read these, fr fr:

• +xxx — include the file(s) on this line if the symbol xxx is defined ✨
• -xxx — exclude the file(s) on this line if the symbol xxx is defined 💀
• +!xxx — include the file(s) on this line if the symbol xxx is not defined 🙈
• -!xxx — exclude the file(s) on this line if the symbol xxx is not defined
• - — exclude this file. it's literally just the bare minus. it's used to avoid spurious --check messages. she's here to keep the peace 🕊️

the guards are processed left to right, and the last guard that matches is the one that determines if the file is included. so like, the newest opinion wins, it's very main character energy 👑.

if no guard is specified at all, then the --default setting is what decides whether the file gets included. she's flexible like that 🦋

and if no configuration file is specified, the script just reads from standard input. chill. easy. no big deal.

---

🧚 the --check situation 🧚

the --check option compares the specification file against the file system — yes, they're being compared, it's a whole vibe check 👀. if:

• files are referenced in the specification that do not exist, or
• files are not enlisted in the specification file,

…then warnings get printed. that's it. that's the drama. 😭

🔥 paths and prefixes and files, oh my 🔥

• the --path option lets you specify which directory (or directories!! plural!!) to scan 🌈
• multiple directories are separated by a colon — that's the ":" character, exactly one of them, don't get creative bestie
• the --prefix option specifies the location of the files 📁
• alternatively, you can use the --path=@<file> syntax to specify a file from which the file names will be read. yes, that's an at-sign, yes it's iconic, no I will not be taking questions ✨

💅 and the other three, because she contains multitudes 💅

• use --list to list all files independent of any rules. no rules, no conditions, just vibes. she's free 🌈
• use --invert-match to list only the excluded patches. flipping the script, literally 🦋
• use --with-guards to also include all inclusion and exclusion rules. she's showing her work, we love a transparent queen 👑

---

👑 AUTHOR 👑

Andreas Gruenbacher <agruen@suse.de>, SUSE Labs — absolute legend, thank you for your service 🫡💖

---

okay that's the whole page, bestie, you ate that 🎀

this was perl v5.40.1 and the page is dated 2026-01-23 — mwah, iconic, no notes 💜✨