Merge branch 'master' into dvc.yaml/params AND small fixes in DVC FIl…

…es guide

content/docs/command-reference/config.md

@@ -38,18 +38,21 @@ instead, to set (or override) secrets:
 The `--global` and `--system` flags are also available to set config options for
 multiple projects and users, respectively:
 
-| Flag       | Priority | Mac location                             | Linux location             | Windows location                                          |
-| ---------- | -------- | ---------------------------------------- | -------------------------- | --------------------------------------------------------- |
-| `--global` | 3        | `$HOME/Library/Application\ Support/dvc` | `$HOME/.config/dvc/config` | `%LocalAppData%\iterative\dvc\config`                     |
-| `--system` | 4        | `/Library/Application\ Support/dvc`      | `/etc/dvc/config`          | `%AllUsersProfile%\Application Data\iterative\dvc\config` |
-
-<!-- Avoids new lines in the Flag column (above). -->
+<!-- Avoids new lines in the Flag columns (below). -->
 <style>
   #markdown-root td:first-child code {
     white-space: nowrap;
   }
 </style>
 
+| Flag       | Priority | Mac location                           | Linux location (typical\*) | Windows location                                          |
+| ---------- | -------- | -------------------------------------- | -------------------------- | --------------------------------------------------------- |
+| `--global` | 3        | `$HOME/Library/Preferences/dvc/config` | `$HOME/.config/dvc/config` | `%LocalAppData%\iterative\dvc\config`                     |
+| `--system` | 4        | `/Library/Preferences/dvc/config`      | `/etc/xdg/dvc/config`      | `%AllUsersProfile%\Application Data\iterative\dvc\config` |
+
+> \* For Linux, the global `dvc/config` may be found in `$XDG_CONFIG_HOME`, and
+> the system-wide one in `$XDG_CONFIG_DIRS[0]`, if those env vars are defined.
+
 ## Command options (flags)
 
 - `-u`, `--unset` - remove a specified config option from a config file.
@@ -64,7 +67,8 @@ multiple projects and users, respectively:
 
 - `--system` - modify a system config file (e.g. `/etc/dvc/config`) instead of
   `.dvc/config`. Useful to apply config options to all the projects (all users)
-  in the machine.
+  in the machine. May require superuser access e.g.
+  `sudo dvc config --system ...` (Linux).
 
 - `-l`, `--list` - lists all defined config values.
 

content/docs/command-reference/import.md

@@ -10,7 +10,7 @@ the import.
 ## Synopsis
 
 ```usage
-usage: dvc import [-h] [-q | -v]
+usage: dvc import [-h] [-q | -v] [-j <number>]
                   [-o <path>] [--file <filename>]
                   [--rev <commit>] [--no-exec] [--desc <text>]
                   url path
@@ -110,6 +110,12 @@ repo at `url`) are not supported.
   data already exist locally and you want to "DVCfy" this state of the project
   (see also `dvc commit`).
 
+- `-j <number>`, `--jobs <number>` - number of threads to run simultaneously to
+  handle the downloading of files from the remote. The default value is
+  `4 * cpu_count()`. For SSH remotes, the default is just `4`. Using more jobs
+  may improve the total download speed if a combination of small and large files
+  are being fetched.
+
 - `--desc <text>` - user description of the data (optional). This doesn't affect
   any DVC operations.
 

content/docs/user-guide/dvc-files.md

@@ -1,6 +1,6 @@
-# DVC File Formats
+# DVC Files
 
-There are a few special files that enable DVC's features:
+There are a few special DVC file formats that enable its features:
 
 - Files ending with the `.dvc` extension are placeholders to track data files
   and directories. A <abbr>DVC project</abbr> usually has one `.dvc` file per
@@ -15,8 +15,8 @@ Both `.dvc` files and `dvc.yaml` use human-friendly YAML 1.2 schemas, described
 below. We encourage you to get familiar with them so you may create, generate,
 and edit them on your own.
 
-Both the internal directory and these "metafiles" should be versioned with Git
-(in Git-enabled <abbr>repositories</abbr>).
+These metafiles should be versioned with Git (in Git-enabled
+<abbr>repositories</abbr>).
 
 > See also [`.dvcignore`](/doc/user-guide/dvcignore).
 
@@ -70,6 +70,9 @@ An _output entry_ (`outs`) can have these fields:
   and a special _checksum_ for HDFS and WebHDFS.
 - `size`: Size of the file or directory (sum of all files).
 - `nfiles`: If a directory, number of files inside.
+- `isexec`: Whether this is an executable file. DVC preserves execute
+  permissions upon `dvc checkout` and `dvc pull`. This has no effect on
+  directories, or in general on Windows.
 - `cache`: Whether or not this file or directory is <abbr>cached</abbr> (`true`
   by default, if not present). See the `--no-commit` option of `dvc add`.
 - `persist`: Whether the output file/dir should remain in place while