Skip to content

common: Cleanup manpage formatting #504

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

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

common: Cleanup manpage formatting #504

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
72 changes: 36 additions & 36 deletions common/docs/Containerfile.5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,67 +107,67 @@ Attach a filesystem mount to the container

Current supported mount TYPES are bind, cache, secret and tmpfs.

e.g.
Examples:

mount=type=bind,source=/path/on/host,destination=/path/in/container,relabel=shared
mount=type=bind,source=/path/on/host,destination=/path/in/container,relabel=shared

mount=type=tmpfs,tmpfs-size=512M,destination=/path/in/container
mount=type=tmpfs,tmpfs-size=512M,destination=/path/in/container

mount=type=secret,id=mysecret cat /run/secrets/mysecret
mount=type=secret,id=mysecret cat /run/secrets/mysecret

Common Options:
Common Options:

· src, source: mount source spec for bind and volume. Mandatory for bind. If `from` is specified, `src` is the subpath in the `from` field.
* src, source: mount source spec for bind and volume. Mandatory for bind. If `from` is specified, `src` is the subpath in the `from` field.

· dst, destination, target: mount destination spec.
* dst, destination, target: mount destination spec.

· ro, read-only: true (default) or false.
* ro, read-only: true (default) or false.

Options specific to bind:
Options specific to *bind*:

· bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
* bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).

. bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
* bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.

· from: stage or image name for the root of the source. Defaults to the build context.
* from: stage or image name for the root of the source. Defaults to the build context.

· relabel=shared, z: Relabels src content with a shared label.
* relabel=shared, z: Relabels src content with a shared label.

. relabel=private, Z: Relabels src content with a private label.
* relabel=private, Z: Relabels src content with a private label.

Labeling systems like SELinux require proper labels on the bind mounted content mounted into a container. Without a label, the security system might prevent the processes running in side the container from using the content. By default, container engines do not change the labels set by the OS. The relabel flag tells the engine to relabel file objects on the shared mountz.
Labeling systems like SELinux require proper labels on the bind mounted content mounted into a container. Without a label, the security system might prevent the processes running in side the container from using the content. By default, container engines do not change the labels set by the OS. The relabel flag tells the engine to relabel file objects on the shared mountz.

The relabel=shared and z options tell the engine that two or more containers will share the mount content. The engine labels the content with a shared content label.
The relabel=shared and z options tell the engine that two or more containers will share the mount content. The engine labels the content with a shared content label.

The relabel=private and Z options tell the engine to label the content with a private unshared label. Only the current container can use a private mount.
The relabel=private and Z options tell the engine to label the content with a private unshared label. Only the current container can use a private mount.

Relabeling walks the file system under the mount and changes the label on each file, if the mount has thousands of inodes, this process takes a long time, delaying the start of the container.
Relabeling walks the file system under the mount and changes the label on each file, if the mount has thousands of inodes, this process takes a long time, delaying the start of the container.
Comment on lines +138 to +144
Copy link
Contributor

@mtrmac mtrmac Dec 2, 2025

Choose a reason for hiding this comment

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

These are conceptually a description of the relabel= options, so should be nested under those bullet points (as opposed to the Options specific to *tmpfs* line below, which is “higher level” than the bullet points).

So, I think these should be indented one level; that seems to make a difference for GitHub rendering, but I’m afraid creates exactly the same man page content, so it does not help there. Maybe I’m missing a trick. If not, using a more precise markup means we can hope for md2man improvements in the future.


· rw, read-write: allows writes on the mount.
* rw, read-write: allows writes on the mount.

Options specific to tmpfs:
Options specific to *tmpfs*:

· tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
* tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.

· tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
* tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.

· tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself.
* tmpcopyup: Path that is shadowed by the tmpfs mount is recursively copied up to the tmpfs itself.

Options specific to cache:
Options specific to *cache*:

