cherry pick #5322 to release-4.0

TomShawn · ti-srebot · commit fd7fe8095776 · 2021-04-16T19:18:15.000+08:00
Signed-off-by: ti-srebot &lt;ti-srebot@pingcap.com&gt;
diff --git a/tiup/tiup-command-list.md b/tiup/tiup-command-list.md
@@ -20,19 +20,19 @@ tiup list [component] [flags]
 
 - Displays all components. By default, TiUP does not show hidden components.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --installed
 
 - Only displays components and versions that have been installed.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --verbose
 
 - Displays installed component versions in the components list.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Outputs
 
diff --git a/tiup/tiup-command-mirror-clone.md b/tiup/tiup-command-mirror-clone.md
@@ -21,7 +21,7 @@ tiup mirror clone <target-dir> [global version] [flags]
 
 - Whether to clone the whole mirror. If this option is set, other options becomes ignored and TiUP completely clones all components of all versions from the targeted mirror.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### -a, --arch
 
@@ -39,7 +39,7 @@ tiup mirror clone <target-dir> [global version] [flags]
 
 - Whether to only match the prefix of versions. By default, TiUP downloads a component version when it is strictly matched. If this option is set, TiUP also downloads component versions of which prefixes are matched.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --{component}
 
diff --git a/tiup/tiup-command-mirror-genkey.md b/tiup/tiup-command-mirror-genkey.md
@@ -35,13 +35,13 @@ tiup mirror genkey [flags]
 - Shows the corresponding public key of the private key specified in the option `-n/--name`.
 - TiUP does not create a new private key when `-p/--public` is specified. If the private key specified in `-n/--name` does not exist, TiUP returns an error.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --save
 
 - Saves the information of the public key as a file in the current directory. The file name is `{hash-prefix}-public.json`. `hash-prefix` is the first 16 bits of the key ID.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Outputs
 
diff --git a/tiup/tiup-command-mirror-publish.md b/tiup/tiup-command-mirror-publish.md
@@ -73,7 +73,7 @@ The meaning of each parameter is as follows:
 
 - Controls whether the component can run standalone. This option is currently **NOT available**.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Outputs
 
diff --git a/tiup/tiup-command-uninstall.md b/tiup/tiup-command-uninstall.md
@@ -22,13 +22,13 @@ tiup uninstall <component1>:<version> [component2...N] [flags]
 
 - Uninstalls all installed versions of the specified component(s). You must use this option when `<version>` is omitted.
 - Data type: `BOOLEAN`
-- Default: `false`
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --self
 
 - Uninstalls TiUP itself. When this option is used, all data downloaded from the mirror is deleted, but the data generated by TiUP and its components is retained. The data is stored in the directory specified by the `TIUP_HOME` environment variable. If `TIUP_HOME` is not set, the default value is `~/.tiup/`.
 - Data type: `BOOLEAN`
-- Default: `false`
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Outputs
 
diff --git a/tiup/tiup-command-update.md b/tiup/tiup-command-update.md
@@ -24,25 +24,25 @@ The update operation does not delete the old version. You can still specify usin
 
 - If no component is specified, this option must be specified.
 - Data type: `BOOLEAN`
-- Default: `false`
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --force
 
 - If the specified version of the component is already installed, the update operation is skipped by default. Specifying this option will have the installed version forcibly updated.
 - Data type: `BOOLEAN`
-- Default: `false`
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --nightly
 
 - Updates the specified components to the nightly version. The `tiup update` command with this option is equivalent to the `tiup update <component>:nightly` command.
 - Data type: `BOOLEAN`
-- Default: `false`
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --self
 
 - Updates TiUP itself.
 - Data type: `BOOLEAN`
-- Default: `false`
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Outputs
 
diff --git a/tiup/tiup-component-cluster-audit.md b/tiup/tiup-component-cluster-audit.md
@@ -21,7 +21,7 @@ tiup cluster audit [audit-id] [flags]
 
 - Prints the help information.
 - Data type: `Boolean`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Outputs
 
diff --git a/tiup/tiup-component-cluster-clean.md b/tiup/tiup-component-cluster-clean.md
@@ -24,7 +24,7 @@ tiup cluster clean <cluster-name> [flags]
 
 - Cleans data and the log at the same time. It is equivalent to specifying `--data` and `--log` at the same time.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 - If it is not specified, you must specify at lease one of the following options:
     - --data: Cleans data
     - --log: Cleans the log
