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