Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs about pager in the pipeline command #831

Merged
merged 18 commits into from Dec 11, 2019
Merged
Show file tree
Hide file tree
Changes from 16 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 31 additions & 4 deletions static/docs/command-reference/pipeline/show.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,9 @@ instead of stages.
option is specified) of stage outputs instead of paths to DVC-files.

- `--ascii` - visualize pipeline. It will print a graph (ASCII) instead of a
This conversation was marked as resolved.
Show resolved Hide resolved
list of path to DVC-files. (To navigate, use arrows or `W`, `A`, `S`, `D`
keys. To exit, press `Q`.)
list of path to DVC-files. (`less` pager may be used, see
[this section](/doc/command-reference/pipeline/show#paging-the-output) for
This conversation was marked as resolved.
Show resolved Hide resolved
details).

- `--dot` - show contents of `.dot` files with a DVC pipeline graph. It can be
passed to third party visualization utilities.
Expand All @@ -52,6 +53,33 @@ instead of stages.

- `-v`, `--verbose` - displays detailed tracing information.

## Paging the output

This command's output is automatically piped to
[`less`](<https://en.wikipedia.org/wiki/Less_(Unix)>), if available in the
This conversation was marked as resolved.
Show resolved Hide resolved
terminal. (The exact command used is `less --chop-long-lines --clear-screen`.)
If less is not available (e.g. on Windows), the output is simply printed out.
This conversation was marked as resolved.
Show resolved Hide resolved

> It's also possible to
> [enable Less paging on Windows](/doc/user-guide/running-dvc-on-windows#enabling-paging-with-less).
jorgeorpinel marked this conversation as resolved.
Show resolved Hide resolved

### Providing a custom pager

It's possible to override the default pager via the `DVC_PAGER` environment
variable. For example, the following command will replace the default pager with
[`more`](<https://en.wikipedia.org/wiki/More_(command)>), for a single run:

```bash
$ DVC_PAGER=more dvc pipeline show --ascii my-pipeline.dvc
```
This conversation was marked as resolved.
Show resolved Hide resolved

For a persistent change, define `DVC_PAGER` in the shell configuration. For
example in Bash, we could add the following line to `~/.bashrc`:

```bash
export DVC_PAGER=more
```

## Examples

Default mode: show stage files that `output.dvc` recursively depends on:
Expand All @@ -72,8 +100,7 @@ cleanup.py raw data
process.py data output
```

Visualize DVC pipeline (To navigate, use arrows or `W`, `A`, `S`, `D` keys. To
exit, press `Q`.):
Visualize DVC pipeline:

```dvc
$ dvc pipeline show eval.txt.dvc --ascii
Expand Down
17 changes: 17 additions & 0 deletions static/docs/user-guide/running-dvc-on-windows.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,3 +47,20 @@ The performance of NTFS degrades while handling large volumes of files in a
directory.
[Here](https://stackoverflow.com/questions/197162/ntfs-performance-and-large-volumes-of-files-and-directories)
is the resource for reference.

## Enabling paging with `less`

By default, DVC tries to use
[`Less`](<https://en.wikipedia.org/wiki/Less_(Unix)>) as pager for the output of
This conversation was marked as resolved.
Show resolved Hide resolved
`dvc pipeline show`. Windows doesn't have the less command available however.
Fortunately, there is a easy way of installing `less` via
[Chocolatey](https://chocolatey.org/) (please install the tool first):

```dvc
$ choco install less
```

If you do not want to use [Chocolatey](https://chocolatey.org/) for some reason,
you can still provide `less` by your own way. However, you must make `less` to
be runnable from `cmd`/`Powershell`. This usually means to add the `less`
installation directory to the `PATH` environment variable.
This conversation was marked as resolved.
Show resolved Hide resolved