Add wildcard matching to substitute-path rules

  Hi everyone!

I have developed a patch that allows for glob pattern matching within substitute-path rules.

Why is this useful?
Some build systems and/or package managers may copy the sources of a program before build. The path of this copy may not always be the same. In the case of conan (https://conan.io/) the path will consist of some constant part and some directory named with some hash value (i.e., /path/to/<unique hash>/builddir/). This hash will differ with each build, and therefore any source redirection within GDB must be reconfigured. This is, of course, really annoying when debugging a library. You might write a custom startup script for GDB to set the correct path automatically. But I thought it would be much more elegant if GDB would just support glob patterns (so that the rule /path/to/*/builddir/ would match any relevant build directory).

How does the patch work?
I wrote a custom glob matching function gdb_fileprefix_fnmatch() that is called from substitute_path_rule_matches() (maybe this function should be renamed because its meaning is slightly different now). It is located in utils.c. If you think this function should be defined at another location, let me know.
I considered just using fnmatch(), but I found that this is not viable for the problem at hand. fnmatch() matches a complete string, but I need to find the longest leading substring (and its length) that matches a given pattern. So calling fnmatch() multiple times would have quadratic complexity.
I also didn't want to add any additional dependencies.
Instead, I was inspired by git's implementation (https://github.com/git/git/blob/master/wildmatch.c) as well as fnmatch() from libiberty. It is recursive, but given that usually only a few (often just one) wildcards are used, this should not be an issue.

What must be considered?
This patch will break some (rather obscure) substitute-path rules. Any rule containing the characters '\', '?' and '*' must be rewritten to escape the aforementioned characters. This could get messy because backslashes must already be escaped in the GDB command line. Maybe another command (substitute-path-glob) should be introduced instead. Personally, I am ok with breaking stuff because it's only a small change to perform for the user, but that's not really my decision to make.
I have not implemented character sets yet. I don't really see use cases for them in this setting. But if you want me to add them for completeness, I would be willing to do so.
I also actively decided against implementing the '**' wildcard (match any string, also match directory separators), as this could lead to ambiguous matches.

Testing
I have created the 'gdb.base/subst-glob.exp' testsuite to test out the new feature. I also tested against 'gdb.base/subst.exp'. The tests were performed on GNU/Linux and Windows (MinGW). I did not find any regressions in the testsuite (on Linux).

Copyright
I have not yet signed any papers regarding FSF copyright assignment.

Please let me know what you think of this patch!
Thank you in advance,
Max

---
 gdb/NEWS                              |   5 +
 gdb/doc/gdb.texinfo                   |  29 +++++
 gdb/source.c                          |  77 ++++++++----
 gdb/testsuite/gdb.base/subst-glob.exp | 166 ++++++++++++++++++++++++++
 gdb/utils.c                           | 100 ++++++++++++++++
 gdb/utils.h                           |   2 +
 6 files changed, 356 insertions(+), 23 deletions(-)
 create mode 100644 gdb/testsuite/gdb.base/subst-glob.exp
  

> Date: Mon, 1 Apr 2024 23:26:36 +0200
> From: Max Yvon Zimmermann <max.yvon.zimmermann@campus.tu-berlin.de>
> 
> I have developed a patch that allows for glob pattern matching within substitute-path rules.

Thanks.

> diff --git a/gdb/NEWS b/gdb/NEWS
> index feb3a37393a..5a041175507 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -90,6 +90,11 @@ show unwind-on-signal
>    These new commands replaces the existing set/show unwindonsignal.  The
>    old command is maintained as an alias.
>  
> +set substitute-path
> +  This command now supports glob pattern matching for substitution
> +  rules.  Wildcards '?' and '*' are supported.  Use '\' to escape
> +  '?', '*' and '\' characters.

This part is approved, documentation-wise.

But I wonder what does the above mean for Windows file names that use
backslashes as directory separators?  Does each backslash need to be
escaped by another one, when creating the rewrite rules??

> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -9954,6 +9954,35 @@ For instance, if we had entered the following commands:
>  use the second rule to rewrite @file{/usr/src/lib/foo.c} into
>  @file{/mnt/src/lib/foo.c}.
>  
> +Rules can contain wildcards to match multiple paths.  The supported
> +wildcards are @samp{?} (to match any single character) and @samp{*}
> +(to match any string).  Wildcards will never match the path separator of
> +the system.

File names of their parts should have the @file markup, not @samp.
(Wildcards are file names of sorts.)

> +For instance, if we had entered the following command:
> +
> +@smallexample
> +(@value{GDBP}) set substitute-path /usr/*/include /mnt/include
> +@end smallexample

Does this mean that multiple /usr/*/include directories could be
redirected to the same /mnt/include directory?  Won't that cause
trouble, if there are several distinct directories recorded in the
debug info whose names match the wildcard, and which are supposed to
resolve to different directories?

> +Use @samp{@backslashchar{}} to escape the characters @samp{?}@comma{}
> +@samp{*} and @samp{@backslashchar{}}.  Note that you need to escape any
> +@samp{@backslashchar{}} characters twice in the @value{GDBN} command line.

I'd prefer not to use @comma{} and @backslashchar{} except where the
literal characters will confuse TeX.  AFAIU, they are not needed here,
and literal characters will do the job.

> +  if (IS_DIR_SEPARATOR (path[last]))
> +    {
> +      path[last] = '\0';
> +
> +      if (path[last] != '\\')
> +        return;

Something's wrong here: you assign path[last] and then test its value?

Also, how does this handle Windows-style file names with backslashes?

> +#ifdef HAVE_DOS_BASED_FILE_SYSTEM
> +          /* On DOS-based file systems, the '/' and the '\' are equivalent.  */
> +          if (pattern_c == '/')
> +            pattern_c = '\\';
> +          if (string_c == '/')
> +            string_c = '\\';
> +#endif

Does this mean "//" (two slashes in a row) will be converted to "\\",
and will then be interpreted as an escaped single backslash?

Reviewed-By: Eli Zaretskii <eliz@gnu.org>
  

Thank you for the quick reply!

>> diff --git a/gdb/NEWS b/gdb/NEWS
>> index feb3a37393a..5a041175507 100644
>> --- a/gdb/NEWS
>> +++ b/gdb/NEWS
>> @@ -90,6 +90,11 @@ show unwind-on-signal
>>    These new commands replaces the existing set/show unwindonsignal.  The
>>    old command is maintained as an alias.
>>  
>> +set substitute-path
>> +  This command now supports glob pattern matching for substitution
>> +  rules.  Wildcards '?' and '*' are supported.  Use '\' to escape
>> +  '?', '*' and '\' characters.
> 
> This part is approved, documentation-wise.
> 
> But I wonder what does the above mean for Windows file names that use
> backslashes as directory separators?  Does each backslash need to be
> escaped by another one, when creating the rewrite rules??

On DOS-based systems both backslashes and forward slashes are valid path separators. So while Windows users COULD write their paths as \\path\\to\\, /path/to/ would work as well. This behavior is not new, the previous version behaved similarly. New is that to match a backslash from the GDB command line you would have to escape a backslash twice (because the CLI already unescapes backslashes). But because everyone can just continue to use forwards slashes, I think this should be fine.

>> --- a/gdb/doc/gdb.texinfo
>> +++ b/gdb/doc/gdb.texinfo
>> @@ -9954,6 +9954,35 @@ For instance, if we had entered the following commands:
>>  use the second rule to rewrite @file{/usr/src/lib/foo.c} into
>>  @file{/mnt/src/lib/foo.c}.
>>  
>> +Rules can contain wildcards to match multiple paths.  The supported
>> +wildcards are @samp{?} (to match any single character) and @samp{*}
>> +(to match any string).  Wildcards will never match the path separator of
>> +the system.
> 
> File names of their parts should have the @file markup, not @samp.
> (Wildcards are file names of sorts.)

Ok, I will change that.

>> +For instance, if we had entered the following command:
>> +
>> +@smallexample
>> +(@value{GDBP}) set substitute-path /usr/*/include /mnt/include
>> +@end smallexample
> 
> Does this mean that multiple /usr/*/include directories could be
> redirected to the same /mnt/include directory?  Won't that cause
> trouble, if there are several distinct directories recorded in the
> debug info whose names match the wildcard, and which are supposed to
> resolve to different directories?

I realize now that /usr/*/include is actually a terrible example for this feature. I will change the example to avoid confusion. However it is correct that two files from distinct directories COULD accidentally get matched. But you could argue that this is already the case. Let's say we set the following two rules:

set substitute-path /foo/include /mnt/include
set substitute-path /bar/include /mnt/include

Then we could run into exactly the same issue.

I would also like to point out that the rule selection is unaffected by this patch. To quote from the documentation: "In the case when more than one substitution rule have been defined, the rules are evaluated one by one in the order where they have been defined. The first one matching, if any, is selected to perform the substitution." I think this should prevent any accidental matches if the feature is used correctly.

>> +Use @samp{@backslashchar{}} to escape the characters @samp{?}@comma{}
>> +@samp{*} and @samp{@backslashchar{}}.  Note that you need to escape any
>> +@samp{@backslashchar{}} characters twice in the @value{GDBN} command line.
> 
> I'd prefer not to use @comma{} and @backslashchar{} except where the
> literal characters will confuse TeX.  AFAIU, they are not needed here,
> and literal characters will do the job.
> 
>> +  if (IS_DIR_SEPARATOR (path[last]))
>> +    {
>> +      path[last] = '\0';
>> +
>> +      if (path[last] != '\\')
>> +        return;
> 
> Something's wrong here: you assign path[last] and then test its value?
> 
> Also, how does this handle Windows-style file names with backslashes?

Yes, this is a bug. I actually wrote this function specifically for DOS-style file names. The idea is that any trailing backslash (that should be deleted) will be preceded by another (escape) backslash that must also be deleted. I will post a V2 soon where this function is getting a major overhaul and the relevant edge cases are included in the testsuite.

>> +#ifdef HAVE_DOS_BASED_FILE_SYSTEM
>> +          /* On DOS-based file systems, the '/' and the '\' are equivalent.  */
>> +          if (pattern_c == '/')
>> +            pattern_c = '\\';
>> +          if (string_c == '/')
>> +            string_c = '\\';
>> +#endif
> 
> Does this mean "//" (two slashes in a row) will be converted to "\\",
> and will then be interpreted as an escaped single backslash?

No, this is only done for the comparison directly below. The pattern is not altered in any way. "//" will not result in an escaped single backslash.
  

> Date: Thu, 4 Apr 2024 02:05:11 +0200
> CC: <gdb-patches@sourceware.org>
> From: Max Yvon Zimmermann <max.yvon.zimmermann@campus.tu-berlin.de>
> 
> Thank you for the quick reply!

Thank you for working on this feature in the first place.

> > But I wonder what does the above mean for Windows file names that use
> > backslashes as directory separators?  Does each backslash need to be
> > escaped by another one, when creating the rewrite rules??
> 
> On DOS-based systems both backslashes and forward slashes are valid path separators. So while Windows users COULD write their paths as \\path\\to\\, /path/to/ would work as well. This behavior is not new, the previous version behaved similarly. New is that to match a backslash from the GDB command line you would have to escape a backslash twice (because the CLI already unescapes backslashes). But because everyone can just continue to use forwards slashes, I think this should be fine.

So extra \-escaping will still be needed for DOS-based filesystems.  I
think this should be mentioned in the documentation.

> > Does this mean that multiple /usr/*/include directories could be
> > redirected to the same /mnt/include directory?  Won't that cause
> > trouble, if there are several distinct directories recorded in the
> > debug info whose names match the wildcard, and which are supposed to
> > resolve to different directories?
> 
> I realize now that /usr/*/include is actually a terrible example for this feature. I will change the example to avoid confusion. However it is correct that two files from distinct directories COULD accidentally get matched. But you could argue that this is already the case. Let's say we set the following two rules:
> 
> set substitute-path /foo/include /mnt/include
> set substitute-path /bar/include /mnt/include
> 
> Then we could run into exactly the same issue.

The difference here is that the two lines above must be explicitly
written by the user, whereas the wildcard rule could catch another
directory unintentionally.

> I would also like to point out that the rule selection is unaffected by this patch. To quote from the documentation: "In the case when more than one substitution rule have been defined, the rules are evaluated one by one in the order where they have been defined. The first one matching, if any, is selected to perform the substitution."

To me, this means that the two-line example you've shown is processed
in a predictable way, by only using the first one if both match,
whereas a wildcard rule will cause unpredictable results, because the
order in which files are compared against a wildcard is undefined.
Right?

Thanks.
  

Thank you.

>> On DOS-based systems both backslashes and forward slashes are valid path separators. So while Windows users COULD write their paths as \\path\\to\\, /path/to/ would work as well. This behavior is not new, the previous version behaved similarly. New is that to match a backslash from the GDB command line you would have to escape a backslash twice (because the CLI already unescapes backslashes). But because everyone can just continue to use forwards slashes, I think this should be fine.
> 
> So extra \-escaping will still be needed for DOS-based filesystems.  I
> think this should be mentioned in the documentation.

Actually, this is already mentioned in the documentation. But maybe it can be made a bit clearer. On the other hand, I really do not want to encourage the extra \-escaping. I am thinking of writing something like this instead:

"On DOS-based file system, you are encouraged to use '/' as the path separator within your patterns. This avoids escaping the '\' characters and would still match against file names that use '\' as the path separator. For instance, the pattern 'C:/foo/*' would still match 'C:\foo\bar'."

>> I realize now that /usr/*/include is actually a terrible example for this feature. I will change the example to avoid confusion. However it is correct that two files from distinct directories COULD accidentally get matched. But you could argue that this is already the case. Let's say we set the following two rules:
>>
>> set substitute-path /foo/include /mnt/include
>> set substitute-path /bar/include /mnt/include
>>
>> Then we could run into exactly the same issue.
> 
> The difference here is that the two lines above must be explicitly
> written by the user, whereas the wildcard rule could catch another
> directory unintentionally.
> 
>> I would also like to point out that the rule selection is unaffected by this patch. To quote from the documentation: "In the case when more than one substitution rule have been defined, the rules are evaluated one by one in the order where they have been defined. The first one matching, if any, is selected to perform the substitution."
> 
> To me, this means that the two-line example you've shown is processed
> in a predictable way, by only using the first one if both match,
> whereas a wildcard rule will cause unpredictable results, because the
> order in which files are compared against a wildcard is undefined.
> Right?

No, rules that use wildcards are still processed in a predictable way. If we set the following two rules (and in that order!):

set substitute-path /foo/include /path/to/foo
set substitute-path /*/include /path/to/somewhere

Then any file names matching '/foo/include' would be rewritten to '/path/to/foo' and NOT '/path/to/somewhere'. Even though any file name matching '/foo/include' would of course also match '/*/include'. The rule selection is entirely based on the order of their definition.

Also, in the example I stated in my last reply, no file name that matches '/foo/include' would ever match '/bar/include'. The point I was trying to get across was that two unrelated files can already be mapped onto the same file (accidentally).
  

> Date: Thu, 4 Apr 2024 10:52:31 +0200
> CC: <gdb-patches@sourceware.org>
> From: Max Yvon Zimmermann <max.yvon.zimmermann@campus.tu-berlin.de>
> 
> Actually, this is already mentioned in the documentation. But maybe it can be made a bit clearer. On the other hand, I really do not want to encourage the extra \-escaping. I am thinking of writing something like this instead:
> 
> "On DOS-based file system, you are encouraged to use '/' as the path separator within your patterns. This avoids escaping the '\' characters and would still match against file names that use '\' as the path separator. For instance, the pattern 'C:/foo/*' would still match 'C:\foo\bar'."

I'm not sure this should be in the manual, since the way file names
are written in the debug info is not under user's control.  If the
file names in the debug info use backslashes, will GDB recognize
rewrite rules that use forward slashes?  Even if GDB does treat both
characters as equal on Windows, I'm not sure users will trust that up
front, so they might use backslashes in the rewrite rules anyway.

> > To me, this means that the two-line example you've shown is processed
> > in a predictable way, by only using the first one if both match,
> > whereas a wildcard rule will cause unpredictable results, because the
> > order in which files are compared against a wildcard is undefined.
> > Right?
> 
> No, rules that use wildcards are still processed in a predictable way. If we set the following two rules (and in that order!):
> 
> set substitute-path /foo/include /path/to/foo
> set substitute-path /*/include /path/to/somewhere
> 
> Then any file names matching '/foo/include' would be rewritten to '/path/to/foo' and NOT '/path/to/somewhere'. Even though any file name matching '/foo/include' would of course also match '/*/include'. The rule selection is entirely based on the order of their definition.

That's not what I meant.  I meant that a rule like

  set substitute-path /*/include /path/to/somewhere

can catch any parent directory of 'include', and which one it will
catch is not known in advance.

> Also, in the example I stated in my last reply, no file name that matches '/foo/include' would ever match '/bar/include'. The point I was trying to get across was that two unrelated files can already be mapped onto the same file (accidentally).

Well, two wrongs don't make a right.

I'd be interested to hear opinions of others about this.
  

On 4/4/24 08:52, Eli Zaretskii wrote:
>>> To me, this means that the two-line example you've shown is processed
>>> in a predictable way, by only using the first one if both match,
>>> whereas a wildcard rule will cause unpredictable results, because the
>>> order in which files are compared against a wildcard is undefined.
>>> Right?
>> No, rules that use wildcards are still processed in a predictable way. If we set the following two rules (and in that order!):
>>
>> set substitute-path /foo/include /path/to/foo
>> set substitute-path /*/include /path/to/somewhere
>>
>> Then any file names matching '/foo/include' would be rewritten to '/path/to/foo' and NOT '/path/to/somewhere'. Even though any file name matching '/foo/include' would of course also match '/*/include'. The rule selection is entirely based on the order of their definition.
> That's not what I meant.  I meant that a rule like
>
>    set substitute-path /*/include /path/to/somewhere
>
> can catch any parent directory of 'include', and which one it will
> catch is not known in advance.

This was something I was also wondering about. taking from the original 
example:

Max> In the case of conan (https://conan.io/) the path will consist of 
some constant part and some directory named with some hash value (i.e., 
/path/to/<unique hash>/builddir/)

Suppose there are 2 builds for this package, so we have the following 
valid directories: /path/to/deadbeef/builddir /path/to/00000000/builddir

which of those will be chosen? Is it consistent across gdb runs? OSs? 
How can a user know in advance which will be picked?

>
>> Also, in the example I stated in my last reply, no file name that matches '/foo/include' would ever match '/bar/include'. The point I was trying to get across was that two unrelated files can already be mapped onto the same file (accidentally).

The difference I see is that in the previous examples, the problem is 
apparent within what the user would expect (some GDB script, debug 
information, or other things related to their project), whereas with 
glob matching, the problem may be unrelated (directory structure of 
unrelated folders).

If I wasn't aware of this patch, I would never think to check if the 
folder structure of my system could be the problem for getting debug 
information.

> Well, two wrongs don't make a right.
>
> I'd be interested to hear opinions of others about this.
  

Thank you once again for your feedback. You made me take a deep dive into how source redirection works in detail. It was quite fun!
I will try to answer the concerns from both of you in this reply.

>> Actually, this is already mentioned in the documentation. But maybe it can be made a bit clearer. On the other hand, I really do not want to encourage the extra \-escaping. I am thinking of writing something like this instead:
>>
>> "On DOS-based file system, you are encouraged to use '/' as the path separator within your patterns. This avoids escaping the '\' characters and would still match against file names that use '\' as the path separator. For instance, the pattern 'C:/foo/*' would still match 'C:\foo\bar'."
> 
> I'm not sure this should be in the manual, since the way file names
> are written in the debug info is not under user's control.  If the
> file names in the debug info use backslashes, will GDB recognize
> rewrite rules that use forward slashes?  Even if GDB does treat both
> characters as equal on Windows, I'm not sure users will trust that up
> front, so they might use backslashes in the rewrite rules anyway.

Yes, GDB will recognize rewrite rules that use forward slashes even if file names in the debug info use backslashes.
I can of course still add an example for double \-escaped DOS paths if you want me to.

>> That's not what I meant.  I meant that a rule like
>>
>>   set substitute-path /*/include /path/to/somewhere
>>
>> can catch any parent directory of 'include', and which one it will
>> catch is not known in advance.
> 
> This was something I was also wondering about. taking from the original example:
> 
> Max> In the case of conan (https://conan.io/) the path will consist of some constant part and some directory named with some hash value (i.e., /path/to/<unique hash>/builddir/)
> 
> Suppose there are 2 builds for this package, so we have the following valid directories: /path/to/deadbeef/builddir /path/to/00000000/builddir
> 
> which of those will be chosen? Is it consistent across gdb runs? OSs? How can a user know in advance which will be picked?

I think I need to clear up some confusion about the direction of this mapping. We map from the file names provided in the debug info to our local source files. NOT the other way around!

In my original example we would set the following rule:

set substitute-path /path/to/*/builddir /src

Let's say we are debugging an executable which contains the file name '/path/to/deadbeef/builddir/main.c' in its debug info.
When GDB wants to open the file it will look up any substitution rules that match this file name.
In this case the file would match against our specified rule and would therefore be rewritten as '/src/main.c'. This is unambiguous.
Now '/src/main.c' will be opened by GDB.
If we were to debug another executable which contains the file name '/path/to/00000000/builddir/main.c' in its debug info, the same thing would happen.

I want to emphasize that we are NOT looking for any paths that would "match" '/src/main.c'.
So your question about which path will be chosen does not really apply.
There is no path to be chosen.

But I think I know what you mean with your question.
In a nutshell, the "chosen" path depends on which build of the package is currently being debugged.

Is this consistent across GDB runs?
Yes.

Is this consistent across OSs?
Yes.

How can a user know in advance which will be picked?
There is nothing to be picked.

>>> Also, in the example I stated in my last reply, no file name that matches '/foo/include' would ever match '/bar/include'. The point I was trying to get across was that two unrelated files can already be mapped onto the same file (accidentally).
> 
> The difference I see is that in the previous examples, the problem is apparent within what the user would expect (some GDB script, debug information, or other things related to their project), whereas with glob matching, the problem may be unrelated (directory structure of unrelated folders).
> 
> If I wasn't aware of this patch, I would never think to check if the folder structure of my system could be the problem for getting debug information.

Once again, this is not really an issue due to the direction of the mapping.
The folder structure of a system does not affect which rule will be matched. I know this might sound like a bold statement but it's true.
Only the file names in the debug info are relevant.

>> Also, in the example I stated in my last reply, no file name that matches '/foo/include' would ever match '/bar/include'. The point I was trying to get across was that two unrelated files can already be mapped onto the same file (accidentally).
> 
> Well, two wrongs don't make a right.

This is a very fair point. Having different files map to the same file in the local source directory could be annoying.
Because this isn't a new issue per se, I thought about implementing a separate patch that would warn the user if two different files get mapped onto the same source file.
But after some thought I realized that there are actually valid use-cases for this multi-mapping.

Let's say we have the following directory structure:

/inc.h
/foo.c
/dir/bar.c

'/foo.c' includes '/inc.h' via #include "inc.h".
'/dir/bar.c' includes '/inc.h' via #include "../inc.h"

With GCC this will result in two entries in the debug info: '/inc.h' and '/dir/../inc.h'.
For GDB these entries are two separate files. (Maybe this could changed with another patch though)
But with the help of the following two rules we can tell GDB to treat them the same:

set substitute-path /from /to
set substitute-path /from/dir/../ /to

I therefore don't know if multi-mapping should be considered wrong here.
Also I don't think that glob matching would make this more common due to the aforementioned direction of the mapping.
For me, this is a completely separate issue.
  

Sorry, I need to make a correction. This topic can be a bit more confusing at times than I initially thought.

>>> Also, in the example I stated in my last reply, no file name that matches '/foo/include' would ever match '/bar/include'. The point I was trying to get across was that two unrelated files can already be mapped onto the same file (accidentally).
>>
>> Well, two wrongs don't make a right.
> 
> This is a very fair point. Having different files map to the same file in the local source directory could be annoying.
> Because this isn't a new issue per se, I thought about implementing a separate patch that would warn the user if two different files get mapped onto the same source file.
> But after some thought I realized that there are actually valid use-cases for this multi-mapping.
> 
> Let's say we have the following directory structure:
> 
> /inc.h
> /foo.c
> /dir/bar.c
> 
> '/foo.c' includes '/inc.h' via #include "inc.h".
> '/dir/bar.c' includes '/inc.h' via #include "../inc.h"
> 
> With GCC this will result in two entries in the debug info: '/inc.h' and '/dir/../inc.h'.
> For GDB these entries are two separate files. (Maybe this could changed with another patch though)
> But with the help of the following two rules we can tell GDB to treat them the same:
> 
> set substitute-path /from /to
> set substitute-path /from/dir/../ /to
> 
> I therefore don't know if multi-mapping should be considered wrong here.
> Also I don't think that glob matching would make this more common due to the aforementioned direction of the mapping.
> For me, this is a completely separate issue.

The rule

set substitute-path /from/dir/../ /to

would actually never match because '/dir/../inc.h' (inside '/from') would also match '/from' which is defined first.

Also you could make the case that this is not really a multi-mapping, because '/inc.h' and '/dir/../inc.h' are, of course, the same file.
But it makes implementing a usable warning more tedious.
Maybe a warning to the user is actually the right solution here but I'm not entirely sure.
What are your thoughts on this?