@@ -33,13 +33,13 @@ tiup cluster clean <cluster-name> [flags]
 
 - Cleans data. If neither of it nor `--all` is specified, data will not be cleaned.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --log
 
 - Cleans the log. If neither of it nor `--all` is specified, the log will not be cleaned.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --ignore-node
 
@@ -57,7 +57,7 @@ tiup cluster clean <cluster-name> [flags]
 
 - Prints help information.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Output
 
diff --git a/tiup/tiup-component-cluster-deploy.md b/tiup/tiup-component-cluster-deploy.md
@@ -34,12 +34,12 @@ tiup cluster deploy <cluster-name> <version> <topology.yaml> [flags]
 
 - Specifies the password used to connect to the target machine. Do not use this option with `-i/--identity_file` at the same time.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --ignore-config-check
 
 - This option is used to skip the configuration check. After the binary files of components are deployed, the configurations of TiDB, TiKV, and PD components are checked using `<binary> --config-check <config-file>`. `<binary>` is the path of the deployed binary file. `<config-file>` is the configuration file generated based on the user configuration.
-- Data type: `BOOLEAN`
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 - Default: false
 
 ### --no-labels
@@ -48,19 +48,19 @@ tiup cluster deploy <cluster-name> <version> <topology.yaml> [flags]
 - When two or more TiKV nodes are deployed on the same physical machine, a risk exists: PD cannot learn the cluster topology, so PD might schedule multiple replicas of a Region to different TiKV nodes on one physical machine, which makes this physical machine a single point. To avoid this risk, you can use labels to tell PD not to schedule the same Region to the same machine. See [Schedule Replicas by Topology Labels](/schedule-replicas-by-topology-labels.md) for label configuration.
 - For the test environment, this risk might matter and you can use `--no-labels` to skip the check.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --skip-create-user
 
 - During the cluster deployment, tiup-cluster checks whether the specified user name in the topology file exists or not. If not, it creates one. To skip this check, you can use the `--skip-create-user` option.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### -h, --help
 
 - Prints help information.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Output
 
diff --git a/tiup/tiup-component-cluster-destroy.md b/tiup/tiup-component-cluster-destroy.md
@@ -24,7 +24,7 @@ tiup cluster destroy <cluster-name> [flags]
 
 - In some cases, some nodes in the cluster have been down, making it impossible to connect to the node through SSH for operation. At this time, you can use the `--force` option to ignore these errors.
 - Data type: `Boolean`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### --retain-node-data
 
@@ -42,7 +42,7 @@ tiup cluster destroy <cluster-name> [flags]
 
 - Prints the help information.
 - Data type: `Boolean`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Output
 
diff --git a/tiup/tiup-component-cluster-disable.md b/tiup/tiup-component-cluster-disable.md
@@ -40,7 +40,7 @@ tiup cluster disable <cluster-name> [flags]
 
 - Prints the help information.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Output
 
diff --git a/tiup/tiup-component-cluster-display.md b/tiup/tiup-component-cluster-display.md
@@ -20,7 +20,7 @@ tiup cluster display <cluster-name> [flags]
 
 - By default, all node information of the entire cluster is displayed. With the `--dashboard` option, only dashboard information is displayed.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ### -N, --node
 
@@ -46,7 +46,7 @@ tiup cluster display <cluster-name> [flags]
 
 - Prints the help information.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Outputs
 
diff --git a/tiup/tiup-component-cluster-edit-config.md b/tiup/tiup-component-cluster-edit-config.md
@@ -25,9 +25,9 @@ tiup cluster edit-config <cluster-name> [flags]
 
 - Prints help information.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Output
 
-- Normally, no output.
-- If you have mistakenly modified the fields that cannot be modified, when you save the file, an error will be reported, reminding you to edit the file again. For the fields that cannot be modified, see topology file<!-- (/tiup/tiup-cluster-topology-reference.md) -->.
+- If the command is successfully executed, there is no output.
+- If you have mistakenly modified the fields that cannot be modified, when you save the file, an error will be reported, reminding you to edit the file again. For the fields that cannot be modified, see the topology file<!-- /tiup/tiup-cluster-topology-reference.md) -->.
diff --git a/tiup/tiup-component-cluster-list.md b/tiup/tiup-component-cluster-list.md
@@ -22,7 +22,7 @@ tiup cluster list [flags]
 
 - Prints help information.
 - Data type: `BOOLEAN`
