Skip to content

first_found

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin
Added in version historical.

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 locations of role / play / include and so on.
  • The list of files has precedence over the paths searched. For example, 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 O(_terms) or a key O(files) with a list of files is required for this plugin to operate.

Parameters

Parameter Defaults / Choices Comments
_terms A list of file names.
files
list / elements=string		 A list of file names.
paths
list / elements=string		 A list of paths in which to look for the files.
skip
boolean		 When V(True), return an empty list when no files are matched.
This is useful when used with C(with_first_found), as an empty list return to C(with_) calls causes the calling task to be skipped.
When used as a template via C(lookup) or C(query), setting O(skip=True) will *not* cause the task to skip. Tasks must handle the empty list return from the template.
When V(False) and C(lookup) or C(query) specifies O(ignore:errors='ignore') all errors (including no file found, but potentially others) return V(None) or an empty list respectively.
When V(True) and C(lookup) or C(query) specifies O(ignore:errors='ignore'), no file found will return an empty list and other potential errors return V(None) or empty list depending on the template call (in other words return values of C(lookup) vs C(query)).

Notes

Note

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

Examples

- name: Set _found_file to the first existing file, raising an error if a file is not found
  ansible.builtin.set_fact:
    _found_file: "{{ lookup('ansible.builtin.first_found', findme) }}"
  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: Set _found_file to the first existing file, or an empty list if no files found
  ansible.builtin.set_fact:
    _found_file: "{{ lookup('ansible.builtin.first_found', files, paths=['/extra/path'], skip=True) }}"
  vars:
    files:
      - /path/to/foo.txt
      - /path/to/bar.txt

- name: Include tasks only if one of the files exist, otherwise skip the task
  ansible.builtin.include_tasks:
    file: "{{ item }}"
  with_first_found:
    - files:
      - path/tasks.yaml
      - path/other_tasks.yaml
      skip: True

- name: Include tasks only if one of the files exists, otherwise skip
  ansible.builtin.include_tasks: '{{ tasks_file }}'
  when: tasks_file is not none
  vars:
    tasks_file: "{{ lookup('ansible.builtin.first_found', files=['tasks.yaml', 'other_tasks.yaml'], 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
  ansible.builtin.copy:
    src: "{{ lookup('ansible.builtin.first_found', findme) }}"
    dest: /some/file
  vars:
    findme:
      - foo
      - "{{ inventory_hostname }}"
      - bar

- name: same copy but specific paths
  ansible.builtin.copy:
    src: "{{ lookup('ansible.builtin.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
  ansible.builtin.template:
    src: "{{ lookup('ansible.builtin.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
  ansible.builtin.include_vars: "{{lookup('ansible.builtin.first_found', params)}}"
  vars:
    params:
      files:
        - '{{ ansible_distribution }}.yml'
        - '{{ ansible_os_family }}.yml'
        - default.yml
      paths:
        - 'vars'

Return Values

Key Data Type Description Returned
_raw list path to file found

Authors