psi-jack/dotbot
1
0
Fork 0
mirror of synced 2024-11-25 01:25:35 -05:00
Code Issues Releases Wiki Activity

Standardize documentation for extended config

Browse source 
This patch adds parameter/explanation tables for the two other commands
that support extended configuration syntaxes, so now we have
identically-formatted tables for link, shell, and clean.

This change was prompted by
https://github.com/anishathalye/dotbot/issues/223.
This commit is contained in:
Anish Athalye 2020-06-19 20:28:47 -04:00
parent 8f136ee73f
commit 043373ea74
1 changed files with 55 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

92
README.md
View file

@ -119,9 +119,8 @@ The conventional name for the configuration file is `install.conf.yaml`.
``` ```
The configuration file is typically written in YAML, but it can also be written The configuration file is typically written in YAML, but it can also be written
in JSON (which is a subset of YAML). [Here][json-equivalent] is the JSON in JSON (which is a [subset of YAML][json2yaml]). JSON configuration files are
[equivalent][json2yaml] of the YAML configuration given above. JSON conventionally named `install.conf.json`.
configuration files are conventionally named `install.conf.json`.
## Configuration ## Configuration
@ -146,11 +145,11 @@ Following the formatting used in the examples is a good idea. If a YAML
configuration file is not behaving as you expect, try inspecting the configuration file is not behaving as you expect, try inspecting the
[equivalent JSON][json2yaml] and check that it is correct. [equivalent JSON][json2yaml] and check that it is correct.
Also, note that `~` in YAML is the same as `null` in JSON. If you want a single
character string containing a tilde, make sure to enclose it in quotes: `'~'`
## Directives ## Directives
Most Dotbot commands support both a simplified and extended syntax, and they
can also be configured via setting [defaults](#defaults).
### Link ### Link
Link commands specify how files and directories should be symbolically linked. Link commands specify how files and directories should be symbolically linked.
@ -161,25 +160,24 @@ files if necessary. Environment variables in paths are automatically expanded.
Link commands are specified as a dictionary mapping targets to source Link commands are specified as a dictionary mapping targets to source
locations. Source locations are specified relative to the base directory (that locations. Source locations are specified relative to the base directory (that
is specified when running the installer). If linking directories, *do not* include a trailing slash. is specified when running the installer). If linking directories, *do not*
include a trailing slash.
Link commands support an (optional) extended configuration. In this type of Link commands support an optional extended configuration. In this type of
configuration, instead of specifying source locations directly, targets are configuration, instead of specifying source locations directly, targets are
mapped to extended configuration dictionaries. mapped to extended configuration dictionaries.
Available extended configuration parameters: | Parameter | Explanation |
| --- | --- |
| Link Option | Explanation | | `path` | The source for the symlink, the same as in the shortcut syntax (default: null, automatic (see below)) |
| -- | -- | | `create` | When true, create parent directories to the link as needed. (default: false) |
| `path` | The source for the symlink, the same as in the shortcut syntax (default:null, automatic (see below)) | | `relink` | Removes the old target if it's a symlink (default: false) |
| `create` | When true, create parent directories to the link as needed. (default:false) | | `force` | Force removes the old target, file or folder, and forces a new link (default: false) |
| `relink` | Removes the old target if it's a symlink (default:false) | | `relative` | Use a relative path to the source when creating the symlink (default: false, absolute links) |
| `force` | Force removes the old target, file or folder, and forces a new link (default:false) | | `canonicalize-path` | Resolve any symbolic links encountered in the source to symlink to the canonical path (default: true, real paths) |
| `relative` | Use a relative path to the source when creating the symlink (default:false, absolute links) | | `glob` | Treat a `*` character as a wildcard, and perform link operations on all of those matches (default: false) |
| `canonicalize-path` | Resolve any symbolic links encountered in the source to symlink to the canonical path (default:true, real paths) |
| `glob` | Treat a `*` character as a wildcard, and perform link operations on all of those matches (default:false) |
| `if` | Execute this in your `$SHELL` and only link if it is successful. | | `if` | Execute this in your `$SHELL` and only link if it is successful. |
| `ignore-missing` | Do not fail if the source is missing and create the link anyway (default:false) | | `ignore-missing` | Do not fail if the source is missing and create the link anyway (default: false) |
#### Example #### Example
@ -202,7 +200,9 @@ Available extended configuration parameters:
If the source location is omitted or set to `null`, Dotbot will use the If the source location is omitted or set to `null`, Dotbot will use the
basename of the destination, with a leading `.` stripped if present. This makes basename of the destination, with a leading `.` stripped if present. This makes
the following config files equivalent: the following two config files equivalent.
Explicit sources:
```yaml ```yaml
- link: - link:
@ -220,6 +220,8 @@ the following config files equivalent:
relink: true relink: true
``` ```
Implicit sources:
```yaml ```yaml
- link: - link:
~/bin/ack: ~/bin/ack:
@ -267,11 +269,22 @@ Another way is to specify a two element array where the first element is the
shell command and the second is an optional human-readable description. shell command and the second is an optional human-readable description.
Shell commands support an extended syntax as well, which provides more Shell commands support an extended syntax as well, which provides more
fine-grained control. A command can be specified as a dictionary that contains fine-grained control.
the command to be run, a description, whether to suppress outputting the
command in the display via `quiet`, and whether `stdin`, `stdout`, | Parameter | Explanation |
and `stderr` are enabled. In this syntax, all keys are optional except for the | --- | --- |
command itself. | `command` | The command to be run |
| `description` | A human-readable message describing the command (default: null) |
| `quiet` | Show only the description but not the command in log output (default: false) |
| `stdin` | Allow a command to read from standard input (default: false) |
| `stdout` | Show a command's output from stdout (default: false) |
| `stderr` | Show a command's error output from stderr (default: false) |
Note that `quiet` controls whether the command (a string) is printed in log
output, it does not control whether the output from running the command is
printed (that is controlled by `stdout` / `stderr`). When a command's `stdin` /
`stdout` / `stderr` is not enabled (which is the default), it's connected to
`/dev/null`, disabling input and hiding output.
#### Example #### Example
@ -294,19 +307,22 @@ command itself.
Clean commands specify directories that should be checked for dead symbolic Clean commands specify directories that should be checked for dead symbolic
links. These dead links are removed automatically. Only dead links that point links. These dead links are removed automatically. Only dead links that point
to the dotfiles directory are removed unless the `force` option is set to to somewhere within the dotfiles directory are removed unless the `force`
`true`. option is set to `true`.
#### Format #### Format
Clean commands are specified as an array of directories to be cleaned. Clean commands are specified as an array of directories to be cleaned.
Clean commands support an extended configuration syntax. In this type of Clean commands also support an extended configuration syntax.
configuration, commands are specified as directory paths mapping to options. If
the `force` option is set to `true`, dead links are removed even if they don't | Parameter | Explanation |
point to a file inside the dotfiles directory. If `recursive` is set to `true`, | --- | --- |
the directory is traversed recursively (not recommended for `~` because it will | `force` | Remove dead links even if they don't point to a file inside the dotfiles directory (default: false) |
be slow). | `recursive` | Traverse the directory recursively looking for dead links (default: false) |
Note: using the `recursive` option for `~` is not recommended because it will
be slow.
#### Example #### Example
@ -326,8 +342,8 @@ Default options for plugins can be specified so that options don't have to be
repeated many times. This can be very useful to use with the link command, for repeated many times. This can be very useful to use with the link command, for
example. example.
Defaults apply to all commands that follow setting the defaults. Defaults can Defaults apply to all commands that come after setting the defaults. Defaults
be set multiple times; each change replaces the defaults with a new set of can be set multiple times; each change replaces the defaults with a new set of
options. options.
#### Format #### Format
@ -359,6 +375,8 @@ Plugins are loaded using the `--plugin` and `--plugin-dir` options, using
either absolute paths or paths relative to the base directory. It is either absolute paths or paths relative to the base directory. It is
recommended that these options are added directly to the `install` script. recommended that these options are added directly to the `install` script.
See [here][plugins] for a current list of plugins.
## Command-line Arguments ## Command-line Arguments
Dotbot takes a number of command-line arguments; you can run Dotbot with Dotbot takes a number of command-line arguments; you can run Dotbot with
@ -404,8 +422,8 @@ Copyright (c) 2014-2020 Anish Athalye. Released under the MIT License. See
[dotfiles-template]: https://github.com/anishathalye/dotfiles_template [dotfiles-template]: https://github.com/anishathalye/dotfiles_template
[inspiration]: https://github.com/anishathalye/dotbot/wiki/Users [inspiration]: https://github.com/anishathalye/dotbot/wiki/Users
[managing-dotfiles-post]: http://www.anishathalye.com/2014/08/03/managing-your-dotfiles/ [managing-dotfiles-post]: http://www.anishathalye.com/2014/08/03/managing-your-dotfiles/
[json-equivalent]: https://gist.github.com/anishathalye/84bd6ba1dbe936e05141e07ec45f5fd4
[json2yaml]: https://www.json2yaml.com/ [json2yaml]: https://www.json2yaml.com/
[plugins]: https://github.com/anishathalye/dotbot/wiki/Plugins
[wiki]: https://github.com/anishathalye/dotbot/wiki [wiki]: https://github.com/anishathalye/dotbot/wiki
[contributing]: CONTRIBUTING.md [contributing]: CONTRIBUTING.md
[license]: LICENSE.md [license]: LICENSE.md