# dir

manage a directory

The step creates missing parent directories, owned by root with mode 0755. winch checks owner, group, and mode on every run.

## Keys

| Key | Type | Default | Meaning |
| --- | --- | --- | --- |
| [`path`](#dir.path) | string | required | absolute |
| [`owner`](#dir.owner) | name or ID | root |  |
| [`group`](#dir.group) | name or ID | root |  |
| [`mode`](#dir.mode) | string | 0755 | octal, in quotes |
| [`recurse`](#dir.recurse) | boolean | false | owner and group for the whole tree |
| [`absent`](#dir.absent) | boolean | false | remove it with its content |
| [`replace`](#dir.replace) | boolean | false | remove another kind of thing at path first |
| [`purge`](#dir.purge) | boolean | false | remove entries that nothing declares |
| [`keep`](#dir.keep) | list of strings | - | name patterns that purge keeps |

### `dir.path` {#dir.path}

string, required

Absolute. The step creates missing parent directories, owned by root with mode 0755. It follows a symbolic link to a directory and manages the directory behind it.

### `dir.owner` {#dir.owner}

name or ID, default root

A user name, or a numeric ID that needs no account. A value of only digits is an ID, also in quotes.

### `dir.group` {#dir.group}

name or ID, default root

A group name, or a numeric ID that needs no group. A value of only digits is an ID, also in quotes.

### `dir.mode` {#dir.mode}

string, default 0755

Octal, in quotes: "0750". Without quotes, YAML reads it as a number.

### `dir.recurse` {#dir.recurse}

boolean, default false

Owner and group for the whole tree. The mode stays the mode of the directory alone. The plan fails when another step gives a path in the tree another owner or group; a file with content and no owner counts as root.

### `dir.absent` {#dir.absent}

boolean, default false

Remove it with its content.

### `dir.replace` {#dir.replace}

boolean, default false

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

### `dir.purge` {#dir.purge}

boolean, default false

Remove entries that nothing declares. Purge looks only at the direct entries. It keeps an entry that a package owns, or that a step for the host writes. Each removal is a change.

### `dir.keep` {#dir.keep}

list of strings

Name patterns that purge keeps, such as \*.db. They are glob patterns. keep needs purge.

## Example

```yaml
- dir:
    path: /var/www/app
    owner: www-data
    group: www-data
    mode: "0750"
```