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

[CI:DOCS] Update podman.1.md, image-(diff, mount, exists) & images #10536

Closed
wants to merge 1 commit into from
+318 −155
Closed

[CI:DOCS] Update podman.1.md, image-(diff, mount, exists) & images #10536

Show file tree
Hide file tree
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
27 changes: 22 additions & 5 deletions docs/source/markdown/podman-image-diff.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,45 @@
% podman-image-diff(1)

## NAME

podman-image-diff - Inspect changes on an image's filesystem

## SYNOPSIS

Copy link
Member

Choose a reason for hiding this comment

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

I think our validate script does not allow an extra newline after the heading.

Copy link
Contributor

Choose a reason for hiding this comment

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

It does work, but for the uniformity of all manpages I'll specify in the MANPAGE_SYNTAX, that there shouldn't be a new line.

Copy link
Author

Choose a reason for hiding this comment

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

@Procyhon I am using markdownlint, which is a vscode extension and they suggest using a new line https://github.com/DavidAnson/markdownlint/blob/v0.23.1/doc/Rules.md#md022
I think it just makes the markdown source code more readable

Copy link
Author

Choose a reason for hiding this comment

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

But let me know what is the final verdict on this

**podman image diff** [*options*] *name*

## DESCRIPTION
Displays changes on a container or image's filesystem. The container or image will be compared to its parent layer

**podman image diff** displays changes on an image's filesystem. The image will be compared to its parent layer.

The output is prefixed with the following symbols:

| Symbol | Description |
|--------|-------------|
| A | A file or directory was added. |
| D | A file or directory was deleted. |
| C | A file or directory was changed. |

## OPTIONS

#### **--format**
#### **--format**, **-f**=*format*
Copy link
Member

Choose a reason for hiding this comment

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

-f is not valid for image diff

$ podman image diff -f json alpine
Error: unknown shorthand flag: 'f' in -f


Alter the output into a different format. The only valid format for diff is `json`.
Alter the output into a different format. The only valid format for diff is `JSON`.
Copy link
Member

Choose a reason for hiding this comment

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

JSON should be lowercase. The uppercase one throws an error.

Copy link
Member

Choose a reason for hiding this comment

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

Where is the error coming from on JSON vs json? We need to stop that error, JSON is the correct capitalization.

Copy link
Author

Choose a reason for hiding this comment

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

It has to be fixed in containers/common https://github.com/containers/common/blob/6c933f226ed44491d082d6d52cbe31ae6fe0e76f/pkg/report/validate.go#L5 where it should be probably (json|JSON)


## EXAMPLE

- Diff of two different python images.
Copy link
Member

Choose a reason for hiding this comment

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

podman image diff will accept only one argument so the examples are wrong.


```
# podman diff redis:old redis:alpine
# podman diff python:latest python:alpine
C /usr
C /usr/local
C /usr/local/bin
A /usr/local/bin/docker-entrypoint.sh
```

- `JSON` formatted diff of two different redis images. The returned `JSON` object contains arrays specifying changes in the filesystem.

```
# podman diff --format json redis:old redis:alpine
{
Expand All @@ -40,7 +55,9 @@ A /usr/local/bin/docker-entrypoint.sh
```

## SEE ALSO
podman(1)

**[podman(1)](podman.1.md)**
infiniteregrets marked this conversation as resolved.
Show resolved Hide resolved

## HISTORY

August 2017, Originally compiled by Ryan Cole <[email protected]>
34 changes: 22 additions & 12 deletions docs/source/markdown/podman-image-exists.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,53 @@
% podman-image-exists(1)

## NAME

podman-image-exists - Check if an image exists in local storage

## SYNOPSIS
**podman image exists** *image*

**podman image exists** [*options*] *name*

## DESCRIPTION
**podman image exists** checks if an image exists in local storage. The **ID** or **Name**
of the image may be used as input. Podman will return an exit code
of `0` when the image is found. A `1` will be returned otherwise. An exit code of `125` indicates there
was an issue accessing the local storage.

**podman image exists** checks if an image exists in local storage. The *ID* or *name* of the image may be used as input.

Podman will return the following exit codes:

| Exit Code | Description |
|-----------|-------------|
| 0 | Image found. |
| 1 | Image not found. |
| 125 | Could not access local storage. |

## OPTIONS

#### **--help**, **-h**

Print usage statement
Print usage statement.

## EXAMPLES

Check if an image called `webclient` exists in local storage (the image does actually exist).
- Check if an image called `webclient` exists in local storage (the image does actually exist).

```
$ podman image exists webclient
$ echo $?
0
$
```

