Crash on --include/--include-path (Windows)

[iki]

Steps to reproduce:

# Macros - not needed, crashes with import and --include/--include-path independently on file existence
$ echo '{% macro format_num(val) -%}{{ val }}{%- endmacro -%}' > macros.html 

$ echo 'test: 1' > context.yaml

$ echo '{% import "macros.html" as macros %}' > test.md
$ echo '{{ macros::format_num(val=test) }}' >> test.md # Not needed, crashes with import only

# Crash with --include
$ tera --template test.md --include context.yaml
The application panicked (crashed).
Message:  called `Result::unwrap()` on an `Err` value: StripPrefixError(())
Location: C:\Users\runneradmin\.cargo\registry\src\index.crates.io-6f17d22bba15001f\tera-1.20.0\src\tera.rs:209

# Crash with --include-path
$ tera --template test.md --include-path . context.yaml
The application panicked (crashed).
Message:  called `Result::unwrap()` on an `Err` value: StripPrefixError(())
Location: C:\Users\runneradmin\.cargo\registry\src\index.crates.io-6f17d22bba15001f\tera-1.20.0\src\tera.rs:209

# Error without --include/--include-path
$ tera --template test.md context.yaml
Error:
   0: failed to render
   1: Template `__tera_one_off` loads macros from `Vzory/macros.html` which isn't present in Tera

Location:
   src\main.rs:81

[iki]

Also happens if I use --include-path .macros where .macros/ contains only macros.html

[iki]

Gemini analysis

This crash is caused by a known interplay between Windows file paths, how tera-cli constructs glob patterns, and how the tera engine calculates base directories.

Here is the step-by-step technical breakdown of exactly what happens in the source code.

1. The Point of Failure (tera.rs:209)

The panic occurs inside the tera engine (version 1.20.0) during template initialization:

// tera-1.20.0/src/tera.rs (simplified)
let name = path.strip_prefix(&base_dir).unwrap().to_string_lossy().replace('\\', "/");

Tera uses the glob crate to find files. For every file it finds (path), it attempts to strip the base directory (base_dir) to determine the relative template name (e.g., stripping C:\project\ from C:\project\macros.html to get macros.html).

If base_dir is not a valid prefix of path, strip_prefix returns an Err(StripPrefixError). Because Tera unconditionally calls .unwrap(), the application panics.

2. Why strip_prefix fails with --include

When you run tera --template test.md --include context.yaml, tera-cli attempts to automatically include the directory containing the template file.

• It checks the parent of test.md. Because there is no directory in the path, Path::parent() returns an empty string "".
• tera-cli constructs a glob pattern by appending //* to the parent. The resulting glob is exactly //*.
• Tera receives //* and calculates the base_dir by splitting the string by / until it hits a wildcard. For //*, the extracted base_dir is / (the root directory).
• The glob crate searches //* and returns absolute Windows paths starting from the current drive root (e.g., C:\Users\runneradmin\...).
• Tera attempts: Path::new("C:\\Users\\...").strip_prefix("/").
• The Crash: In Rust, / parses as a RootDir component, while C:\ parses as a Prefix(C:) followed by RootDir. The components do not match, strip_prefix fails, and .unwrap() panics.

3. Why strip_prefix fails with --include-path

When you use --include-path . or --include-path .macros, a different path-mangling issue occurs involving Windows UNC paths.

• tera-cli likely uses std::fs::canonicalize to resolve the provided path to an absolute path. On Windows, canonicalize returns a UNC path: \\?\C:\Users\runneradmin\project\.macros.
• To ensure compatibility with glob engines, CLIs often replace backslashes with forward slashes before appending the glob wildcard. The path becomes: //?/C:/Users/runneradmin/project/.macros//*.
• Tera receives this string and extracts the base_dir as //?/C:/Users/runneradmin/project/.macros/.
• The glob crate queries the file system and returns the actual Windows paths, which retain the strict UNC prefix: \\?\C:\Users\runneradmin\project\.macros\macros.html.
• The Crash: Rust's Path parser strictly requires backslashes (\\?\) for UNC prefixes. Because base_dir uses forward slashes (//?/C:/), Rust parses it as a standard relative path starting with RootDir and normal components ?, C:, etc. It compares this against the actual file path which has a legitimate Prefix(UNC) component. The component arrays are completely different, causing strip_prefix to return Err.

Summary

The root cause is a leaky abstraction where tera-cli feeds Windows-specific paths (empty relative roots or canonicalized UNC paths) into tera, which performs naive /-based string splitting to guess the base directory. When Rust's strict Path::components() comparison runs, the mangled string representations fail to match the actual OS paths returned by the globber.