`./assets` in the `exclude` field of `typst.toml` actually matches `**/assets`

[YDX-2147483647]

Description

packages/docs/manifest.md

Line 68 in 8785ec6

- `exclude`: An array of globs specifying files that should not be part of the

It looks like an array of globs is the only description for the format of the exclude field in typst.toml.
This ambiguity cause problems.

QuadnucYard/ourchat-typ#3 is an example.
This package has the following file structure.

• /typst.toml
• /assets/ (to be excluded)
• /src/
  • /src/assets/ (to be included)

The package specifies ./assets, but surprisingly, it matches both /assets/ and /src/assets/.

exclude = ["./assets"]

Analysis

The bundler trims the ./ prefix, and uses a library for .gitignore to parse the glob.
As a result, ./assets becomes assets, and matches recursively.

packages/bundler/src/main.rs

Line 336 in 8785ec6

let exclusion = exclusion.trim_start_matches("./");

(introduced in b41d483)

Workaround

Use /assets.
(not confirmed yet)

Confirmed with https://github.com/typst-community/dev-builds/releases/tag/packages-bundler-main.2025-12-10.8c2f3eb.

Links

Discord

[laurmaedje]

In Typst itself, assets and ./assets are also equivalent, though I can see how in the context of a manifest, the dot could carry extra meaning. Regardless of whether the current behavior is sensible, using /assets seems like the clearest option and not like a workaround to me.

[HackYardo]

I don't think it's a good idea to write something like "any dir", "assets", "the top level dir".
Perhaps there are no asset in a package. And what is top dir, root or /home/user/ ?
My suggestions are:

1. do not use relative path in exclude string array, it's not reasonable in manifest or gitignore;
2. make it clear that glob patterns will be applied recursively throughout the entire working tree;
3. attach a link to Pro Git 2nd - Ignoring Files.

[arepodesir]

Hello world! As it would turn out in a all but fair economy there is more free work to be found then paid work for those who then get paid from free work 😄 However out of love for this work of art gifted to humanity I thought I share my suggestion for this issue that I also had to deal with (AuDHD brain can't stand inconsistency :P)...

A design suggestion for typst manifest exclusion logic, inspired by Jekyll

As @HackYardo observed there's no logical reason a pathname should ever resolve to outside the project root, so this should be an impossible state: perhaps even a compiler error. Having used Jekyll for a decade before the Agents took over I was all of a sudden curious how they implemented their exclusion logic when trying to configure my own typst project. Here's what they say:

Exclude directories and/or files from the conversion. These exclusions are relative to the site's source directory and cannot be outside the source directory. - Jekyll

Moreover the underlying function for path-pattern resolution, implemented in Ruby, has some helpful remarks:

fnmatch( pattern, path, [flags] ) → (true or false)
  
  # Returns true if path matches against pattern. The pattern is not a regular expression; 
  # instead it follows rules similar to shell filename globbing. It may contain the following metacharacters:

*
Matches any file. Can be restricted by other values in the glob. Equivalent to /.*/x in regexp.

*
Matches all regular files

c*
Matches all files beginning with c

*c
Matches all files ending with c

*c*
Matches all files that have c in them (including at the beginning or end).

To match hidden files (that start with a .) set the File::FNM_DOTMATCH flag.

**
Matches directories recursively or files expansively.

?
Matches any one character. Equivalent to /.{1}/ in regexp.

[set]
Matches any one character in set. Behaves exactly like character sets in [Regexp](https://ruby-doc.org/3.3.5/Regexp.html), including set negation ([^a-z]).

\
Escapes the next metacharacter.

{a,b}
Matches pattern a and pattern b if File::FNM_EXTGLOB flag is enabled. Behaves like a [Regexp](https://ruby-doc.org/3.3.5/Regexp.html) union ((?:a|b)).

  # flags is a bitwise OR of the FNM_XXX constants. 
  # The same glob pattern and flags are used by [Dir::glob](https://ruby-doc.org/3.3.5/Dir.html#method-c-glob).

Some examples from the Ruby Documentation

File.fnmatch('cat',       'cat')        #=> true  # match entire string
File.fnmatch('cat',       'category')   #=> false # only match partial string

File.fnmatch('c{at,ub}s', 'cats')                    #=> false # { } isn't supported by default
File.fnmatch('c{at,ub}s', 'cats', File::FNM_EXTGLOB) #=> true  # { } is supported on FNM_EXTGLOB

File.fnmatch('c?t',     'cat')          #=> true  # '?' match only 1 character
File.fnmatch('c??t',    'cat')          #=> false # ditto
File.fnmatch('c*',      'cats')         #=> true  # '*' match 0 or more characters
File.fnmatch('c*t',     'c/a/b/t')      #=> true  # ditto
File.fnmatch('ca[a-z]', 'cat')          #=> true  # inclusive bracket expression
File.fnmatch('ca[^t]',  'cat')          #=> false # exclusive bracket expression ('^' or '!')

File.fnmatch('cat', 'CAT')                     #=> false # case sensitive
File.fnmatch('cat', 'CAT', File::FNM_CASEFOLD) #=> true  # case insensitive
File.fnmatch('cat', 'CAT', File::FNM_SYSCASE)  #=> true or false # depends on the system default

File.fnmatch('?',   '/', File::FNM_PATHNAME)  #=> false # wildcard doesn't match '/' on FNM_PATHNAME
File.fnmatch('*',   '/', File::FNM_PATHNAME)  #=> false # ditto
File.fnmatch('[/]', '/', File::FNM_PATHNAME)  #=> false # ditto

File.fnmatch('\?',   '?')                       #=> true  # escaped wildcard becomes ordinary
File.fnmatch('\a',   'a')                       #=> true  # escaped ordinary remains ordinary
File.fnmatch('\a',   '\a', File::FNM_NOESCAPE)  #=> true  # FNM_NOESCAPE makes '\' ordinary
File.fnmatch('[\?]', '?')                       #=> true  # can escape inside bracket expression

File.fnmatch('*',   '.profile')                      #=> false # wildcard doesn't match leading
File.fnmatch('*',   '.profile', File::FNM_DOTMATCH)  #=> true  # period by default.
File.fnmatch('.*',  '.profile')                      #=> true

...

And this is how they are determining equality between pathnames:

identical?(file_1, file_2) → true or false
Returns true if the named files are identical.

file_1 and file_2 can be an [IO](https://ruby-doc.org/3.3.5/IO.html) object.

open("a", "w") {}
p File.identical?("a", "a")      #=> true
p File.identical?("a", "./a")    #=> true
File.link("a", "b")
p File.identical?("a", "b")      #=> true
File.symlink("a", "c")
p File.identical?("a", "c")      #=> true
open("d", "w") {}
p File.identical?("a", "d")      #=> false

My solution

Update the documentation to reflect this psuedo-regex exclusion logic like Jekyll did, and normalize the exlcusion glob to match Jekyll conventions and allow differentiating patterns from explicit paths. I'll make a pull request if this makes sense to anyone but something like:

fn normalize_exclusion_glob(pattern: &str) -> String {
    if let Some(rest) = pattern.strip_prefix("./") {
        // "./path" -> "/path"
        format!("/{rest}")
    } else if !pattern.starts_with('/') {
        // "path" -> "path"
        //  leave patterns without ./ as-is to support extension globs.
        pattern.to_string()
    } else {
        // "/path" -> "/path" 
        pattern.to_string()
    }
}

and in main.rs:

  let pattern = normalize_exclusion_glob(exclusion);
  overrides.add(&format!("!{}", pattern))?;

thanks for reading! ✨