Check if an image called `webbackend` exists in local storage (the image does not actually exist).
- Check if an image called `webbackend` exists in local storage (the image does not actually exist).

```
$ podman image exists webbackend
$ echo $?
1
$
```

## SEE ALSO
podman(1)

**[podman(1)](podman.1.md)**

## HISTORY
November 2018, Originally compiled by Brent Baude (bbaude at redhat dot com)

November 2018, Originally compiled by Brent Baude <[email protected]>
42 changes: 28 additions & 14 deletions docs/source/markdown/podman-image-mount.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,28 @@
% podman-image-mount(1)

## NAME

podman\-image\-mount - Mount an image's root filesystem

## SYNOPSIS
**podman image mount** [*options*] [*image* ...]

**podman image mount** [*options*] name

## DESCRIPTION
Mounts the specified images' root file system in a location which can be

**podman image mount** mounts the specified images' root file system in a location which can be
accessed from the host, and returns its location.

If you execute the command without any arguments, Podman will list all of the
currently mounted images.
If a command is executed without any arguments, Podman will list all of the currently mounted images.

Rootless mode only supports mounting VFS driver, unless you enter the user namespace
Rootless mode only supports mounting `VFS driver`, unless you enter the user namespace
via the `podman unshare` command. All other storage drivers will fail to mount.

## RETURN VALUE
The location of the mounted file system. On error an empty string and errno is
returned.
**Return Value:**
The location of the mounted file system.

- **Note:**
On error an empty string and an errno is returned.

## OPTIONS

Expand All @@ -28,26 +32,31 @@ Mount all images.

#### **--format**=*format*

Print the mounted images in specified format (json).
Print the mounted images in specified format (`JSON`).
Copy link
Contributor

Choose a reason for hiding this comment

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

JSON should also be small.

Copy link
Member

Choose a reason for hiding this comment

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

From what I can see caps is correct.... https://www.rfc-editor.org/info/std90

Copy link
Contributor

@Procyhon Procyhon Jun 10, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

$ podman image diff --format JSON alpine
Error: only supported value for '--format' is 'json'
$ podman image diff --format json alpine
<works>

Writing it in caps lock does not work as you can see. I think it has to be defined what is more important, that it is written in caps like an acronym is written or that the right input for the flag is listed. I think that the later variant is more important. You can still describe it in the description of the option as JSON but if you list the argument for the flag in a table or refer to it should be small.

For the description should also be mentioned what happens if you don't right an input after the equal sign. JSON is the only xml like format that can be selected here, but if you just leave it blank the output is plain text.

Btw. I think that the flag does not even work. Input after the equal sign is simply ignored.

edit: spelling

Copy link
Author

Choose a reason for hiding this comment

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

I agree, there is something buggy about this. And the examples use diff when they should be using image diff. I remember testing the command on my machine and thought I was doing something wrong. I am going test this command more and open an issue

Copy link
Member

Choose a reason for hiding this comment

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

Only the lowercase version is accepted so we should not show this as JSON


## EXAMPLE

```
podman image mount fedora ubi8-init
- Location of the mounted images' root file system on the host is returned.

```
# podman image mount fedora ubi8-init
/var/lib/containers/storage/overlay/f3ac502d97b5681989dff84dfedc8354239bcecbdc2692f9a639f4e080a02364/merged
/var/lib/containers/storage/overlay/0ff7d7ca68bed1ace424f9df154d2dd7b5a125c19d887f17653cbcd5b6e30ba1/merged
```

- Currently mounted images.

```
podman mount
# podman mount

