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.

Sign up for GitHub

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

docs: rewrite show section as two separate modes for clarity #9752

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: rewrite show section as two separate modes for clarity #9752

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
49 changes: 30 additions & 19 deletions docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -494,13 +494,39 @@ about dependency groups.

## show

To list all the available packages, you can use the `show` command.
This command provides details of packages, or a single package, specified in the lock file.

### Packages:

```bash
poetry show

build 1.2.2 A simple, correct Python build frontend
cachecontrol 0.14.0 httplib2 caching for requests
certifi 2024.7.4 Python package for providing Mozilla's CA Bundle.
cffi 1.16.0 Foreign Function Interface for Python calling C code.
cfgv 3.4.0 Validate configuration and produce human readable error messages.
```

If you want to see the details of a certain package, you can pass the package name.
If the terminal supports coloured text, packages that aren't installed are shown with their names in red.

If the terminal doesn't support coloured text, packages that aren't installed are shown with their version prefixed
with `(!)`.
Copy link

Choose a reason for hiding this comment

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

Suggested change
with `(!)`.
with `(!)`.


#### Options

* `--with`: Dependency groups to include.
* `--without`: Dependency groups to ignore.
* `--only`: Only show packages in specified dependency groups. If used, `--with` and `--without` options are ignored.
* `--all (-a)`: Show all packages (even those not compatible with current system).
* `--top-level (-T)`: Only show explicitly defined packages.
* `--no-dev`: Do not list dev dependencies. (**Deprecated**, use `--only main` or `--without dev` instead)
* `--latest (-l)`: Adds a column with the latest version.
* `--outdated (-o)`: Adds a column with the latest version, but only for packages that are outdated.
* `--why`: Adds a column indicating if the package is required by other packages. Not compatible with `--tree`.
* `--tree`: Show packages as a dependency tree. Not compatible with `--why`.

### Single package:

```bash
poetry show pendulum
Expand All @@ -517,24 +543,9 @@ dependencies
required by
- calendar >=1.4.0
```
#### Options

### Options

* `--without`: The dependency groups to ignore.
* `--why`: When showing the full list, or a `--tree` for a single package, display whether they are a direct dependency or required by other packages.
* `--with`: The optional dependency groups to include.
* `--only`: The only dependency groups to include.
* `--no-dev`: Do not list the dev dependencies. (**Deprecated**, use `--only main` or `--without dev` instead)
* `--tree`: List the dependencies as a tree.
* `--latest (-l)`: Show the latest version.
* `--outdated (-o)`: Show the latest version but only for packages that are outdated.
* `--all (-a)`: Show all packages (even those not compatible with current system).
* `--top-level (-T)`: Only show explicitly defined packages.

{{% note %}}
When `--only` is specified, `--with` and `--without` options are ignored.
{{% /note %}}

* `--tree --why`: Show package in a dependency tree, and indicate whether a direct dependency or required by other

## build

Expand Down