DOCS: Add missing docs for fmt, global flags, preview-push (StackExch…

…ange#2886)

Co-authored-by: Jeffrey Cafferata <[email protected]>

commands/commands.go

@@ -50,8 +50,9 @@ func Run(v string) int {
 	app.Usage = "DNSControl is a compiler and DSL for managing dns zones"
 	app.Flags = []cli.Flag{
 		&cli.BoolFlag{
-			Name:        "v",
-			Usage:       "Enable detailed logging",
+			Name:        "debug",
+			Aliases:     []string{"v"},
+			Usage:       "Enable debug logging",
 			Destination: &printer.DefaultPrinter.Verbose,
 		},
 		&cli.BoolFlag{

documentation/creds-json.md

@@ -225,13 +225,14 @@ An example of a template file containing Linode and Cloudflare API credentials i
 ```
 {% endcode %}
 
-## Don't store secrets in a Git repo!
+## Don't store creds.json in a Git repo!
 
-Do NOT store secrets in a Git repository. That is not secure. For example,
-storing the example `cloudflare_tal` is insecure because anyone with access to
-your Git repository or the history will know your apiuser is `REDACTED`.
-Removing secrets accidentally stored in Git is very difficult. You'll probably
-give up and re-create the repo and lose all history.
+Do NOT store `creds.json` (or any secrets!) in a Git repository. That is not secure.
 
-Instead, use environment variables as in the `hexonet` example above.  Use
+For example, storing the creds.json at the top of this document would be horribly insecure.
+Anyone with access to your Git repository *or the history* will know your apiuser is `REDACTED`.
+Removing secrets accidentally stored in Git is very difficult because you'll need to rewrite
+the repo history.
+
+A better way is to use environment variables as in the `hexonet` example above.  Use
 secure means to distribute the names and values of the environment variables.

documentation/fmt.md

@@ -0,0 +1,50 @@
+# fmt
+
+This is a stand-alone utility to pretty-format your `dnsconfig.js` configuration file.
+
+```shell
+NAME:
+   dnscontrol fmt - [BETA] Format and prettify a given file
+
+USAGE:
+   dnscontrol fmt [command options] [arguments...]
+
+CATEGORY:
+   utility
+
+OPTIONS:
+   --input value, -i value   Input file (default: "dnsconfig.js")
+   --output value, -o value  Output file
+   --help, -h                show help
+```
+
+## Examples
+
+By default the output goes to stdout:
+
+```shell
+dnscontrol fmt >new-dnsconfig.js
+```
+
+You can also redirect the output via the `-o` option:
+
+```shell
+dnscontrol fmt -o new-dnsconfig.js
+```
+
+The **safest** method involves making a backup first:
+
+```shell
+cp dnsconfig.js dnsconfig.js.BACKUP
+dnscontrol fmt -i dnsconfig.js.BACKUP -o dnsconfig.js
+```
+
+The **riskiest** method depends on the fact that DNSControl currently processes
+the `-o` file after the input file is completely read. It makes no backups.
+This is useful if Git is your backup mechanism.
+
+```shell
+git commit -m'backup dnsconfig.js' dnsconfig.js
+dnscontrol fmt -o dnsconfig.js
+git diff -- dnsconfig.js
+```

documentation/globalflags.md

@@ -0,0 +1,42 @@
+# Global Flags
+
+These flags are global. They affect all subcommands.
+
+```text
+   --debug, -v        Enable detailed logging (default: false)
+   --allow-fetch      Enable JS fetch(), dangerous on untrusted code! (default: false)
+   --disableordering  Disables update reordering (default: false)
+   --no-colors        Disable colors (default: false)
+   --help, -h         show help
+```
+
+They must appear before the subcommand.
+
+**Right**
+
+{% hint style="success" %}
+```shell
+dnscontrol --no-colors preview
+```
+{% endhint %}
+
+**Wrong**
+
+{% hint style="danger" %}
+```shell
+dnscontrol preview --no-colors
+```
+{% endhint %}
+
+* `-debug`
+  * Enable debug output.  (The `-v` alias is the original name for this flag. That alias will go away eventually.)
+
+
+* `--allow-fetch`
+  * Enable the `fetch()` function in `dnsconfig.js` (or equivalent). It is disabled by default because it can be used for nefarious purposes. It is dangerous on untrusted code!  Enable it only if you trust all the people editing dnsconfig.js.
+
+* `--disableordering`
+  * Disables update reordering. Normally DNSControl re-orders the updates done by `push`. This is usually only used to work around bugs in the reordering code.
+
+* `--no-colors`
+  * Disable colors. See [Disabling Colors](colors.md) for details.

documentation/preview-push.md

@@ -30,71 +30,84 @@ OPTIONS:
    --help, -h                                                 show help
 ```
 
-`--config name` -- Specifies the name of the main configuration file, normally
+* `--config name`
+  * Specifies the name of the main configuration file, normally
 `dnsconfig.js`.
 
-`--dev` -- Developer mode.  Normally `helpers.js` is embedded in the dnscontrol
-executable.  With this flag, the local file `helpers.js` is read instead.
-
-`--v foo=bar` -- Sets the variable `foo` to the value `bar` prior to
-interpreting the configuration file.  Multiple `-v` options can be used.
-
-`--creds name` -- Specifies the name of the credentials file, normally
-`creds.json`. Typically the file is read.  If the executable bit is set, the
-file is executed and the output is used as the configuration. (That feature may
-or may not work on Windows.)   If the filename begins with a `|` (for example:
-`|runme.sh`) the `|` is removed and the remaining string is used as the name of
-the program.
-
-`--providers name,name2` -- Specifies a comma-separated list of providers to
-enable.  The default is all providers.  A provider can opt out of being in the
-default list by `"_exclude_from_defaults": "true"` to the credentials entry for
-that provider. In that case, the provider will only be activated if it is
-included in `--providers`.
-
-`--domains value` -- Specifies a comma-separated list of domains to include.
-Typically all domains are included in `preview`/`push`.  Wildcards are not
-permitted except `*` at the start of the entry. For example, `--domains
-example.com,*.in-addr.arpa` would include `example.com` plus all reverse lookup
-domains.
-
-`--notify` -- Enables sending notifications to the destinations configured in
-`creds.json`.
-
-`--expect-no-changes` -- If set, a non-zero exit code is returned if there are
-changes.  Normally DNSControl sets the exit code based on whether or not there
-were protocol errors or other reasons the program can not continue. With this
-flag set, the exit code indicates if any changes were required.  This is
-typically used with `preview` to allow scripts to determine if changes would
-happen if `push` was used. For example, one might want to run `dnscontrol
-preview --expect-no-changes` daily to determine if changes have been made to
-a domain outside of DNSControl.
-
-`--no-populate` -- Do not auto-create non-existing zones at the provider.
-Normally non-existent zones are automatically created at a provider (unless the
-provider does not implement zone creation). This flag disables that feature.
-
-`--full` -- Add headings, providers names, notifications of no changes, etc. to
-the output.  Normally the output of `preview`/`push` is extremely brief. This
-makes the output more verbose. Useful for debugging.
-
-`--bindserial value` -- Force BIND serial numbers to this value. Normally the
-BIND provider generates SOA serial numbers automatically. This flag forces the
-serial number generator to output the value specified for all domains.  This is
-generally used for reproducibility in testing pipelines.
-
-`--report name` -- (`push` only!)  Generate a machine-parseable report of
-performed corrections in the file named `name`.  If no name is specified, no
-report is generated.
-
-## Experimental
+* `--creds name`
+  * Specifies the name of the credentials file, normally `creds.json`.
+    Typically the file is read. If the executable bit is set, the file is
+    executed and the output is used as the configuration. See
+    [creds.json][creds-json.md] for details.
+
+* `--providers name,name2`
+  * Specifies a comma-separated list of providers to
+    enable. The default is all providers. A provider can opt out of being in the
+    default list by `"_exclude_from_defaults": "true"` to the credentials entry for
+    that provider. In that case, the provider will only be activated if it is
+    included in `--providers`.
+
+* `--domains value`
+  * Specifies a comma-separated list of domains to include.
+    Typically all domains are included in `preview`/`push`. Wildcards are not
+    permitted except `*` at the start of the entry. For example, `--domains
+    example.com,*.in-addr.arpa` would include `example.com` plus all reverse lookup
+    domains.
+
+* `--v foo=bar`
+  * Sets the variable `foo` to the value `bar` prior to
+    interpreting the configuration file. Multiple `-v` options can be used.
+
+* `--notify`
+  * Enables sending notifications to the destinations configured in `creds.json`.
+
+* `--dev`
+  * Developer mode. Normally `helpers.js` is embedded in the dnscontrol
+    executable. With this flag, the local file `helpers.js` is read instead.
+
+* `--expect-no-changes`
+  * If set, a non-zero exit code is returned if there are
+    changes. Normally DNSControl sets the exit code based on whether or not there
+    were protocol errors or other reasons the program can not continue. With this
+    flag set, the exit code indicates if any changes were required. This is
+    typically used with `preview` to allow scripts to determine if changes would
+    happen if `push` was used. For example, one might want to run `dnscontrol
+    preview --expect-no-changes` daily to determine if changes have been made to
+    a domain outside of DNSControl.
+
+* `--no-populate`
+  * Do not auto-create non-existing zones at the provider.
+    Normally non-existent zones are automatically created at a provider (unless the
+    provider does not implement zone creation). This flag disables that feature.
+
+* `--full`
+  * Add headings, providers names, notifications of no changes, etc. to
+    the output. Normally the output of `preview`/`push` is extremely brief. This
+    makes the output more verbose. Useful for debugging.
+
+* `--bindserial value`
+  * Force BIND serial numbers to this value. Normally the
+    BIND provider generates SOA serial numbers automatically. This flag forces the
+    serial number generator to output the value specified for all domains. This is
+    generally used for reproducibility in testing pipelines.
+
+* `--report name`
+  * (`push` only!)  Generate a machine-parseable report of
+    performed corrections in the file named `name`. If no name is specified, no
+    report is generated.
+
+## ppreview/ppush
+
+{% hint style="info" %}
+Starting in v4.9
+{% endhint %}
 
 The `ppreview`/`ppush` subcommands are a preview of a future feature where zone
-data is gathered concurrently.  The commands will go away when
+data is gathered concurrently. The commands will go away when
 they replace the existing `preview`/`push` commands.
 
-`--cmode value` -- Concurrency mode.  Specifies what kind of providers should be run concurrently. This flag onl
-
-* `default` -- Providers are run sequentially or concurrently depending on whether the provider is marked as having been tested to run concurrently.
-* `none` -- All providers are run sequentially. This is the safest mode. It can be used if a concurrency bug is discovered.
-* `all` -- This is unsafe. It runs all providers concurrently, even the ones that have not be validated to run concurrently. It is generally only used for demonstrating bugs.
+* `--cmode value`
+  * Concurrency mode. Specifies what kind of providers should be run concurrently.
+    * `default` -- Providers are run sequentially or concurrently depending on whether the provider is marked as having been tested to run concurrently.
+    * `none` -- All providers are run sequentially. This is the safest mode. It can be used if a concurrency bug is discovered.
+    * `all` -- This is unsafe. It runs all providers concurrently, even the ones that have not be validated to run concurrently. It is generally only used for demonstrating bugs.