registry.fedoraproject.org/fedora:latest /var/lib/containers/storage/overlay/f3ac502d97b5681989dff84dfedc8354239bcecbdc2692f9a639f4e080a02364/merged
registry.access.redhat.com/ubi8-init:latest /var/lib/containers/storage/overlay/0ff7d7ca68bed1ace424f9df154d2dd7b5a125c19d887f17653cbcd5b6e30ba1/merged
```

- Mounted images displayed in `JSON` format.

```
podman image mount --format json
# podman image mount --format json
[
{
"id": "00ff39a8bf19f810a7e641f7eb3ddc47635913a19c4996debd91fafb6b379069",
Expand All @@ -73,4 +82,9 @@ podman image mount --format json
```

## SEE ALSO
podman(1), podman-image-umount(1), mount(8), podman-unshare(1)

**[podman(1)](podman.1.md)**, **[podman-image-unmount(1)](podman-image-unmount.1.md)**, **[podman-unshare(1)](podman-unshare.1.md)**, **mount(8)**

## HISTORY

July 2020, Originally compiled by Daniel Walsh <[email protected]>
69 changes: 37 additions & 32 deletions docs/source/markdown/podman-images.1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,72 +1,67 @@
% podman-images(1)

## NAME

podman\-images - List images in local storage

## SYNOPSIS

**podman images** [*options*]

**podman image list** [*options*]

**podman image ls** [*options*]

## DESCRIPTION
Displays locally stored images, their names, and their IDs.

**podman images** displays locally stored images, their names, and their IDs.

## OPTIONS

#### **--all**, **-a**

Show all images (by default filter out the intermediate image layers). The default is false.

#### **--digests**

Show image digests
Show all images. If set, itermediate layers are not filtered out.

#### **--filter**=*filter*, **-f**
**Note:**

Filter output based on conditions provided
- Intermediate layers are filtered out by default i.e. when this option is not set.
Copy link
Member

Choose a reason for hiding this comment

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

Why is this a list when there is only one sentence?


Filters:

**since=IMAGE**
Filter on images created after the given IMAGE (name or tag).

**before=IMAGE**
Filter on images created before the given IMAGE (name or tag).
#### **--digests**

**dangling=true|false**
Show dangling images. Dangling images are a file system layer that was used in a previous build of an image and is no longer referenced by any active images. They are denoted with the `<none>` tag, consume disk space and serve no active purpose.
Show image digests.

**label**
Filter by images labels key and/or value.
#### **--filter**=, **-f**=*filter*

**readonly=true|false**
Show only read only images or Read/Write images. The default is to show both. Read/Only images can be configured by modifying the "additionalimagestores" in the /etc/containers/storage.conf file.
| Filter | Description |
| ----------- | ----------- |
| since=IMAGE | Filter on images created after a given IMAGE (name or tag).|
| before=IMAGE | Filter on images created before the given IMAGE (name or tag).|
| dangling=true\|false | Show dangling images. Dangling images refer to file system layers that were used in a previous build of an image and are no longer referenced by any active images. They are denoted with the `<none>` tag, consume disk space and serve no active purpose. |
| label | Filter by images labels key and/or value. |
| readonly=true\|false | Show only read only images or read/write images. The default is to show both. Read only images can be configured by modifying the `"additionalimagestores"` in the `/etc/containers/storage.conf` file. |
| reference | Filter by image name, specified as regular expressions. |

**reference=**
Filter by image name, specified as regular expressions.
Filter output based on conditions provided.

#### **--format**=*format*

Change the default output format. This can be of a supported type like 'json'
or a Go template.
Valid placeholders for the Go template are listed below:
Change the default output format. This can be of a supported type like `json` or a `Go` template.
Valid placeholders for the `Go` template are listed below:

| **Placeholder** | **Description** |
| --------------- | ----------------------------------------------------------------------------- |
| .ID | Image ID |
| .Repository | Image repository |
| .Tag | Image tag |
| .Digest | Image digest |
| .CreatedSince | Elapsed time since the image was created |
| .CreatedSince | Elapsed time since the image was created |
| .CreatedAt | Time when the image was created |
| .Size | Size of layer on disk |
| .History | History of the image layer |

#### **--history**

Display the history of image names. If an image gets re-tagged or untagged, then the image name history gets prepended (latest image first). This is especially useful when undoing a tag operation or an image does not contain any name because it has been untagged.
Display the history of image names. If an image gets re-tagged or untagged, then the image name history gets prepended (latest image first). This is especially useful when undoing a tag operation or when an image does not contain any name because it has been untagged.

#### **--noheading**, **-n**

Expand All @@ -80,9 +75,17 @@ Do not truncate output.

Lists only the image IDs.

#### **--sort**=*sort*
#### **--sort**=**_created_**

Sort by created, id, repository, size or tag (default: created)
| Criteria | Description |
| ----------- | ----------- |
| **created** | When an image was created. |
| id | Alpha-numeric order of id of the created images.|
| repository | Repository from which the image was pulled.|
| size | Size of the image. |
| tag | Alpha-numeric order of tags given to the images.|

Sort by created, id, repository, size or tag. The default is **created**.

## EXAMPLE

Expand Down Expand Up @@ -188,7 +191,9 @@ docker.io/library/alpine latest 3fd9065eaf02 5 months ago 4.41 MB
```

## SEE ALSO
podman(1), containers-storage.conf(5)

**[podman(1)](podman.1.md)**, **[containers-storage.conf(5)](https://github.com/containers/common/blob/master/docs/containers-mounts.conf.5.md)**

## HISTORY
March 2017, Originally compiled by Dan Walsh `<[email protected]>`

March 2017, Originally compiled by Dan Walsh <[email protected]>
Loading