From 826019177d26594ab1d37ba5e33e4eaef7265cac Mon Sep 17 00:00:00 2001 From: Jeremy DesRoches Date: Wed, 29 Jul 2020 20:53:42 +0800 Subject: [PATCH 01/18] Clarifies motivation and description, adds relevant examples --- content/docs/command-reference/root.md | 75 ++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 5 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 2b4c29deae..ce7854ee5a 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -10,11 +10,15 @@ 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. +The `dvc root` command returns the path to the root directory of the DVC +project, relative to the current working directory. + +Using `dvc root`, you can build a path to a dependency, script, or data +artifact using `dvc run` from any subdirectory of a DVC +project. + +You can also use `dvc root` to simplify other commands when working in a +DVC project. ## Options @@ -40,6 +44,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 +55,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 +``` From ec653092345e6f31f36827cf00251a9f146370f7 Mon Sep 17 00:00:00 2001 From: Jeremy DesRoches Date: Thu, 30 Jul 2020 10:42:10 +0800 Subject: [PATCH 02/18] Returned to single paragraph, adjusts style to comments --- content/docs/command-reference/root.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index ce7854ee5a..e3fa0f5703 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -10,15 +10,7 @@ usage: dvc root [-h] [-q | -v] ## Description -The `dvc root` command returns the path to the root directory of the DVC -project, relative to the current working directory. - -Using `dvc root`, you can build a path to a dependency, script, or data -artifact using `dvc run` from any subdirectory of a DVC -project. - -You can also use `dvc root` to simplify other commands when working in a -DVC project. +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 From 844f2810db03889b7c8c99cf53b2a70f30ae7bfd Mon Sep 17 00:00:00 2001 From: Jeremy DesRoches Date: Thu, 30 Jul 2020 10:54:08 +0800 Subject: [PATCH 03/18] Returned to single paragraph, adjusts style to comments --- content/docs/command-reference/root.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index ce7854ee5a..ac0849b06a 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -10,15 +10,11 @@ usage: dvc root [-h] [-q | -v] ## Description -The `dvc root` command returns the path to the root directory of the DVC -project, relative to the current working directory. - -Using `dvc root`, you can build a path to a dependency, script, or data -artifact using `dvc run` from any subdirectory of a DVC -project. - -You can also use `dvc root` to simplify other commands when working in a -DVC project. +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 From 3fa33d5dda410c9c691df5cb8c24286e8947e103 Mon Sep 17 00:00:00 2001 From: Jeremy DesRoches Date: Thu, 30 Jul 2020 11:23:05 +0800 Subject: [PATCH 04/18] Fixes my merge mistake --- content/docs/command-reference/root.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 11dc8382c4..ac0849b06a 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -10,17 +10,11 @@ usage: dvc root [-h] [-q | -v] ## Description -<<<<<<< HEAD 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. ======= 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. - -> > > > > > > ec653092345e6f31f36827cf00251a9f146370f7 +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 From 7a630b5825189d269fefc83d6372e50992e27ea2 Mon Sep 17 00:00:00 2001 From: Jeremy DesRoches Date: Thu, 30 Jul 2020 11:53:01 +0800 Subject: [PATCH 05/18] Removes repeated references to dvc root from examples --- content/docs/command-reference/root.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index ac0849b06a..b6f97e3aa3 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -40,8 +40,8 @@ $ dvc root ## Example: Referencing files -Use `dvc root` to simplify file references when working in a subdirectory of a -DVC project. +Simplify file references when working in a subdirectory of a DVC +project. ```dvc $ dvc root @@ -54,7 +54,7 @@ $ dvc run -d $(dvc root)/data/file.cvs ... \ ## Example: Output references -Use `dvc root` to simplify output file or directory references. +Simplify output file or directory references. ```dvc $ dvc root @@ -67,8 +67,7 @@ $ dvc get -o $(dvc root)/root-model.pkl \ ## Example: Other commands -Use `dvc root` to simplify other commands when working in a DVC -project. +Simplify other commands when working in a DVC project. ```dvc $ dvc root @@ -87,8 +86,8 @@ $ tree $(dvc root)/data/ ## Example: Build reusable paths -Use `dvc root` to build reusable paths to dependencies, scripts, or data -artifacts from separate stages and subdirectories. +Build reusable paths to dependencies, scripts, or data artifacts +from separate stages and subdirectories. ```dvc $ cd more_stages/ From f0ef6e821b5fce596e9bd24a899bd8bbe7f88802 Mon Sep 17 00:00:00 2001 From: Jeremy DesRoches Date: Thu, 30 Jul 2020 14:36:43 +0800 Subject: [PATCH 06/18] Adds "root directory" to short intro --- content/docs/command-reference/root.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index b6f97e3aa3..62c649f02f 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 root of the DVC project. +Return the relative path to the root directory of the DVC project. ## Synopsis From 8952e4eeae7876ad0935212d9529b3295159963c Mon Sep 17 00:00:00 2001 From: Jeremy DesRoches Date: Thu, 30 Jul 2020 15:23:38 +0800 Subject: [PATCH 07/18] Adds command name and splits description to two paragraphs --- content/docs/command-reference/root.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 62c649f02f..4348e6d3d0 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -11,10 +11,11 @@ usage: dvc root [-h] [-q | -v] ## Description 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. +to the current working directory. Useful for referencing a file in another +directory when working in a subdirectory of the project. + +Use `dvc root` to build reusable paths to dependencies, scripts, or data +artifacts. ## Options From 8bd6c6127e460324ac1255f4a6427504a85d7206 Mon Sep 17 00:00:00 2001 From: Jeremy DesRoches Date: Thu, 30 Jul 2020 15:32:30 +0800 Subject: [PATCH 08/18] removes extra spacing from examples --- content/docs/command-reference/root.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 4348e6d3d0..f36abcfcc8 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -30,12 +30,10 @@ artifacts. ```dvc $ dvc root - . $ cd subdir $ dvc root - .. ``` @@ -46,7 +44,6 @@ project. ```dvc $ dvc root - ../../../ $ dvc run -d $(dvc root)/data/file.cvs ... \ @@ -59,7 +56,6 @@ Simplify output file or directory references. ```dvc $ dvc root - ../../../ $ dvc get -o $(dvc root)/root-model.pkl \ @@ -72,7 +68,6 @@ Simplify other commands when working in a DVC project. ```dvc $ dvc root - ../.. $ tree $(dvc root)/data/ @@ -97,6 +92,7 @@ $ dvc run -n process_data \ -d $(dvc root)/process_data.py \ -o result.out \ python process_data.py data.in result.out + $ tree .. . ├── dvc.yaml From 6dc5f64c30f607fdcc2a44b1647a846701bd0490 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Thu, 30 Jul 2020 11:00:45 -0500 Subject: [PATCH 09/18] Update content/docs/command-reference/root.md --- content/docs/command-reference/root.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index f36abcfcc8..81c5c22468 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -11,8 +11,8 @@ usage: dvc root [-h] [-q | -v] ## Description Returns the path to the root directory of the DVC project, relative -to the current working directory. Useful for referencing a file in another -directory when working in a subdirectory of the project. +to the current working directory. `dvc root` is useful for referencing a file +in another directory when working in a subdirectory of the project. Use `dvc root` to build reusable paths to dependencies, scripts, or data artifacts. From 24d5ed8262384bf988771741f96a273e12a90e6a Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Thu, 30 Jul 2020 11:01:29 -0500 Subject: [PATCH 10/18] Update content/docs/command-reference/root.md --- content/docs/command-reference/root.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 81c5c22468..4f98c07770 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -14,8 +14,8 @@ Returns the path to the root directory of the DVC project, relative to the current working directory. `dvc root` is useful for referencing a file in another directory when working in a subdirectory of the project. -Use `dvc root` to build reusable paths to dependencies, scripts, or data -artifacts. +Use this command to build reusable paths to dependencies, scripts, or +data artifacts. ## Options From 8474156d9f69decbf51fc8b1876193a1cbed8b0f Mon Sep 17 00:00:00 2001 From: jeremydesroches <18587991+jeremydesroches@users.noreply.github.com> Date: Fri, 31 Jul 2020 10:44:53 +0800 Subject: [PATCH 11/18] Update content/docs/command-reference/root.md Co-authored-by: Jorge Orpinel --- content/docs/command-reference/root.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 4f98c07770..34b0395980 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -37,7 +37,7 @@ $ dvc root .. ``` -## Example: Referencing files +## Example: Referencing fixed paths for `dvc run` Simplify file references when working in a subdirectory of a DVC project. From 9c82fc86599fe28f525ae0cb82f7d78545c38e0f Mon Sep 17 00:00:00 2001 From: Jeremy DesRoches Date: Fri, 31 Jul 2020 12:13:13 +0800 Subject: [PATCH 12/18] Removes extra examples, updates example titles and descriptions --- content/docs/command-reference/root.md | 54 +++++--------------------- 1 file changed, 9 insertions(+), 45 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 34b0395980..51630a889b 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -11,10 +11,10 @@ usage: dvc root [-h] [-q | -v] ## Description Returns the path to the root directory of the DVC project, relative -to the current working directory. `dvc root` is useful for referencing a file -in another directory when working in a subdirectory of the project. +to the current working directory. `dvc root` is useful for referencing a file in +another directory when working in a subdirectory of the project. -Use this command to build reusable paths to dependencies, scripts, or +Use this command to build scripts using fixed paths to dependencies, files, or data artifacts. ## Options @@ -32,6 +32,7 @@ Use this command to build reusable paths to dependencies, scripts, or $ dvc root . +$ mkdir subdir $ cd subdir $ dvc root .. @@ -39,8 +40,8 @@ $ dvc root ## Example: Referencing fixed paths for `dvc run` -Simplify file references when working in a subdirectory of a DVC -project. +When working in a subdirectory of a DVC project, simplify file +references by making all paths relative to the root directory. ```dvc $ dvc root @@ -50,21 +51,10 @@ $ dvc run -d $(dvc root)/data/file.cvs ... \ python $(dvc root)/scripts/something.py ``` -## Example: Output references +## Example: Referencing fixed paths for other commands -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 - -Simplify other commands when working in a DVC project. +When working in a subdirectory of a DVC project, simplify file +references in other commands by using paths relative to the root directory. ```dvc $ dvc root @@ -79,29 +69,3 @@ $ tree $(dvc root)/data/ ├── test.tsv └── train.tsv ``` - -## Example: Build reusable paths - -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 -``` From b05473bd97ac6348d1b8d3a09927bb480332d38f Mon Sep 17 00:00:00 2001 From: Jeremy DesRoches Date: Fri, 31 Jul 2020 13:00:11 +0800 Subject: [PATCH 13/18] Updates description to expand scripting use case --- content/docs/command-reference/root.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 51630a889b..2e712d4293 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -14,8 +14,9 @@ Returns the path to the root directory of the DVC project, relative to the current working directory. `dvc root` is useful for referencing a file in another directory when working in a subdirectory of the project. -Use this command to build scripts using fixed paths to dependencies, files, or -data artifacts. +Use this command to build fixed paths to dependencies, files, or data +artifacts. Useful when creating shell scripts that generate `dvc.yaml` +files programmatically or with the `dvc run` helper. ## Options From f00550740a6a97706980d2d2bfe45fdb07cca1e6 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Fri, 31 Jul 2020 00:23:12 -0500 Subject: [PATCH 14/18] Update content/docs/command-reference/root.md --- content/docs/command-reference/root.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 2e712d4293..9842683a51 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -39,7 +39,7 @@ $ dvc root .. ``` -## Example: Referencing fixed paths for `dvc run` +## Example: Referencing fixed paths in other commands When working in a subdirectory of a DVC project, simplify file references by making all paths relative to the root directory. From f8b08e612bbf3fc2a74c299a588336b59660dc60 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Fri, 31 Jul 2020 00:30:56 -0500 Subject: [PATCH 15/18] Update content/docs/command-reference/root.md --- content/docs/command-reference/root.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 9842683a51..6cfbdc61e3 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -32,7 +32,6 @@ files programmatically or with the `dvc run` helper. ```dvc $ dvc root . - $ mkdir subdir $ cd subdir $ dvc root From a7d0f2780287b7fa48482171b39366682f96f178 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Fri, 31 Jul 2020 00:35:00 -0500 Subject: [PATCH 16/18] Update content/docs/command-reference/root.md --- content/docs/command-reference/root.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index 6cfbdc61e3..d6cbbce2b8 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -65,7 +65,4 @@ $ tree $(dvc root)/data/ ├── data.xml ├── data.xml.dvc ... -└── prepared - ├── test.tsv - └── train.tsv ``` From 070cf40d5be0a2bf5f997e25533a02f9c3d6a06f Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Fri, 31 Jul 2020 00:39:17 -0500 Subject: [PATCH 17/18] Update content/docs/command-reference/root.md --- content/docs/command-reference/root.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index d6cbbce2b8..f3810dbf06 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -51,10 +51,7 @@ $ dvc run -d $(dvc root)/data/file.cvs ... \ python $(dvc root)/scripts/something.py ``` -## Example: Referencing fixed paths for other commands - -When working in a subdirectory of a DVC project, simplify file -references in other commands by using paths relative to the root directory. +The same can be applied to non-DVC commands: ```dvc $ dvc root From 949682279572c31b17188f6932b28c12b6168c9e Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Fri, 31 Jul 2020 00:39:27 -0500 Subject: [PATCH 18/18] Update content/docs/command-reference/root.md --- content/docs/command-reference/root.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/command-reference/root.md b/content/docs/command-reference/root.md index f3810dbf06..f36cddce61 100644 --- a/content/docs/command-reference/root.md +++ b/content/docs/command-reference/root.md @@ -15,8 +15,8 @@ to the current working directory. `dvc root` is useful for referencing a file in another directory when working in a subdirectory of the project. Use this command to build fixed paths to dependencies, files, or data -artifacts. Useful when creating shell scripts that generate `dvc.yaml` -files programmatically or with the `dvc run` helper. +artifacts. This is useful when creating shell scripts that generate +`dvc.yaml` files programmatically or with the `dvc run` helper. ## Options