bpkg-defau...ions-files(1)

💅 bpkg-default-options-files — specifying default options ✨

okay bestie, welcome to the bpkg-default-options-files(1) page from the General Commands Manual 🎀 this one's all about how your default options files get found and loaded, and ngl it's lowkey iconic once you get the vibe.

---

🌸 SYNOPSIS 🌸

bpkg command [mode-options] ...

---

✨ DESCRIPTION ✨

So instead of inventing a whole separate config file format for tool configuration, the build2 toolchain said "no, we're doing it differently" and uses default options files — which contain literally the same options you can pass on the command line. They're like the options files you can specify with --options-file (bpkg-common-options(1)), except for one main character difference: these ones get loaded by default. fr fr. 💖

Here's where they look for them, in order:

• the .build2/ and .build2/local/ subdirectories of each outer directory, starting from the start directory and going until it reaches either the home directory or the filesystem root directory — and it does not include those two, so, both excluded 🫶
• then the .build2/ subdirectory of the home directory 🏠
• and finally the system directory (for example, /etc/build2/) if it's configured ✨

Once the search is done, the files get loaded in reverse order — meaning it starts from the system directory (if there is one), then the home directory, ending with the start directory, and finishing off with the options you gave on the command line. In other words: the files load from the more generic to the more specific, and the command line options get to override any values that showed up in the default options files. command line stays winning, periodt 👑

The start directory, the names of the default options files, and the order they load within each directory are all determined by the command and potentially its mode-options. So go check each command's own DEFAULT OPTIONS FILES section for the tea, iykyk 🦋

Now the spicy bits:

• If a default options file contains --no-default-options, the search stops at the directory containing this file and no outer files get loaded. 🛑
• If this option is specified on the command line, then none of the default options files are searched for or loaded. 💀

You can also point at an extra directory of default options files with --default-options. And here's the cute part about how it slots in:

• If that directory is a subdirectory of the start directory, or sits between the start directory and the end of the outer search, then its configuration files load at the corresponding point in the directory hierarchy. 🎯
• Otherwise, they load after the home directory. 🏡

---

🚨 the remote files thing (important, bestie) 🚨

The presence of the .git filesystem entry causes the default options files in this directory and any of its subdirectories to be considered remote. Depending on the command, some security-sensitive options may be disallowed or may trigger a prompt when specified in remote options files. And yes, in the current implementation this is the case even for files from the .build2/local/ subdirectory — because the mere location isn't enough to definitively conclude the file isn't remote. To be sure you'd need to query the version control system. so yeah, don't @ me 😭

💡 Note that additional default options files specified with --default-options are never considered remote.

Also! The order in which default options files are loaded is traced at verbosity level 3 (the -V option) or higher. so if you wanna watch it happen live, crank that up 📈✨

---

🐛 BUGS 🐛

Send bug reports to the users@build2.org mailing list. we appreciate you, fr fr 🙏

---

©️ COPYRIGHT ©️

Copyright (c) 2014-2024 the build2 authors.

Permission is granted to copy, distribute and/or modify this document under the terms of the MIT License. 💖

---

and that's the whole page, bestie!! 🦋 this was bpkg 0.17.0 from June 2024 — stay slay, go read your DEFAULT OPTIONS FILES sections, and remember: generic to specific, command line always overrides 💅✨🌈