First, I used google search AI response that wasted a lot of my time because it was wrong and did not provide information about requirements for root_dir parameters in the pathspec API. (Not your problem, but my request might address that.

What I learned is that I need to use a .gitignore in the root_dir that I pass to match_tree_files.
While I understand that patterns in .gitignore are relative to the root_dir, I might not want to process that entire tree. Maybe I only want to traverse root_dir/src. There does not seem to be a way to do that.
The google search example used Path.walk() and then match_file to check each file. However, it did not take into account that the path being checked needs to be "correctly" relative to root_dir.

My thoughts about the API.

1. a PathSpec constructor should take the root directory as a parameter. I used the from_lines method to create the PathSpec object. I passed in the gitignore lines. For those gitignore lines to have meaning, PathSpec also needs to know the root directory that they apply to.
2. passing the root directory to match_tree_files is problematic as it might not be the actual root relative to the path specs. The directory passed to match_tree_files should be the directory to traverse and it must be the root directory of a subdirectory. This completely removes the confusion between how paths are checked and what paths are being traversed.

In addition, it would be nice if full support for the handling of gitignore inside pathspec was provided. See Open in GitHub Copilot app