grlx.ingredients.file

The file ingredient handles all file operations on various file providers (such as local files, HTTP, etc.)

file.absent

Deletes a file or directory

Parameters

parameter	type	required	description
name	string	yes	the name/path of the file to delete

Example

file.absent:
    name: ~/.config/systemd/user/backup.service

file.append

Appends content to a file. Only appends the content if it doesn’t exist.

Parameters

parameter	type	required	description
name	string	yes	the name/path of the file to append to
text	string	no	the text to append to a file
makedirs	bool	no	create parent directories if they do not exist
source	string	no	append lines from a file sourced from this path/URL
source_hash	string	no	hash to verify the file specified by source
template experimental	bool	no	treat this file as a template and render it before placing
sources	string/list	no	appends all content specified in list, checked in order
source_hashes	string/list	no	corresponding hashes for sources

Example

file.append:
  - name: /etc/profile
  - text: |
      export PATH=$PATH:/usr/local/go/bin

file.cached

Validates if a file is cached in the sprout’s cache. If it isn’t the file will be cached.

Parameters

parameter	type	required	description
name	string	yes	the path describing where to save the cached file
source	string	yes	a file source (such as HTTP, file, etc.) to reference
hash	string	conditional (required if skip_verify is false)	a valid hash of the source file
skip_verify	boolean	no	whether to skip hash validation, false by default

Example

file.cached:
    - name: /tmp/cachedfile
    - source: https://go.dev/dl/go1.21.3.src.tar.gz
    - hash: sha256=186f2b6f8c8b704e696821b09ab2041a5c1ee13dcbc3156a13adcf75931ee488

file.contains

Checks if a file contains a given selection. If multiple sources are provided, all must be satisfied.

Parameters

parameter	type	required	description
name	string	yes	the name/path of the file to check
text	string	no	the item to search for
source	string	no	a file source (such as HTTP, file, etc.) to reference
source_hash	string	conditional (required if source provided)	a hash for a given source
sources	list	no	a list of sources to check against
source_hashes	list	conditional (required if skip_verify is false)	a list of source hashes
skip_verify	boolean	no	whether to skip hash validation, false by default
template experimental	bool	no	treat this file as a template and render it before placing it

file.content

Copies content into a given file

Parameters

parameter	type	required	description
name	string	yes	Represents the name of a file or directory
makedirs	bool	no (default: false)	Determines whether directories should be created if they don’t exist
source	string	no	Represents a source file’s path or name
source_hash	string	conditional (required if source is provided and skip_verify is false)	Represents the hash of a source file, used for verification
text	string/list	no	Represents the content of a file. Can be a single string or a list of items
sources	list	no	Represents multiple source files
template experimental	bool	no	treat this file as a template and render it before placing it
skip_verify	boolean	no	whether to skip hash validation, false by default
source_hashes	list	conditional (required if sources is provided and skip_verify is false)	Represents the hashes for the multiple source files mentioned in sources

Example

file.content:
    - name: /srv/nginx/nginx.conf
    - makedirs: true
    - text: |
        server {
            listen 8080;
            root /data/up1;

            location / {
            }
        }

file.directory

Handles many directory operations. Ensures that a directory exists with the given permissions.

Parameters

parameter	type	required	description
name	string	yes	the name/path of the directory
makedirs	bool	no	option to make directory if it doesn’t exist, defaults to true
user	string	no	the user who will own the directory
group	string	no	the group who will own the directory
dir_mode	string	no	the directory mode
file_mode	string	no	the file mode to set
recurse	bool	no	whether to recurse the directories and apply permissions

Example

file.directory:
    - name: /tmp/item
    - makedirs: false
    - user: grlx
    - group: grlx
    - dir_mode: 755
    - recurse: false

file.exists

Checks if a file exists.

Parameters

parameter	type	required	description
name	string	yes	the name/path of the file

Example

file.exists:
    - name: /tmp/exists

file.managed

Manage many properties of a file concurrently, safely

Parameters

parameter	type	required	description
name	string	yes	Represents the name of a file or directory
source	string	no	Represents a source file’s path or name
source_hash	string	conditional (required if skip_verify is false)	Represents the hash of a source file, used for verification
user	string	no	the user who will own the directory
group	string	no	the group who will own the directory
mode	string	no	the file’s mode
template experimental	bool	no	treat this file as a template and render it before placing it
makedirs	bool	no (default: false)	Determines whether directories should be created if they don’t exist
dir_mode	string	no	the directory mode
text	string/list	no	Represents the content of a file. Can be a single string or a list of items
sources	list	no	Represents multiple source files
skip_verify	boolean	no	whether to skip hash validation, false by default
source_hashes	list	conditional (required if sources is provided)	Represents the hashes for the multiple source files mentioned in sources

Example

file.managed:
    - name: /srv/nginx/nginx.conf
    - makedirs: true
    - user: pi
    - group: wheel
    - text: |
        server {
            listen 8080;
            root /data/up1;

            location / {
            }
        }

file.missing

Checks if a file is missing.

Parameters

parameter	type	required	description
name	string	yes	the name/path of the file

Example

file.missing:
    - name: /tmp/missing

file.prepend

Prepends content to a file. Only prepends the content if it doesn’t exist.

Parameters

parameter	type	required	description
name	string	yes	the name/path of the file to prepend to
text	string	no	the text to prepend to a file
makedirs	bool	no	create parent directories if they do not exist
source	string	no	prepend lines from a file sourced from this path/URL
source_hash	string	conditional (required if source is provided and skip_verify is false)	hash to verify the file specified by source
skip_verify	boolean	no	whether to skip hash validation, false by default
template experimental	bool	no	treat this file as a template and render it before placing it
sources	string/list	no	list source, but in list format
source_hashes	string/list	no	corresponding hashes for sources

Example

file.prepend:
  - name: /etc/profile
  - text: |
      export PATH=$PATH:/usr/local/go/bin

file.symlink

Creates a symlink at name that points to target

Parameters

parameter	type	required	description
name	string	yes	the name/path of the file
target	string	yes	the target path to link to
makedirs	string	no	make parent directories if missing
user	string	no	the user who should own the symlink
group	string	no	the group who should own the symlink
mode	string	no	the desired filemode of the symlink

Example

file.symlink:
    - name: ~/localbash
    - target: /usr/bin/bash
    - user: pi
    - group: wheel
    - mode: "655"

file.touch

Performs a touch on a file

parameter	type	required	description
name	string	yes	the name/path of the file
atime	time (RFC339)	no	the access time to set the file to, set to the current time by default
mtime	time (RFC339)	no	the modified time to set the file to, sets to the current time by default
makedirs	bool	yes	whether or not to create any provided parent directories, false by default

file.touch:
  - name: /tmp/parent/new-file
  - atime: Mon, 06 Nov 2023 00:00:00 +0000
  - mtime: Mon, 06 Nov 2023 00:00:00 +0000
  - makedirs: true