Support recursive globs in file monitoring (#10064)

[tdammers]

Implements support for recursive globs (some/path/**/file.name) for file monitoring.

• Patches conform to the coding conventions.
• Any changes that could be relevant to users have been recorded in the changelog.
  • Is the change significant? If so, remember to add significance: significant in the changelog file.
• The documentation has been updated, if necessary.
• Manual QA notes have been included.
• Tests have been added. (Ask for help if you don’t know how to write them! Ask for an exemption if tests are too complex for too little coverage!)

QA Notes

Previously, attempting to use recursive globs (**) to declare build rules (with build-type "Hooks") would yield an error message saying that this isn't implemented; this should now work. See #10064 for details and examples.

[philderbeast]

Will this resolve #10064?

[tdammers]

Will this resolve #10064?

Yes, that is the idea.

[sheaf]

This is looking great, but I think the testing strategy is insufficient. It's quite awkward to go through SetupHooks for testing; I'm not sure whether there's a better (and more direct) way to test the code. We definitely need to test more things:

• recurring deeper into subdirectories of subdirectories
• making sure that we don't monitor things that we shouldn't:
  • adding a directory which contains no files that match
  • modifying a file that doesn't match at any level of the directory hierarchy

Again it's not great to test this within the SetupHooks framework as it muddies the waters (and unrelated bugs may interfere).

I'm also wondering whether we need to take into account possible recursive symlinks?
If we have foo/bar/baz which is a symlink back to foo, then we could enter an infinite loop here. So perhaps we need to additionally keep track of which directories we have seen to avoid entering them again?

[tdammers]

This is looking great, but I think the testing strategy is insufficient. It's quite awkward to go through SetupHooks for testing; I'm not sure whether there's a better (and more direct) way to test the code. We definitely need to test more things:

* recurring deeper into subdirectories of subdirectories

* making sure that we don't monitor things that we shouldn't:
  
  * adding a directory which contains no files that match
  * modifying a file that doesn't match at any level of the directory hierarchy

Probably also:

• Adding/removing entire new subdirectories (and subdirectories of subdirectories)
• Moving files between sub(-sub-sub-...)directories
• Changing a directory name such that files below it that would previously match no longer do (and also the reverse)

Again it's not great to test this within the SetupHooks framework as it muddies the waters (and unrelated bugs may interfere).

Indeed, I found this test quite awkward to write. Do you have any pointers for me where/how this could better fit into the existing testing framework?

I'm also wondering whether we need to take into account possible recursive symlinks? If we have foo/bar/baz which is a symlink back to foo, then we could enter an infinite loop here. So perhaps we need to additionally keep track of which directories we have seen to avoid entering them again?

Good point, we should probably do that. The alternative would be to just not support symlinks, but that doesn't sound like a nice thing to do to me.

[sheaf]

Indeed, I found this test quite awkward to write. Do you have any pointers for me where/how this could better fit into the existing testing framework?

It seems there are unit tests for file monitoring in cabal-install/tests/UnitTests/Distribution/Client/FileMonitor. Adding the tests we discussed above sounds like a great plan, so we can make sure the file monitoring logic is correct before we investigate the potential recompilation issue with SetupHooks.

[sheaf]

This looks excellent. As far as I can see, all that's left to do is to rebase, squash the commits, and update the expected output for the SetupHooksRecursiveGlob test.

[mergify]

Merge Queue Status

• ✅ Entered queue — 2026-05-02 10:17 UTC · Rule: default
• ✅ Checks skipped · PR is already up-to-date
• ✅ Merged — 2026-05-02 10:27 UTC · at 53d2cda31926f6547329405b51a0f86efc8f6a2b · merge

This pull request spent 10 minutes 25 seconds in the queue, including 1 second running CI.

Required conditions to merge

• #approved-reviews-by >= 2 [🛡 GitHub branch protection]
  • Support recursive globs in file monitoring (#10064) #11658
• #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • Support recursive globs in file monitoring (#10064) #11658
• #review-threads-unresolved = 0 [🛡 GitHub branch protection]
  • Support recursive globs in file monitoring (#10064) #11658
• any of [🛡 GitHub branch protection]:
  • check-success = Doctest Cabal
  • check-neutral = Doctest Cabal
  • check-skipped = Doctest Cabal
• any of [🛡 GitHub branch protection]:
  • check-success = Meta checks
  • check-neutral = Meta checks
  • check-skipped = Meta checks
• any of [🛡 GitHub branch protection]:
  • check-success = docs/readthedocs.org:cabal
  • check-neutral = docs/readthedocs.org:cabal
  • check-skipped = docs/readthedocs.org:cabal
• any of [🛡 GitHub branch protection]:
  • check-success = Validate post job
  • check-neutral = Validate post job
  • check-skipped = Validate post job
• any of [🛡 GitHub branch protection]:
  • check-success = fourmolu
  • check-neutral = fourmolu
  • check-skipped = fourmolu
• any of [🛡 GitHub branch protection]:
  • check-success = hlint
  • check-neutral = hlint
  • check-skipped = hlint
• any of [🛡 GitHub branch protection]:
  • check-success = Bootstrap post job
  • check-neutral = Bootstrap post job
  • check-skipped = Bootstrap post job
• any of [🛡 GitHub branch protection]:
  • check-success = whitespace
  • check-neutral = whitespace
  • check-skipped = whitespace
• any of [🛡 GitHub branch protection]:
  • check-success = Check sdist post job
  • check-neutral = Check sdist post job
  • check-skipped = Check sdist post job
• any of [🛡 GitHub branch protection]:
  • check-success = Changelogs
  • check-neutral = Changelogs
  • check-skipped = Changelogs