-- Default: false
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
 
 ## Outputs
 
diff --git a/tiup/tiup-reference.md b/tiup/tiup-reference.md
@@ -0,0 +1,88 @@
+---
+title: TiUP Reference
+---
+
+# TiUP Reference
+
+TiUP serves as the package manager of the TiDB ecosystem. It manages components in the TiDB ecosystem, such as TiDB, PD, and TiKV.
+
+## Syntax
+
+```shell
+tiup [flags] <command> [args...]        # Executes a command
+# or
+tiup [flags] <component> [args...]      # Runs a component
+```
+
+You can use the `help` command to get the information of a specific command. The summary of each command shows its parameters and their usage. Mandatory parameters are shown in angle brackets, and optional parameters are shown in square brackets.
+
+`<command>` represents the command name. For the list of supported commands, see the [Command list](#command-list) below. `<component>` represents the component name. For the list of supported components, see the [Component list](#component-list) below.
+
+## Options
+
+### -B, --binary
+
+- If you enable this option, the specified binary file path is printed.
+
+    - Executing `tiup -B/--binary <component>` will have the path of the latest stable installed `<component>` component printed. If `<component>` is not installed, an error is returned.
+    - Executing `tiup -B/--binary <component>:<version>` will have the path of the installed `<component>` component's `<version>` printed. If this `<version>` is not printed, an error is returned.
+
+- Data type: `BOOLEAN`
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
+
+> **Note:**
+>
+> This option can only be used in commands of the `tiup [flags] <component> [args...]` format.
+
+### --binpath
+
+> **Note:**
+>
+> This option can only be used in commands of the `tiup [flags] <component> [args...]` format.
+
+- Specifies the path of the component to be executed. When a component is executed, if you do not want to use the binary file in the TiUP mirror, you can add this option to specify using the binary file in a custom path.
+- Data type: `STRING`
+
+### --skip-version-check
+
+> **Note:**
+>
+> This option is deprecated since v1.3.0.
+
+- Skips the validity check for version numbers. By default, the specified version number can only be the semantic version.
+- Data type: `BOOLEAN`
+- This option is disabled by default and its default value is `false`. To enable this option, you can add this option to the command, and pass the `true` value or do not pass any value.
+
+### -T, --tag
+
+- Specifies a tag for the component to be started. Some components need to use disk storage during the execution, and TiUP allocates a temporary storage directory for this execution. If you want TiUP to allocate a fixed directory, you can use `-T/--tag` to specify the name of the directory, so that the same batch of files can be read and written in multiple executions with the same tag.
+- Data type: `STRING`
+
+### -v, --version
+
+Prints the TiUP version.
+
+### --help
+
+Prints the help information.
+
+## Command list
+
+TiUP has multiple commands, and these commands have multiple sub-commands. For the specific commands and their detailed descriptions, click the corresponding links in the list below:
+
+- [install](/tiup/tiup-command-install.md): Installs a component.
+- [list](/tiup/tiup-command-list.md): Shows the component list.
+- [uninstall](/tiup/tiup-command-uninstall.md): Uninstalls a component.
+- [update](/tiup/tiup-command-update.md): Updates the installed component.
+- [status](/tiup/tiup-command-status.md): Shows the running status of a component.
+- [clean](/tiup/tiup-command-clean.md): Cleans the data directory of a component.
+- [mirror](/tiup/tiup-command-mirror.md): Manages the mirror.
+- [telemetry](/tiup/tiup-command-telemetry.md): Enables or disables the telemetry.
+- [completion](/tiup/tiup-command-completion.md): Completes the TiUP command.
+- [env](/tiup/tiup-command-env.md): Shows the TiUP-related environment variables.
+- [help](/tiup/tiup-command-help.md): Shows the help information of a command or component.
+
+## Component list
+
+- [cluster](/tiup/tiup-component-cluster.md): Manages the TiDB cluster in a production environment.
+- [dm](/tiup/tiup-component-dm.md): Manages the TiDB Data Migration (DM) cluster in a production environment.
