Adds max_matches parameter to ansible.builtin.find

[colin-nolan]

SUMMARY

ansible.builtin.find currently looks for matches in all non-filtered files. When there is a very big file system in the search scope, and/or an expensive search is made (e.g. based off whole file contents), the operation can be very expensive.

This PR adds the ability for the user to limit the number of matches that are made. Use cases that would benefit/be enabled with this functionality include:

• Determining if there are > n matching files in a directory.
• Finding the first directory in a nested tree with any files.
• Discovering where the file with matching content is (stopping once found!).

ISSUE TYPE

• Feature Pull Request

ADDITIONAL INFORMATION

Try the module using:

# Can't run module in place due to import issues caused by other modules in directory
cp lib/ansible/modules/find.py /tmp/find.py && python /tmp/find.py <<EOF
{
    "ANSIBLE_MODULE_ARGS": {
        "paths": "/var/log",
        "file_type": "file",
        "contains": "wally",
        "read_whole_file": true,
        "patterns": "^.*\\\.log$",
        "use_regex": true,
        "recurse": true,
        "max_matches": 1
    }
}
EOF