· id: Create a separate cache directory for a particular id.
* id: Create a separate cache directory for a particular id.

· mode: File mode for new cache directory in octal. Default 0755.
* mode: File mode for new cache directory in octal. Default 0755.

· ro, readonly: read only cache if set.
* ro, readonly: read only cache if set.

· uid: uid for cache directory.
* uid: uid for cache directory.

· gid: gid for cache directory.
* gid: gid for cache directory.

· from: stage name for the root of the source. Defaults to host cache directory.
* from: stage name for the root of the source. Defaults to host cache directory.

· rw, read-write: allows writes on the mount.
* rw, read-write: allows writes on the mount.

**RUN --network**

Expand All @@ -178,11 +178,11 @@ Syntax: `--network=<TYPE>`

**Network types**

| Type | Description |
|----------------------------------------------|----------------------------------------|
| [`default`](#run---networkdefault) (default) | Run in the default network. |
| [`none`](#run---networknone) | Run with no network access. |
| [`host`](#run---networkhost) | Run in the host's network environment. |
| Type | Description |
|-----------|----------------------------------------|
| `default` | Run in the default network. |
| `none` | Run with no network access. |
| `host` | Run in the host's network environment. |

##### RUN --network=default

Expand Down
103 changes: 64 additions & 39 deletions common/docs/containerignore.5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,28 +1,32 @@
% ".containerignore" "28" "Sep 2021" "" "Container User Manuals"
% ".containerignore" "5" "Sep 2021" "" "Container User Manuals"

# NAME

.containerignore(.dockerignore) - files to ignore buildah or podman build context directory

# INTRODUCTION

Before container engines build an image, they look for a file named .containerignore or .dockerignore in the root
context directory. If one of these file exists, the CLI modifies the context to exclude files and
directories that match patterns specified in the file. This avoids adding them to images using the ADD or COPY
instruction.

The CLI interprets the .containerignore or .dockerignore file as a newline-separated list of patterns similar to
the file globs of Unix shells. For the purposes of matching, the root of the context is considered to be both the
working and the root directory. For example, the patterns /foo/bar and foo/bar both exclude a file or directory
named bar in the foo subdirectory of PATH or in the root of the git repository located at URL. Neither excludes
Before container engines build an image, they look for a file named
`.containerignore` or `.dockerignore` in the root context directory. If one of
these file exists, the CLI modifies the context to exclude files and
directories that match patterns specified in the file. This avoids adding them
to images using the ADD or COPY instruction.

The CLI interprets the `.containerignore` or `.dockerignore` file as a
newline-separated list of patterns similar to the file globs of Unix
shells. For the purposes of matching, the root of the context is considered to
be both the working and the root directory. For example, the patterns `/foo/bar`
and `foo/bar` both exclude a file or directory named bar in the foo subdirectory
of PATH or in the root of the git repository located at URL. Neither excludes
anything else.

If a line in .containerignore or .dockerignore file starts with # in column 1, then this line is considered as a
comment and is ignored before interpreted by the CLI.
If a line in `.containerignore` or `.dockerignore` file starts with `#` in
column 1, then this line is considered as a comment and is ignored before
interpreted by the CLI.

# EXAMPLES

Here is an example .containerignore file:
Here is an example `.containerignore` file:

```
# comment
Expand All @@ -32,56 +36,77 @@ temp?
```

This file causes the following build behavior:
Rule Behavior
```
# comment Ignored.
*/temp* Exclude files and directories whose names start with temp in any immediate subdirectory of the root.
For example, the plain file /somedir/temporary.txt is excluded, as is the directory /somedir/temp.
*/*/temp* Exclude files and directories starting with temp from any subdirectory that is two levels below the
root. For example, /somedir/subdir/temporary.txt is excluded.
temp? Exclude files and directories in the root directory whose names are a one-character extension of temp. For example, /tempa and /tempb are excluded.
```
Matching is done using Go’s filepath.Match rules. A preprocessing step removes leading and trailing whitespace and
eliminates . and .. elements using Go’s filepath.Clean. Lines that are blank after preprocessing are ignored.

Beyond Go’s filepath.Match rules, Docker also supports a special wildcard string ** that matches any number of
directories (including zero). For example, **/*.go will exclude all files that end with .go that are found in all
directories, including the root of the build context.
`#comment`: Lines that start with the `#` character are ignored.

`*/temp*`: Exclude files and directories whose names start with temp in any
immediate subdirectory of the root. For example, the plain file
/somedir/temporary.txt is excluded, as is the directory /somedir/temp.

`*/*/temp*`: Exclude files and directories starting with temp from any
subdirectory that is two levels below the root. For example,
/somedir/subdir/temporary.txt is excluded.

`temp?`: Exclude files and directories in the root directory whose names are a
one-character extension of temp. For example, /tempa and /tempb are excluded.


Matching is done using the `filepath.Match` rules:

* A preprocessing step removes leading and trailing whitespace and eliminates
. and .. elements using the golang `path/filepath` package.
Copy link
Contributor

@mtrmac mtrmac Dec 2, 2025

Choose a reason for hiding this comment

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

(If this should be referring to Go’s implementation details at all — arguably that’s not very useful to users, but I think rewording all of this would be a different PR),filepath.Clean is a specific way to clean, and matches the form of the filepath.Match reference above.

* Lines that are blank after preprocessing are ignored.

Beyond the `filepath.Match` rules, Docker also supports a special wildcard
string `**` that matches any number of directories (including zero). For
example, `**/*.go` will exclude all files that end with `.go` that are found in
all directories, including the root of the build context.

Lines starting with `!` (exclamation mark) can be used to make exceptions to
exclusions. The following is an example `.containerignore` file that uses this
mechanism:

Lines starting with ! (exclamation mark) can be used to make exceptions to exclusions. The following is an example .containerignore file that uses this mechanism:
```
*.md
!README.md
```

All markdown files except README.md are excluded from the context.

The placement of ! exception rules influences the behavior: the last line of the .containerignore that matches a
particular file determines whether it is included or excluded. Consider the following example:
The placement of `!` exception rules influences the behavior: the last line of
the `.containerignore` that matches a particular file determines whether it is
included or excluded. Consider the following example:

```
*.md
!README*.md
README-secret.md
```
No markdown files are included in the context except README files other than README-secret.md.

No markdown files are included in the context except `README` files other than `README-secret.md`.

Now consider this example:

```
*.md
README-secret.md
!README*.md
```
All of the README files are included. The middle line has no effect because !README*.md matches README-secret.md and
comes last.

You can even use the .containerignore file to exclude the Containerfile or Dockerfile and .containerignore files.
These files are still sent to the daemon because it needs them to do its job. But the ADD and COPY instructions do
not copy them to the image.
All of the README files are included. The middle line has no effect because
`!README*.md` matches `README-secret.md` and comes last.

You can even use the .containerignore file to exclude the `Containerfile` or
`Dockerfile` and `.containerignore` files. These files are still sent to the
daemon because it needs them to do its job. But the `ADD` and `COPY` instructions
do not copy them to the image.

Finally, you may want to specify which files to include in the context, rather than which to exclude. To achieve
this, specify * as the first pattern, followed by one or more ! exception patterns.
Finally, you may want to specify which files to include in the context, rather
than which to exclude. To achieve this, specify `*` as the first pattern,
followed by one or more `!` exception patterns.

## SEE ALSO
buildah-build(1), podman-build(1), docker-build(1)

# HISTORY
*Sep 2021, Compiled by Dan Walsh (dwalsh at redhat dot com) based on docker.com .dockerignore documentation.
*Sep 2021, Compiled by Dan Walsh (dwalsh at redhat dot com) based on docker.com `.dockerignore` documentation.
Loading