file-globbing: add docs for ordered pattern matching

docs/core/extensions/file-globbing.md

@@ -141,6 +141,36 @@ The preceding C# code:
 
 The additional `Match` overloads work in similar ways.
 
+### Ordered evaluation of include/exclude
+
+By default, the matcher evaluates **all** include patterns first, then applies **all** exclude patterns—regardless of the order in which you added them. This means you cannot re-include files that were previously excluded.
+
+Starting with version 10, you can opt into *ordered* evaluation so that includes and excludes are processed exactly in the sequence they were added:
+
+```csharp
+using Microsoft.Extensions.FileSystemGlobbing;
+
+// preserve the order of patterns when matching
+Matcher matcher = new(preserveFilterOrder: true);
+
+matcher.AddInclude("**/*");                // include everything
+matcher.AddExclude("logs/**/*");           // exclude logs
+matcher.AddInclude("logs/important/**/*"); // re-include important logs
+
+var result = matcher.Execute(new DirectoryInfoWrapper(new DirectoryInfo(root)));
+foreach (var file in result.Files)
+{
+    Console.WriteLine(file.Path);
+}
+```
+
+In this mode, patterns are applied one after another:  
+- `**/*` adds all files  
+- `logs/**/*` filters out anything in `logs/`  
+- `logs/important/**/*` adds back only files under `logs/important/`  
+
+Existing code that uses the default constructor will continue to run with the original “all includes, then all excludes” behavior.
+
 ## Pattern formats
 
 The patterns that are specified in the `AddExclude` and `AddInclude` methods can use the following formats to match multiple files or directories.