Skip to content

Commit

Permalink
Add reworked configuration docs. (#245)
Browse files Browse the repository at this point in the history
* Add reworked configuration docs.

* Align the table.

* Address review comments.

* Address review.
  • Loading branch information
arturdryomov authored and artem-zinnatullin committed Jan 11, 2019
1 parent ab08a59 commit 88b85fb
Showing 1 changed file with 70 additions and 0 deletions.
70 changes: 70 additions & 0 deletions docs/configuration/description.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Configuration

Files can be put in two places.

* `${HOME}/.config/mainframer` or
[`${XDG_CONFIG_HOME}`](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
if available — the global configuration;
* `.mainframer` — the project configuration.

It is posssible to declare common configuration using the global one
and fine-tune it using the project one.

## `.mainframer`

The directory contains following files.

Name | Required | Keep in VCS | Description
-------------|----------|-------------|------------
`config.yml` | Yes | No | Configuration options.
`ignore.yml` | No | Yes | Ignore rules for copying files.

## `.mainframer/config.yml`

```yaml
remote:
name: "{SSH machine name}"
push:
compression: {level}
pull:
compression: {level}
```
Name | Required | Value | Default | Description
-------------------|----------|---------|---------|------------------
`remote.name` | Yes | `string`| — | Remote machine name from SSH config or hostname / IP address.
`push.compression` | No | `0..9` | `0` | Compression level used to copy files from local machine to remote one.
`pull.compression` | No | `0..9` | `0` | Compression level used to copy files from remote machine to local one.

Compression level is inherited from underlying `rsync`
which uses [`zlib` values](https://www.zlib.net/manual.html):

> The compression level must be between `0` and `9`:
> `1` gives best speed, `9` gives best compression, `0` gives no compression at all
> (the input data is simply copied a block at a time).

## `.mainframer/ignore.yml`

```yaml
push:
- "pattern"
- "..."
pull:
- "pattern"
- "..."
both:
- "pattern"
- "..."
```

Name | Description | Suggestions
-------|---------------------------------------------------------------|------------
`push` | Patterns used to copy files from local machine to remote one. | Build results.
`pull` | Patterns used to copy files from remote machine to local one. | Source code.
`both` | Patterns used to copy files both ways. | VCS, IDE-related directories.

Ignore patterns are inherited from underlying `rsync`.
Please refer to [`rsync` documentation](https://download.samba.org/pub/rsync/rsync.html) —
see the _Include/Exclude Pattern Rules_ section.
The format is very similar to `.gitignore`.

0 comments on commit 88b85fb

Please sign in to comment.