DOCS: Add missing docs for fmt, global flags, preview-push (#2886)

Co-authored-by: Jeffrey Cafferata <jeffrey@jcid.nl>

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",
+			Name:        "debug",
-			Usage:       "Enable detailed logging",
+			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,
+Do NOT store `creds.json` (or any secrets!) in a Git repository. That is not secure.
-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.
 
-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,38 +30,43 @@ 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
+* `--creds name`
-executable.  With this flag, the local file `helpers.js` is read instead.
+  * 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.
 
-`--v foo=bar` -- Sets the variable `foo` to the value `bar` prior to
+* `--providers name,name2`
-interpreting the configuration file.  Multiple `-v` options can be used.
+  * Specifies a comma-separated list of providers to
-
-`--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.
+* `--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
+* `--v foo=bar`
-`creds.json`.
+  * Sets the variable `foo` to the value `bar` prior to
+    interpreting the configuration file. Multiple `-v` options can be used.
 
-`--expect-no-changes` -- If set, a non-zero exit code is returned if there are
+* `--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
@@ -70,31 +75,39 @@ 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.
+* `--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
+* `--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
+* `--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
+* `--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
+## 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
 they replace the existing `preview`/`push` commands.
 
-`--cmode value` -- Concurrency mode.  Specifies what kind of providers should be run concurrently. This flag onl
+* `--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.