Prototype: findfiles_up(path, glob, level)

Return type: data

Description: Return a data array of files that match a given glob pattern by searching up the directory tree.

This function searches for files matching a given glob pattern glob in the local filesystem by searching up the directory tree from a given absolute path path. The function searches at moast level levels of directories or until the root directory is reached. Argument level defaults to inf if not specified. The function returns a list of files as a data array where the first element (element 0) and the last element (element N) is first and last file or directory found respectively.

Note that glob patterns are not regular expressions. They match like Unix shells:

  • * matches any filename or directory
  • ? matches a single letter
  • [a-z] matches any letter from a to z

WARNING: - The current implementation of glob patterns on Windows contains bugs. Therefore, we strongly recommend using the !windows:: class guard expression to safeguard against any use of the function on Windows platforms. Rest assured, we are actively working on resolving these issues and improving its functionality.

Notes:

  • Brace expansion is not currently supported, {x,y,anything} will not match x or y or anything.

Arguments:

  • path: string - Path to search from - in the range: "?(/.*)
  • glob: string - Glob pattern to match files - in the range: .+
  • level: int - Number of levels to search - in the range: 0,99999999999

Example:

code
bundle agent __main__
{
  vars:
      "path" # path to search up from
        string => "/tmp/repo/submodule/some/place/deep/within/my/repo/";
      "glob" # glob pattern matching filename
        string => ".git/config";
      "level" # how far to search
        int => "inf";
      "configs"
        data => findfiles_up("$(path)", "$(glob)", "$(level)");
  reports:
      "Submodules '$(glob)' is located in '$(configs[0])'";
      "Parents '$(glob)' is located in '$(configs[1])'";
}

Output:

code
R: Submodules '.git/config' is located in '/tmp/repo/submodule/.git/config'
R: Parents '.git/config' is located in '/tmp/repo/.git/config'

History: Introduced in 3.18.

See also: findfiles().