podman-container-tools/podman · error · Exception

Please invoke me from the base repo dir

Error message

Please invoke me from the base repo dir

What it means

Raised by main() when os.chdir(script_dir/../docs/source/markdown) raises FileNotFoundError — the man-page directory next to the script's own location does not exist. Despite the message wording, the check is based on the script's __file__ location, not on the caller's current working directory: the script needs a complete checkout where hack/ and docs/source/markdown/ are siblings. Running a copied/relocated script or a partial archive triggers it.

Source

Thrown at hack/markdown-preprocess:280

            # 'pod' not in lhs, must be in rhs
            if not re.match('.*pod([^m]|$)', rhs, re.IGNORECASE):
                raise Exception(f"'{matchobj[0]}' does not match 'pod' in either side")
            if self.pod_or_container == 'pod':
                return rhs
            return lhs

        return re.sub(r'<<[^\|>]*\|[^\|>]*>>', replwith, line)


def main():
    "script entry point"
    script_dir = os.path.abspath(os.path.dirname(__file__))
    man_dir = os.path.join(script_dir,"../docs/source/markdown")

    try:
        os.chdir(man_dir)
    except FileNotFoundError as ex:
        raise Exception("Please invoke me from the base repo dir") from ex

    # No longer possible to invoke us with args: reject any such invocation
    if len(sys.argv) > 1:
        raise Exception("This script accepts no arguments")

    preprocessor = Preprocessor()
    for infile in sorted(glob.glob('*.md.in')):
        preprocessor.process(infile)

    # Now rewrite all option files
    preprocessor.rewrite_optionfiles()

if __name__ == "__main__":
    main()

View on GitHub (pinned to a2409076ef)

Solutions

1. Run from a full clone of the containers/podman repo, where hack/markdown-preprocess sits next to docs/source/markdown
2. Restore the missing directory: git checkout HEAD -- docs/source/markdown or disable sparse-checkout for it
3. Confirm layout: test -d "$(dirname $(realpath hack/markdown-preprocess))/../docs/source/markdown"

Example fix

# before
cp hack/markdown-preprocess /tmp/ && cd /tmp && ./markdown-preprocess

# after
git clone https://github.com/containers/podman && cd podman && ./hack/markdown-preprocess

#!/bin/sh
# Verify repo layout relative to the script before invoking it
script=$(realpath "$1" 2>/dev/null || echo hack/markdown-preprocess)
mandir=$(dirname "$script")/../docs/source/markdown
[ -d "$mandir" ] || { echo "missing $mandir — use a full podman checkout" >&2; exit 1; }
exec "$script"

When it happens

Trigger: Invoking hack/markdown-preprocess from a tarball or sparse checkout that omitted docs/source/markdown; moving or symlinking the script out of the repo; running it after docs/ was renamed; filesystem case-sensitivity mismatches on case-insensitive mounts.

Common situations: Packagers or CI jobs trying to run the script standalone from an installed location; contributors with partial clones (e.g. sparse-checkout without docs); accidental execution from a vendored copy of hack/ inside another tree.

Related errors

• Error while processing {infile} line '{line[:-1]}'
• undefined variable: {name}
• `else` without `if`
• multiple `else` in the same `if`
• `end` without `if`

AI-assisted analysis of podman-container-tools/podman@a2409076ef (2026-08-15). Data as JSON: /api/errors/d5bd4229cfd6ccf0. Report an issue: GitHub.