first_found – return first file found from list

Synopsis

  • this lookup checks a list of files and paths and returns the full path to the first combination found.

  • As all lookups, when fed relative paths it will try use the current task’s location first and go up the chain to the containing role/play/include/etc’s location.

  • The list of files has precedence over the paths searched. i.e, A task in a role has a ‘file1’ in the play’s relative path, this will be used, ‘file2’ in role’s relative path will not.

  • Either a list of files _terms or a key files with a list of files is required for this plugin to operate.

Parameters

Parameter Choices/Defaults Configuration Comments
_terms
-
list of file names
files
-
list of file names
paths
-
list of paths in which to look for the files
skip
boolean
Default:
"no"
Return an empty list if no file is found, instead of an error.

Notes

Note

  • This lookup can be used in ‘dual mode’, either passing a list of file names or a dictionary that has files and paths.

Examples

- name: show first existing file or ignore if none do
  debug: msg={{lookup('first_found', findme, errors='ignore')}}
  vars:
    findme:
      - "/path/to/foo.txt"
      - "bar.txt"  # will be looked in files/ dir relative to role and/or play
      - "/path/to/biz.txt"

- name: |
        include tasks only if files exist.  Note the use of query() to return
        a blank list for the loop if no files are found.
  import_tasks: '{{ item }}'
  vars:
    params:
      files:
        - path/tasks.yaml
        - path/other_tasks.yaml
  loop: "{{ q('first_found', params, errors='ignore') }}"

- name: |
        copy first existing file found to /some/file,
        looking in relative directories from where the task is defined and
        including any play objects that contain it
  copy: src={{lookup('first_found', findme)}} dest=/some/file
  vars:
    findme:
      - foo
      - "{{inventory_hostname}}"
      - bar

- name: same copy but specific paths
  copy: src={{lookup('first_found', params)}} dest=/some/file
  vars:
    params:
      files:
        - foo
        - "{{inventory_hostname}}"
        - bar
      paths:
        - /tmp/production
        - /tmp/staging

- name: INTERFACES | Create Ansible header for /etc/network/interfaces
  template:
    src: "{{ lookup('first_found', findme)}}"
    dest: "/etc/foo.conf"
  vars:
    findme:
      - "{{ ansible_virtualization_type }}_foo.conf"
      - "default_foo.conf"

- name: read vars from first file found, use 'vars/' relative subdir
  include_vars: "{{lookup('first_found', params)}}"
  vars:
    params:
      files:
        - '{{ansible_os_distribution}}.yml'
        - '{{ansible_os_family}}.yml'
        - default.yml
      paths:
        - 'vars'

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key Returned Description
_raw
-
path to file found


Status

Authors

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.