bake and bakefile load exactly one bakefile.py per run. They never merge several files, and a command missing from the chosen file is an error, not a lookup in another file.
Resolution order
- With
-g, the Globalbakefile.py. - With
-C <dir>, only<dir>. No walk-up and no fallback, so a typo in the path fails instead of loading another file. - Otherwise, the nearest
bakefile.pyfound by walking up from the current directory to the filesystem root. - If walk-up finds nothing, the Global
bakefile.py, if you have created one.
-f changes only the file name, and every step looks for that name. bake -f tools.py build walks up looking for tools.py, then falls back to the global tools.py. -f still takes a name, never a path (see file name errors).
bakefile.py wins: from monorepo/services/api/, a services/api/bakefile.py is used over monorepo/bakefile.py. Walk-up crosses repository boundaries, so a git submodule without its own bakefile.py uses the outer repo’s.
bake --help shows which file was loaded, marked (global) when it is the Global bakefile.py:
bakefile subcommands other than init print the same Using: <path> line to stderr before running, since walk-up may have picked a parent’s file. -vvv logs which step matched.
When nothing is found, the error lists what was searched and where a Global bakefile.py would go:
Commands run in the bakefile.py’s directory
Commands always run in the chosenbakefile.py’s directory, wherever you call bake from. Relative paths in your commands (self.ctx.run("pytest tests"), Path("dist")) behave the same from a subfolder as from the root. For the Global bakefile.py, that is the global directory, resolved through symlinks.
Global bakefile.py
A Globalbakefile.py holds commands that belong to no project, such as syncing dotfiles or personal utilities. It is opt-in: nothing exists until you create it, and without one, plain bake behaves as before (only the not-found message is new).
Location
A relative
XDG_CONFIG_HOME is ignored, as the XDG spec requires. The same rule applies on every platform, including macOS (not ~/Library).
Create it
bakefile init without -g always creates in the current directory (or -C), never in a parent or the global directory.
Keep it in a dotfiles repo
Symlink the repo to the global directory (instead ofbakefile -g init; if ~/.config/bake already exists, ln -s would create the link inside it). Commands run in the real repo directory, so its relative paths and bakefile.py.lock work:
Run global commands
Outside any project, plainbake <command> falls back to the Global bakefile.py. Inside a project with its own bakefile.py, use -g:
-g -f picks another file in the global directory, so one repo can hold several global Bakebooks:
-g together with -C is a usage error. bake -g and bakefile -g subcommands with no Global bakefile.py name the expected path and suggest bakefile -g init.
Manage it
Everybakefile subcommand takes -g. For a Global bakefile.py with PEP 723 inline metadata:
Acting on the Invocation directory
Since commands run in thebakefile.py’s directory, a command that should act where you called bake from reads self.ctx.invocation_dir. It stays correct when bake re-runs itself under the bakefile.py’s Python. For example, a global command that cleans Python caches under the current directory:
Upgrading
Earlier versions only looked in the current directory (or-C). Now, running bake from a subfolder without its own bakefile.py runs the parent’s commands instead of failing. Use -C <dir> when you want exactly one directory.