Would've been an easy one, except I decided to fix the text
to conform to our guidelines. I haven't been doing this,
but in this case it's only two man pages and the text is
short enough to make for easy review.
Signed-off-by: Ed Santiago <santiago@redhat.com>
Only applicable to podman-create and -run. I went with the -run
version because it is cleaner and more recently updated.
Signed-off-by: Ed Santiago <santiago@redhat.com>
Whew! This one started off identical everywhere, but the version
in podman-run got fixed in #1380, then again in #5192, with no
corresponding fixes to any of the other man pages.
I went with the podman-run version, with a small change in wording.
Signed-off-by: Ed Santiago <santiago@redhat.com>
Only between podman-create and -run. (podman-build is too
different). I went with the podman-run version.
Signed-off-by: Ed Santiago <santiago@redhat.com>
--dns-opt and --dns-search, but only in podman-create and -run.
Went with the -run version in both cases; --dns-opt remained
unchanged, but in --dns-search I changed 'and' to 'with'.
Did not consolidate podman-build or podman-pod-create: too
different.
Signed-off-by: Ed Santiago <santiago@redhat.com>
podman-logs and podman-pod-logs. Most of these were already
identical, needing no review. Exceptions:
--follow : needed some container/pod tweaking. This is the
only one that really needs careful review.
--names : I went with the longer version
Note that podman-events has --since and --until options too, but
those are too different to be combined here.
Signed-off-by: Ed Santiago <santiago@redhat.com>
This is not an easy one to review, sorry.
I went with the version from podman-create. The differences
against podman-run are subtle: apostrophes, whitespace, and
the arg description in the '####' line. Suggestion for review:
run hack/markdown-preprocess-review, then after you finish
with that, cd /tmp/markdown<TAB>/ipc and use your favorite
two-file diff tool to compare podman-run* against zzz*.
I did not even try to combine the podman-build one; that one
is too different.
Signed-off-by: Ed Santiago <santiago@redhat.com>
Two versions: one for container-related commands, one for pods.
The container one is easy: all versions matched, so I made no
changes.
The pod one is hard to review. I went with the pod-clone
version because the pod-create one looks suspicious: it
talks in terms of containers, not pods. It's possible
that I've got it wrong, and that these two cannot be
combined, so please review very carefully. I strongly
recommend using hack/markdown-preprocess-review for this one.
Signed-off-by: Ed Santiago <santiago@redhat.com>
I chose the version from podman-run because it is the most
up-to-date, and most correct wrt current syntax guidelines.
Differences are in arg description, language, and asterisks.
Signed-off-by: Ed Santiago <santiago@redhat.com>
Allow end users to preprocess default environment variables before
injecting them into container using `--env-merge`
Usage
```
podman run -it --rm --env-merge some=${some}-edit --env-merge
some2=${some2}-edit2 myimage sh
```
Closes: https://github.com/containers/podman/issues/15288
Signed-off-by: Aditya R <arajan@redhat.com>
I chose the version from podman-create. (This is unusual. podman-run
tends to have the better-maintained, more up-to-date version.)
Signed-off-by: Ed Santiago <santiago@redhat.com>
A NOP option. I chose the container word, of course, and the
word 'option' instead of 'flag'. I also hyphenated where needed.
I'm choosing to eliminate the "not on remote" text, because I
don't think it's true: podman-remote happily accepts that
flag on all those commands, including build. (It's marked
as hidden on build, but still accepted).
Signed-off-by: Ed Santiago <santiago@redhat.com>
Only on podman create and run: the --cpus option on container-clone
and pod-clone can probably be combined, but maybe later. pod-create
has unique wording that can't be combined.
This is a freebie to review: the text in both files was already
identical, and I made no changes to it. hack/markdown-preprocess-review
will agree, and show you no diffs, because there are none worth
seeing.
Signed-off-by: Ed Santiago <santiago@redhat.com>
When an unsupported limit on cgroups V1 rootless systems
is requested, podman prints an warning message and
ignores the option/flag.
```
Target options/flags:
--cpu-period, --cpu-quota, --cpu-rt-period, --cpu-rt-runtime,
--cpus, --cpu-shares, --cpuset-cpus, --cpuset-mems, --memory,
--memory-reservation, --memory-swap, --memory-swappiness,
--blkio-weight, --device-read-bps, --device-write-bps,
--device-read-iops, --device-write-iops, --blkio-weight-device
```
Related to https://github.com/containers/podman/discussions/10152
Signed-off-by: Toshiki Sonoda <sonoda.toshiki@fujitsu.com>
Much like --cidfile (#15414), --pod-id-file has two meanings.
One is used in pod-related commands, one in container ones.
Both meanings read the file, so the read/write split used
in --cidfile is not applicable here.
podman-pod-create keeps its --pod-id-file option because
that one cannot be refactored: that's the only command (now)
that writes a pod-id file.
Reviewable using hack/markdown-preprocess-review but I
did take some liberties with the #### args because they
were wrong. And, since I had to much with the description
text anyway (resulting in diffs), I also took the liberty
of cleaning up a double space.
Signed-off-by: Ed Santiago <santiago@redhat.com>
I've been doing the man-page cleanup distractedly, while
fighting other fires, and submitted some crap:
* #15339: I used single angle brackets, not double
* #15407: I only refactored --cert-dir from some man pages, not all
Easy to review with hack/markdown-preprocess-review, because all the
removed texts are identical. The only diff is that container-certs.d
is now a link.
Sorry about that. I'm going to spend more time being careful.
Signed-off-by: Ed Santiago <santiago@redhat.com>
There are two meanings: one writes a cidfile, the other reads.
Split into two .md files.
This can be reviewed with hack/markdown-preprocess-review .
The main differences you'll see are all in cidfile.read:
1) I use the <<subcommand>> feature. This works nicely for
kill, pause/unpause, and stop. It works less nicely for
rm, because the man page will show "...and rm the container"
(a human might prefer to see "REMOVE the container"). Given
the benefit of this cleanup, I think this is a fine tradeoff.
2) I choose to include the "multiple times" text even on man pages
where it wasn't present before. I tested to make sure it works.
3) The #### line I choose is IMHO the best one.
Minor differences:
* I believe the "remove the container" text in podman-kill
and podman-stop is a copy/paste error. This PR fixes it.
* The only differences between the cidfile.write texts is
the #### line (my version is best) and a final period.
Signed-off-by: Ed Santiago <santiago@redhat.com>
Refactor the --creds option. I went with the one in podman-pull
The main difference between all of them is the '####' line,
differences in the param descriptions. podman-pull had the
clearest one.
This is another one that hack/markdown-preprocess-review is
good for reviewing.
Signed-off-by: Ed Santiago <santiago@redhat.com>
After pulling/creating an image of a foreign platform, Podman will
happily use it when looking it up in the local storage and will not
pull down the image matching the host platform.
As discussed in #12682, the reasoning for it is Docker compatibility and
the fact that user already rely on the behavior. While Podman is now
emitting a warning when an image is in use not matching the local
platform, the documentation was lacking that information.
Fixes: #15300
Signed-off-by: Valentin Rothberg <vrothberg@redhat.com>
...and, tweak markdown-process-review so it can detect and
remove identical files, making review easier.
Signed-off-by: Ed Santiago <santiago@redhat.com>
Refactor the --authfile option.
My suggestion for review:
1) run hack/markdown-preprocess-review and immediately Ctrl-Q to
quit out of diffuse, which is completely unusable for this
many files; then
2) cd /tmp/markdown-preprocess-review.diffs/authfile
- this is the directory created by the review script
3) rm podman-image-sign* podman-log* podman-search.1.md.in
- because they're essentially identical to podman-create
4) rm podman-manifest-* podman-push.*
- because they're 100% identical to podman-kube-play
5) rm podman-kube-play*
- because it's apart-from-whitespace identical to podman-build
(use "wdiff" to confirm)
6) rm podman-auto-update*
- because that's the one I chose (hence == zzz-chosen.md)
(You should obviously run your own diff/cmp before rm, to confirm
my assertions about which files are identical).
After all that, you have a manageable number of files which
you can scan, read, diff against zzz-chosen.md, even run diffuse.
This option is IMHO the poster child for why we need this kind
of man page refactoring.
Signed-off-by: Ed Santiago <santiago@redhat.com>
Refactor the --annotation option, but only between podman create,
kube play, and run.
This does not include:
* podman build:
- usage is in terms of images, not containers/pods
* manifest add, manifest annotate:
- usage is in terms of images, not containers/pods
- also, wording is slightly different
Signed-off-by: Ed Santiago <santiago@redhat.com>
Smaller, more reviewable chunks.
This is just one option, --arch. Future PRs may, if the reviewing
is easy, include multiple options. This one includes fixes to
the preprocessor script, though:
* big oops, I was not handling '<<something pod|something>>'
where 'pod' appears other than the beginning of the string.
* I was also not handling 'container<<| or pod>>', where one
side was empty.
* Behavior change: <<subcommand>>, on podman-pod-foo,
becomes just 'foo' (not 'pod foo'). This will be useful
in a future PR where we refactor --pod-id-file.
Signed-off-by: Ed Santiago <santiago@redhat.com>
Followup to #15174. These are the options that are easy(ish)
to review: those that have only drifted slightly, and need
only minor tweaks to bring back to sanity. For the most part,
I went with the text in podman-run because that was cleaned up
in #5192 way back in 2020. These diffs primarily consist of
using '**' (star star) instead of backticks, plus other
formatting and punctuation changes.
This PR also adds a README in the options dir, and a new
convention: <<container text...|pod text...>> which tries
to do the right thing based on whether the man page name
includes "-pod-" or not. Since that's kind of hairy code,
I've also added a test suite for it.
Finally, since this is impossible to review by normal means,
I'm temporarily committing hack/markdown-preprocess-review,
a script that will diff option-by-option. I will remove it
once we finish this cleanup, but be advised that there are
still 130+ options left to examine, and some of those are
going to be really hard to reunite.
Review script usage: simply run it (you need to have 'diffuse'
installed). It isn't exactly obvious, but it shouldn't take more
than a minute to figure out. The rightmost column (zzz-chosen.md)
is the "winner", the actual content that will be used henceforth.
You really want an ultrawide screen here.
Signed-off-by: Ed Santiago <santiago@redhat.com>
podman-create and -run have many options in common. To date,
these are copy-pasted and haphazardly maintained.
Solution: add an include mechanism, '@@option foo', such
that multiple md source files can fetch from one common file.
This is a Phase One commit, a very small subset of what's
possible. Purpose of this commit is ease of review. If this
passes review, much more (trickier stuff) will be forthcoming.
Signed-off-by: Ed Santiago <santiago@redhat.com>
