# file

manage a file

At most one of content, template, source, copy\_from, and stock sets the content. A step without any of them manages only the owner, group, and mode that it gives, of a file that exists. The step creates missing parent directories, owned by root with mode 0755.

## Keys

| Key | Type | Default | Meaning |
| --- | --- | --- | --- |
| [`path`](#file.path) | string | required | absolute |
| [`content`](#file.content) | string | - | literal text |
| [`template`](#file.template) | string | - | file in the recipe's templates/ |
| [`source`](#file.source) | string | - | file in the recipe's files/ |
| [`copy_from`](#file.copy_from) | string | - | file on the host |
| [`stock`](#file.stock) | boolean | false | content that the package ships |
| [`owner`](#file.owner) | name or ID | root |  |
| [`group`](#file.group) | name or ID | root |  |
| [`mode`](#file.mode) | string | 0644 | octal, in quotes |
| [`validate`](#file.validate) | string | - | check command for the new file |
| [`absent`](#file.absent) | boolean | false |  |
| [`replace`](#file.replace) | boolean | false | remove another kind of thing at path first |

### `file.path` {#file.path}

string, required

Absolute. The step creates missing parent directories, owned by root with mode 0755.

### `file.content` {#file.content}

string

Literal text. A step without content, template, source, copy\_from, or stock sets only the owner, group, and mode that it gives, with no defaults, of a file that exists. When that file is missing, the plan says does not exist yet. Apply fails when it is still missing.

### `file.template` {#file.template}

string

File in the recipe's templates/ directory. Its output is the content.

### `file.source` {#file.source}

string

File in the recipe's files/ directory. Its bytes are the content.

### `file.copy_from` {#file.copy_from}

string

File on the host. Its bytes are the content. Its permission bits, without the write bits of the group and others, are the default mode. The default owner and group stay root: the owner of the source does not carry over.

### `file.stock` {#file.stock}

boolean, default false

Content that the package ships for path, from the installed version. The package also gives the default owner, group, and mode.

### `file.owner` {#file.owner}

name or ID, default root

A user name or a numeric ID. A step without content has no default.

### `file.group` {#file.group}

name or ID, default root

A group name or a numeric ID. A step without content has no default.

### `file.mode` {#file.mode}

string, default 0644

Octal, in quotes: "0640". Without quotes, YAML reads it as a number. With stock, the package gives the default. With copy\_from, the source gives it, without the write bits of the group and others. A step without content has no default.

### `file.validate` {#file.validate}

string

Check command for the new file. The command names the real path, or checks the whole config: nginx -t. winch puts the new file in place and runs the command. When the command fails, the old file comes back and the step fails.

### `file.absent` {#file.absent}

boolean, default false

Remove the file. A path of another kind fails the check.

### `file.replace` {#file.replace}

boolean, default false

Remove another kind of thing at path first, such as a directory. Without it, such a thing fails the check.

## Example

```yaml
- name: Write the message of the day
  file:
    path: /etc/motd
    content: "Welcome to mail.example.com.\n"
    mode: "0644"
```