Skip to content

Conversation

euanh
Copy link
Collaborator

@euanh euanh commented May 7, 2025

Motivation

Arranging related options together in groups makes it easier for users to find relevant options. This will be even more beneficial as more options are added (e.g. #91).

Modifications

  • Arrange containertool's command line options into related groups with headings.
  • Update build-container-image manual page to match the new groupings.

Result

  • Users will be able to find help for specific options more easily.
  • Grouping options together may also help them to discover new options related the tasks they are trying to achieve.

Test Plan

  • No functional change.
  • All existing tests continue to pass.

@euanh euanh marked this pull request as ready for review May 7, 2025 14:42
@euanh euanh force-pushed the option-groups branch from 2d09732 to c462f2a Compare May 7, 2025 14:46
@euanh
Copy link
Collaborator Author

euanh commented May 7, 2025

containertool command line help, for comparison:

% swift run containertool --help
[1/1] Planning build
Building for debugging...
[1/1] Write swift-version-1AF32027EA501FB9.txt
Build of product 'containertool' complete! (2.48s)
OVERVIEW: Build and publish a container image

USAGE: containertool [<options>] <executable>

ARGUMENTS:
  <executable>            Executable to package

SOURCE AND DESTINATION REPOSITORY OPTIONS:
  --default-registry <default-registry>
                          Default registry for image references which do not specify one
  --repository <repository>
                          Destination image reference
  --tag <tag>             Destination image tag
  --from <from>           Base image reference

IMAGE BUILD OPTIONS:
  --resources <resources> Directory of resources to include in the image

IMAGE CONFIGURATION OPTIONS:
  --architecture <architecture>
                          CPU architecture
  --os <os>               Operating system

AUTHENTICATION OPTIONS:
  --default-username <default-username>
                          Default username, used if there are no matching entries in .netrc
  --default-password <default-password>
                          Default password, used if there are no matching entries in .netrc
  --enable-netrc/--disable-netrc
                          Load credentials from a netrc file (default: --enable-netrc)
  --netrc-file <netrc-file>
                          Specify the netrc file path
  --allow-insecure-http <allow-insecure-http>
                          Connect to the registry using plaintext HTTP (values: source, destination, both)

OPTIONS:
  -v, --verbose           Verbose output
  -h, --help              Show help information.

@euanh euanh requested a review from heckj May 7, 2025 14:47
@euanh euanh added area/documentation Improvements or additions to documentation semver/none No version bump required. labels May 7, 2025
Copy link
Collaborator

@heckj heckj left a comment

Choose a reason for hiding this comment

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

I'm concerned I may have inadvertently been inconsistent. I tend to lean into "container image" vs. "image". I think 'destination' may be a bit overused, but it's super helpful where there's possible confusion of "where I'm getting a base image from" vs. "where I'm sending the built image" - take a look and see what you think. Hopefully this resonates well.

euanh and others added 6 commits May 8, 2025 16:01
Co-authored-by: Joseph Heck <j_heck@apple.com>
…ner-image.md

Co-authored-by: Joseph Heck <j_heck@apple.com>
Co-authored-by: Joseph Heck <j_heck@apple.com>
Co-authored-by: Joseph Heck <j_heck@apple.com>
Co-authored-by: Joseph Heck <j_heck@apple.com>
Co-authored-by: Joseph Heck <j_heck@apple.com>
@euanh
Copy link
Collaborator Author

euanh commented May 9, 2025

Thank you @heckj!

@euanh euanh requested a review from heckj May 9, 2025 14:28
@euanh euanh merged commit 3030089 into apple:main May 12, 2025
23 checks passed
@euanh euanh deleted the option-groups branch May 12, 2025 09:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/documentation Improvements or additions to documentation semver/none No version bump required.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants