From 9ed5e21e5955dfbe6928bf6a314e2d422a608b24 Mon Sep 17 00:00:00 2001 From: Tai Groot Date: Wed, 8 Nov 2023 21:57:54 -0800 Subject: [PATCH] fix methods and add missing methods --- src/content/docs/ingredients/file.md | 80 +++++++++++++++++++++++++--- 1 file changed, 74 insertions(+), 6 deletions(-) diff --git a/src/content/docs/ingredients/file.md b/src/content/docs/ingredients/file.md index 4ec9256..0097b16 100644 --- a/src/content/docs/ingredients/file.md +++ b/src/content/docs/ingredients/file.md @@ -20,8 +20,14 @@ 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 delete -| _text_ | string | yes | the text to append to a file +| _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_ | bool | no | treat this file as a template and render it before placing it (experimental) +| _sources_ | string/list | no | list source, but in list format +| _source_hashes_ | string/list | no | corresponding hashes for sources #### Example ```yaml file.append: @@ -35,12 +41,14 @@ Validates if a file is cached in the sprout's cache. If it isn't the file will b #### 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 ```yaml file.cached: + - name: /tmp/cachedfile - source: https://go.dev/dl/go1.21.3.src.tar.gz - hash: sha256=186f2b6f8c8b704e696821b09ab2041a5c1ee13dcbc3156a13adcf75931ee488 ``` @@ -52,11 +60,11 @@ Copies content into a given file |-----------|------|----------|-------------| | _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 -| _skip_verify_ | bool | no (default: `false`) | Determines whether certain verifications should be skipped | _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_ | bool | no | treat this file as a template and render it before placing it (experimental) | _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 ```yaml @@ -81,10 +89,10 @@ Checks if a file contains a given selection. If multiple sources are provided, a | _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 and `skip_verify` is `false`) | a hash for a given source +| _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 `source` provided and `skip_verify` is `false`) | a list of source hashes -| _skip_verify_ | boolean | no (default: `false`) | whether to skip hash validation, false by default +| _source_hashes_ | list | conditional (required if `sources` provided) | a list of source hashes +| _template_ | bool | no | treat this file as a template and render it before placing it (experimental) ## **file.directory** @@ -141,11 +149,18 @@ Creates a symlink at `name` that points to `target` |-----------|------|----------|-------------| | _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 ```yaml file.symlink: - name: ~/localbash - target: /usr/bin/bash + - user: pi + - group: wheel + - mode: "655" ``` ## **file.touch** @@ -163,4 +178,57 @@ file.touch: - mtime: Mon, 06 Nov 2023 00:00:00 +0000 - makedirs: true ``` +## **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 `source` is provided) | 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_ | bool | no | treat this file as a template and render it before placing it (experimental) +| _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 +| _source_hashes_ | list | conditional (required if `sources` is provided) | Represents the hashes for the multiple source files mentioned in `sources` +#### Example +```yaml +file.managed: + - name: /srv/nginx/nginx.conf + - makdirs: true + - user: pi + - group: wheel + - text: | + server { + listen 8080; + root /data/up1; + location / { + } + } +``` + +## **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 | no | hash to verify the file specified by source +| _template_ | bool | no | treat this file as a template and render it before placing it (experimental) +| _sources_ | string/list | no | list source, but in list format +| _source_hashes_ | string/list | no | corresponding hashes for sources +#### Example +```yaml +file.prepend: + - name: /etc/profile + - text: | + export PATH=$PATH:/usr/local/go/bin +```