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¶
Notes¶
Note
- This lookup can be used in ‘dual mode’, either passing a list of file names or a dictionary that has
files
andpaths
.
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¶
- This lookup is not guaranteed to have a backwards compatible interface. [preview]
- This lookup is maintained by the Ansible Community. [community]
Authors¶
- Seth Vidal <skvidal@fedoraproject.org>
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.