From f2f7c4166c5833b5b2e3157d4b8bccf1cd9a7edc Mon Sep 17 00:00:00 2001 From: Tai Groot Date: Wed, 8 Nov 2023 22:03:15 -0800 Subject: [PATCH] sort + alphabetize --- src/content/docs/ingredients/file.md | 140 ++++++++++++++------------- 1 file changed, 71 insertions(+), 69 deletions(-) diff --git a/src/content/docs/ingredients/file.md b/src/content/docs/ingredients/file.md index 0097b16..da7a35a 100644 --- a/src/content/docs/ingredients/file.md +++ b/src/content/docs/ingredients/file.md @@ -41,7 +41,7 @@ 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 +| _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 @@ -53,6 +53,20 @@ file.cached: - 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 `sources` provided) | a list of source hashes +| _template_ | bool | no | treat this file as a template and render it before placing it (experimental) + + ## **file.content** Copies content into a given file #### Parameters @@ -81,20 +95,6 @@ file.content: } ``` -## **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 `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** Handles many directory operations. Ensures that a directory exists with the given permissions. #### Parameters @@ -130,6 +130,41 @@ 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 `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.missing** Checks if a file is missing. #### Parameters @@ -142,6 +177,27 @@ 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 | 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 +``` + ## **file.symlink** Creates a symlink at `name` that points to `target` #### Parameters @@ -178,57 +234,3 @@ 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 -```