diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 2b4c29deae..ac0849b06a 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -10,11 +10,11 @@ usage: dvc root [-h] [-q | -v] ## Description -This command returns the path to the root directory of the DVC -project, relative to the current working directory. It can be used to -build a path to a dependency, script, or data artifact, for -example. Useful when working in a subdirectory of the project, and needing to -refer to a file in another directory. +Returns the path to the root directory of the DVC project, relative +to the current working directory. Useful when working in a subdirectory of the +project, and you need to refer to a file in another directory. Use it in files +and commands to build a path to a dependency, script, or data +artifact. ## Options @@ -40,6 +40,9 @@ $ dvc root ## Example: Referencing files +Use `dvc root` to simplify file references when working in a subdirectory of a +DVC project. + ```dvc $ dvc root @@ -48,3 +51,61 @@ $ dvc root $ dvc run -d $(dvc root)/data/file.cvs ... \ python $(dvc root)/scripts/something.py ``` + +## Example: Output references + +Use `dvc root` to simplify output file or directory references. + +```dvc +$ dvc root + +../../../ + +$ dvc get -o $(dvc root)/root-model.pkl \ + https://github.com/iterative/example-get-started model.pkl +``` + +## Example: Other commands + +Use `dvc root` to simplify other commands when working in a DVC +project. + +```dvc +$ dvc root + +../.. + +$ tree $(dvc root)/data/ +../../data/ +├── data.xml +├── data.xml.dvc +... +└── prepared + ├── test.tsv + └── train.tsv +``` + +## Example: Build reusable paths + +Use `dvc root` to build reusable paths to dependencies, scripts, or data +artifacts from separate stages and subdirectories. + +```dvc +$ cd more_stages/ +$ dvc run -n process_data \ + -d data.in \ + -d $(dvc root)/process_data.py \ + -o result.out \ + python process_data.py data.in result.out +$ tree .. +. +├── dvc.yaml +├── dvc.lock +├── process_data.py +├── ... +└── more_stages/ + ├── data.in + ├── dvc.lock + ├── dvc.yaml + └── result.out +```