What's the status of `_format`?

Development Package Manager
1

I was poking around in Swift Package Manager and noted the relatively undocumented command _format in the output. It looks like it was added back in 2020 by Nate Cook (@nnnnnnnn) as a pass-through sort of command to invoking swift-format, but it stands out in that 1) there's no one-liner about what it is or does and 2) has the _ prefix which makes me think it's experimental, with the exception that it's been there for a number of releases now.

It feels really awkward to see _format in the output when you're exploring:

swift package:

SUBCOMMANDS:
  clean                   Delete build artifacts
  purge-cache             Purge the global repository cache.
  reset                   Reset the complete cache/build directory
  update                  Update package dependencies
  describe                Describe the current package
  init                    Initialize a new package
  _format
  diagnose-api-breaking-changes
                          Diagnose API-breaking changes to Swift modules in a
                          package
  dump-symbol-graph       Dump Symbol Graph
  dump-pif
  dump-package            Print parsed Package.swift as JSON
  edit                    Put a package in editable mode
  unedit                  Remove a package from editable mode
  config                  Manipulate configuration of the package
  resolve                 Resolve package dependencies
  show-dependencies       Print the resolved dependency graph
  tools-version           Manipulate tools version of the current package
  compute-checksum        Compute the checksum for a binary artifact.
  archive-source          Create a source archive for the package
  completion-tool         Completion tool (for shell completions)
  plugin                  Invoke a command plugin or perform other actions on
                          command plugins

I wanted to see what the current thinking was on this. Would a PR be welcome to make it just format (removing the _ prefix) and adding a one-liner describing what it is and does? Or is this still experimental in some form, in which case - what's the end-game of this experiment and what's it waiting on?

1 Like
2

Simple answer: It should be properly hidden; it is experimental. It is useful to developers working on Swift itself, but will not work for a user without external set‐up.

Details: It forwards to {$SWIFT_FORMAT} --mode format --in-place --parallel {$x} for each Swift file x. See here. The environment variable would only have been set if the user had done so manually after installing swift‐format.

From SwiftPM’s perspective, two things need to happen before it can be advertised as a proper feature:

  1. swift‐format needs to be included in the toolchain (which is a multistep process from its end).
  2. The format command here needs to be rewritten to call into the corresponding toolchain instead of relying on a user‐specified path.
4 Likes
3

Makes sense to me, thank you. I opened a PR to hide it by default, with the aim to clean up the output from someone exploring swift package or swift package --help.

1 Like