Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add reworked configuration docs. #245

Merged
merged 4 commits into from
Jan 11, 2019
Merged

Add reworked configuration docs. #245

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
68a6a9e
Add reworked configuration docs.
arturdryomov Dec 29, 2018
c81e9f3
Align the table.
arturdryomov Dec 29, 2018
4f3bb85
Address review comments.
arturdryomov Dec 30, 2018
f6d0172
Address review.
arturdryomov Jan 8, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 67 additions & 0 deletions docs/configuration/description.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
Files are placed in the `.mainframer` directory.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is overlapped with next paragraph and also is incorrect in case of ${HOME}/.config/mainframer

The final configuration is the combination of files placed in:

* `${HOME}/.mainframer` — the global configuration;
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

btw, that I would probably like to change to ~/.config/mainframer

A lot of other tools store configs there (example from my machine):

tree -L 1 ~/.config
/Users/user/.config
├── alacritty
├── gcloud
├── gtk-2.0
├── htop
├── kitty
├── nvim
└── thefuck

Can't find it being described as some standard other than by XDG https://unix.stackexchange.com/questions/68721/where-should-user-configuration-files-go but a lot of tools seem to use it now

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good. Yes, it is XDG-only, but I don’t mind a semi-clean home directory on macOS.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My example is from macOS just in case :)

* `.mainframer` — the project configuration.

It is posssible to share the configuration using the global one
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe reword?

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

and fine-tune it using the project one.

## `.mainframer`

The directory contains following files.

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

## `.mainframer/config.yml`

```yaml
remote:
name: "{SSH machine name}"
push:
compression: {level}
pull:
compression: {level}
```

Name | Optional | Value | Default | Description
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Usually it's "Required" instead of "Optional" :)

-------------------|----------|---------|---------|------------------
`remote.name` | No | `string`| — | Remote machine name from SSH config.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Hostname/IP or remote machine name from $HOME/.ssh/config."

`push.compression` | Yes | `0..9` | `0` | Compression level used to copy files from local machine to remote one.
`pull.compression` | Yes | `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`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section misses description

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Files are described in the .mainframer section above.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I guess I just wanted to see description there, ok let's go without it for now then


```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`.