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 all 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
34 changes: 30 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,8 @@ 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
[Paging the output](#paging-the-output) below for 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 +52,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
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.

> 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 +99,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
15 changes: 15 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,18 @@ 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 `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
```

`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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`cmd`/Powershell, where you run dvc. (This usually means adding the directory
`cmd`/Powershell, where you run `dvc`. (This usually means adding the directory

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually I can commit this 🙂 One min...

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah no, sorry. I don't have permission to push to your fork. Please image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(p.s. FYI you can allow upstream repo maintainers to push to the branch in the PR settings.)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jorgeorpinel let's merge and fix it in-place? :) it's too minor to do a cycle.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

True, I can definitely do that!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 9955833.

where `less` is installed to the `PATH` environment variable.)