diff --git a/content/docs/command-reference/gc.md b/content/docs/command-reference/gc.md index e0a275608c..82895a6ea5 100644 --- a/content/docs/command-reference/gc.md +++ b/content/docs/command-reference/gc.md @@ -22,11 +22,11 @@ files if no scope options are provided. It means it's user's responsibility to explicitly provide the right set of options to specify what data is still needed (so that DVC can figure out what fils can be safely deleted). -One of the scope options, `--workspace`, `--all-branches`, `--all-tags`, -`--all-commits`, or any combination of them must be provided. Each of them -corresponds to the current workspace _and_ a set of commits to analyze what -files, directories and what versions are still needed and should be kept (by -analyzing DVC-files in those commits). +One of the scope options (`--workspace`, `--all-branches`, `--all-tags`, +`--all-commits`) or a combination of them must be provided. Each of them +corresponds to keeping the data for the current workspace, and for a certain set +of commits (determined by reading the DVC-files in them). See the +[Options](#options) section for more details. Unless the `--cloud` option is used, `dvc gc` does not remove data files from any remote. This means that any files collected from the local cache can be @@ -61,10 +61,11 @@ The default remote is cleaned (see `dvc config core.remote`) unless the commits as well as the workspace (implies `-w`). Useful for keeping all the data used in the entire existing commit history of the project. - One of the use cases for this option is to safely delete all temporary data - DVC cached when `dvc run` and/or `dvc repro` were run without committing - changes to DVC-files (thus potentially caching data that is not referenced - from workspace or Git commits). + A use case for this option is to safely delete all temporary data `dvc run` + and/or `dvc repro` cache when used without committing changes (see the `-O` or + `-M`, and `--no-commit` options in those commands). In that scenario, data + that is never referenced from the workspace or from any Git commit can still + be stored in the project's cache). - `-p `, `--projects ` - if a single remote or a single cache is shared among different projects (e.g. a configuration like the one described diff --git a/content/docs/command-reference/install.md b/content/docs/command-reference/install.md index 2898e6823f..c0ebcf2b9a 100644 --- a/content/docs/command-reference/install.md +++ b/content/docs/command-reference/install.md @@ -75,11 +75,11 @@ directory: To disable them, you need to **remove** or **edit** those files (i.e. `rm .git/hooks/post-checkout`, `vim .git/hooks/pre-commit`). -## Using Pre-Commit tool +## Using the Pre-commit tool -DVC provides support for [pre-commit](https://pre-commit.com/) users. To adjust -`.pre-commit-config.yaml` you could either use -`dvc install --use-pre-commit-tool`, or add these entries by hand: +DVC provides support to manage Git hooks with +[pre-commit](https://pre-commit.com/). To adjust `.pre-commit-config.yaml`, you +can either use `dvc install --use-pre-commit-tool` or add these entries by hand: ```yaml repos: @@ -103,8 +103,9 @@ repos: ## Options -- `--use-pre-commit-tool` - install pre-commit/pre-push/post-checkout hooks into - the [pre-commit](https://pre-commit.com/) config (`.pre-commit-config.yaml`). +- `--use-pre-commit-tool` - installs pre-commit, pre-push, post-checkout Git + hooks into the [pre-commit](https://pre-commit.com/) config file + (`.pre-commit-config.yaml`). - `-h`, `--help` - prints the usage/help message, and exit. diff --git a/content/docs/command-reference/metrics/add.md b/content/docs/command-reference/metrics/add.md index 1d746bbd86..cd2a3d790c 100644 --- a/content/docs/command-reference/metrics/add.md +++ b/content/docs/command-reference/metrics/add.md @@ -1,7 +1,6 @@ # metrics add -Mark output file as a -[project metric](/doc/command-reference/metrics). +Mark a DVC-tracked file as a [project metric](/doc/command-reference/metrics). ## Synopsis diff --git a/content/docs/command-reference/metrics/remove.md b/content/docs/command-reference/metrics/remove.md index bbb6f77e95..c40a87182f 100644 --- a/content/docs/command-reference/metrics/remove.md +++ b/content/docs/command-reference/metrics/remove.md @@ -1,8 +1,8 @@ # metrics remove -Stop tracking a [project metric](/doc/command-reference/metrics): Keeps file -located at `path` as an output, but removes its metric mark in the -DVC-file. +Remove metric mark on a DVC-tracked file: Keeps file located at `path` as an +output, but removes its mark as a +[project metric](/doc/command-reference/metrics) in the DVC-file. ## Synopsis diff --git a/content/docs/command-reference/remove.md b/content/docs/command-reference/remove.md index f35498dcba..db63ae521f 100644 --- a/content/docs/command-reference/remove.md +++ b/content/docs/command-reference/remove.md @@ -1,6 +1,6 @@ # remove -Remove data files or directories tracked by DVC. +Remove DVC-tracked files or directories from the workspace. ## Synopsis diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 04454a16ac..6cbce836c3 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -1,6 +1,6 @@ # root -Return the relative path to the DVC project. +Return the relative path to the root of the DVC project. ## Synopsis @@ -11,9 +11,10 @@ usage: dvc root [-h] [-q | -v] ## Description While in sub-directories of the project, sometimes developers may want to refer -some file belonging to another directory. This command returns relative path to -the project root from the current working directory. So this command can be used -to build a path to a dependency file, command, or output. +some file belonging to another directory. This command returns the path to the +root directory of the current DVC project, relative to the current +working directory. This command can be used to build a path to a dependency +file, command, or output. ## Options diff --git a/content/docs/install/linux.md b/content/docs/install/linux.md index 5b5ab6c22d..719c62507c 100644 --- a/content/docs/install/linux.md +++ b/content/docs/install/linux.md @@ -29,7 +29,7 @@ plan to use, you might need to install optional dependencies: `[s3]`, `[azure]`, ### Example: How to install DVC with support for Amazon S3 storage ```dvc -$ pip install 'dvc[s3]' +$ pip install "dvc[s3]" ``` In this case it installs `boto3` library as well, besides DVC. diff --git a/content/docs/install/macos.md b/content/docs/install/macos.md index 3a231e4647..ebebf0ee62 100644 --- a/content/docs/install/macos.md +++ b/content/docs/install/macos.md @@ -47,7 +47,7 @@ plan to use, you might need to install optional dependencies: `[s3]`, `[azure]`, ### Example: How to install DVC with support for Amazon S3 storage ```dvc -$ pip install 'dvc[s3]' +$ pip install "dvc[s3]" ``` In this case it installs `boto3` library as well, besides DVC. diff --git a/content/docs/install/windows.md b/content/docs/install/windows.md index cc2e78e4fe..0812719763 100644 --- a/content/docs/install/windows.md +++ b/content/docs/install/windows.md @@ -26,7 +26,7 @@ on GitHub. You can use `conda` from [Anaconda Prompt](https://docs.anaconda.com/anaconda/user-guide/getting-started/#open-prompt-win), -which is a POSIX-like command line terminal in Windows. +a POSIX-like command line terminal in Windows. ```dvc $ conda install -c conda-forge dvc @@ -36,9 +36,8 @@ $ conda install -c conda-forge dvc ## Install with pip -You can install with `pip` from a command line terminal like -[Git Bash](https://gitforwindows.org/#bash) or -[WSL](https://blogs.windows.com/windowsdeveloper/2016/03/30/run-bash-on-ubuntu-on-windows/). +From Command Prompt or other +[recommended consoles](/doc/user-guide/running-dvc-on-windows): ```dvc $ pip install dvc @@ -53,7 +52,7 @@ plan to use, you might need to install optional dependencies: `[s3]`, `[azure]`, ### Example: How to install DVC with support for Amazon S3 storage ```dvc -$ pip install 'dvc[s3]' +$ pip install "dvc[s3]" ``` In this case it installs `boto3` library as well, besides DVC. diff --git a/content/docs/user-guide/contributing/docs.md b/content/docs/user-guide/contributing/docs.md index 49f43a5239..3d166ca14f 100644 --- a/content/docs/user-guide/contributing/docs.md +++ b/content/docs/user-guide/contributing/docs.md @@ -62,8 +62,8 @@ $ git clone git@github.com:/dvc.org.git $ cd dvc.org ``` -Make sure you have the latest version of [Node.js](https://nodejs.org/en/), and -install [Yarn](https://yarnpkg.com/): +Make sure you have a recent version of [Node.js](https://nodejs.org/en/) +(`^12.0.0`), and install [Yarn](https://yarnpkg.com/): ```dvc $ npm install -g yarn @@ -118,7 +118,7 @@ The first few of the rules below should be enforced automatically by a Git pre-commit hook that is integrated when `yarn` installs the project dependencies (explained above). -- No trailing whitespaces are allowed. +- No trailing white spaces are allowed. - Content must be properly formatted at 80 symbols width. diff --git a/content/docs/user-guide/running-dvc-on-windows.md b/content/docs/user-guide/running-dvc-on-windows.md index 5fbd6245cd..ba09225775 100644 --- a/content/docs/user-guide/running-dvc-on-windows.md +++ b/content/docs/user-guide/running-dvc-on-windows.md @@ -5,22 +5,28 @@ involving system performance. Some, for example, have to do with NTFS file system characteristics and Windows built-in security mechanisms. Below are some workarounds that can help avoid these potential problems: -## POSIX-like command line shell - -Many of the DVC commands have POSIX-style options that are given with a double -dash `--`. This isn't supported by the simple Windows command prompt `cmd`. - -Common Windows terminal alternatives are -[Git Bash](https://gitforwindows.org/#bash) or -[Anaconda Prompt](https://docs.anaconda.com/anaconda/user-guide/getting-started/#open-prompt-win) -– but they may not support all the POSIX features (e.g. `\` line continuation). - -💡 We recommend the full [Cmder](https://cmder.net/) console emulator (which -already includes _Git for Windows_). - -Its also possible to enjoy a full Linux terminal experience with the -[WSL](https://blogs.windows.com/windowsdeveloper/2016/03/30/run-bash-on-ubuntu-on-windows/) -– but it may not be possible to access GPUs from this subsystem. +## POSIX-like command line experience + +The regular Command Prompt (`cmd`) in Windows will most likely not help you use +DVC effectively, or follow the examples in our docs. Please avoid it. There's no +perfect solution, bu here are some ideas: + +- The full [Cmder](https://cmder.net/) console emulator combines several useful + tools like [ConEmu](https://conemu.github.io/), and + [Git for Windows](https://gitforwindows.org/)\* (Git Bash) among other + [shell options](https://github.com/cmderdev/cmder/blob/master/README.md#access-to-multiple-shells-in-one-window-using-tabs). +- [Anaconda Prompt](https://docs.anaconda.com/anaconda/user-guide/getting-started/#open-prompt-win) + is another recommendation, but it may not support all the desired CLI features + (e.g. `\` line continuation). +- Consider enabling and using + [WSL](https://blogs.windows.com/windowsdeveloper/2016/03/30/run-bash-on-ubuntu-on-windows/) + ([Windows Terminal](https://devblogs.microsoft.com/commandline/) also + recommended). But it has major + [I/O performance issues](https://www.phoronix.com/scan.php?page=article&item=windows10-okt-wsl&num=2) + and is [unable to access GPUs](https://github.com/Microsoft/WSL/issues/829), + et al.\* +- Install an actual Linux distro (e.g. Ubuntu) on a virtual machine, or in a HD + partition (dual boot). ## Disable short-file name generation @@ -65,6 +71,6 @@ via [Chocolatey](https://chocolatey.org/) (please install the tool first): $ choco install less ``` -`less` can be installed in other ways, just make sure it's available in -`cmd`/PowerShell, where you run `dvc`. (This usually means adding the directory -where `less` is installed to the `PATH` environment variable.) +`less` can be installed in other ways, just make sure it's available in the +command line environment where you run `dvc`. (This usually means adding the +directory where `less` is installed to the `PATH` environment variable.)