From 68a6a9e709234dac20c5613778cd74c87c7f4b1d Mon Sep 17 00:00:00 2001 From: Artur Dryomov Date: Sat, 29 Dec 2018 23:30:56 +0300 Subject: [PATCH 1/4] Add reworked configuration docs. --- docs/configuration/description.md | 67 +++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 docs/configuration/description.md diff --git a/docs/configuration/description.md b/docs/configuration/description.md new file mode 100644 index 0000000..a36f0af --- /dev/null +++ b/docs/configuration/description.md @@ -0,0 +1,67 @@ +Files are placed in the `.mainframer` directory. +The final configuration is the combination of files placed in: + +* `${HOME}/.mainframer` — the global configuration; +* `.mainframer` — the project configuration. + +It is posssible to share the configuration using the global 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 +-------------------|----------|---------|---------|------------------ +`remote.name` | No | `string`| — | Remote machine name from 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` + +```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`. + From c81e9f30df7084a6eff1e616dfc792e39e692fd4 Mon Sep 17 00:00:00 2001 From: Artur Dryomov Date: Sat, 29 Dec 2018 23:34:03 +0300 Subject: [PATCH 2/4] Align the table. --- docs/configuration/description.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/configuration/description.md b/docs/configuration/description.md index a36f0af..4d379b5 100644 --- a/docs/configuration/description.md +++ b/docs/configuration/description.md @@ -54,11 +54,11 @@ both: - "..." ``` -Name | Description | Suggestions --------|-------------|------------ +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. +`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) — From 4f3bb85649370e9c20ec593ea177ccf9cf2a1099 Mon Sep 17 00:00:00 2001 From: Artur Dryomov Date: Sun, 30 Dec 2018 10:25:37 +0300 Subject: [PATCH 3/4] Address review comments. --- docs/configuration/description.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/configuration/description.md b/docs/configuration/description.md index 4d379b5..92b4020 100644 --- a/docs/configuration/description.md +++ b/docs/configuration/description.md @@ -1,20 +1,22 @@ Files are placed in the `.mainframer` directory. The final configuration is the combination of files placed in: -* `${HOME}/.mainframer` — the global configuration; +* `${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 share the configuration using the global one +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 | Optional | Keep in VCS | Description +Name | Required | Keep in VCS | Description -------------|----------|-------------|------------ -`config.yml` | No | No | Configuration options. -`ignore.yml` | Yes | Yes | Ignore rules for copying files. +`config.yml` | Yes | No | Configuration options. +`ignore.yml` | No | Yes | Ignore rules for copying files. ## `.mainframer/config.yml` @@ -27,11 +29,11 @@ pull: compression: {level} ``` -Name | Optional | Value | Default | Description +Name | Required | Value | Default | Description -------------------|----------|---------|---------|------------------ -`remote.name` | No | `string`| — | Remote machine name from 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. +`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): From f6d0172053490d3bb8c4e5fb483bd1bd266b0364 Mon Sep 17 00:00:00 2001 From: Artur Dryomov Date: Tue, 8 Jan 2019 22:01:17 +0300 Subject: [PATCH 4/4] Address review. --- docs/configuration/description.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/configuration/description.md b/docs/configuration/description.md index 92b4020..db981b0 100644 --- a/docs/configuration/description.md +++ b/docs/configuration/description.md @@ -1,5 +1,6 @@ -Files are placed in the `.mainframer` directory. -The final configuration is the combination of files placed in: +# 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)