go clean -h isn't helpful

[will....@gmail.com]

❯ go clean -h
usage: go clean [clean flags] [build flags] [packages]
Run 'go help clean' for details.

This just tells me to invoke another help command.

The flags package has the opinion that command help should print the doc for flags. Shouldn't we do that for go clean -h too?

[Ian Lance Taylor]

The intent is that "go clean -h" prints a short summary. People who
already know what the command does can use that short summary to
remind themselves of the available options. For people who don't know
what the command does, there is "go help clean".

Ian

[Will Faught]

> People who already know what the command does can use that short summary to remind themselves of the available options.

Which options do you mean? My point was that it doesn't document any options.

[Ian Lance Taylor]

On Mon, Jun 17, 2024 at 10:52 PM Will Faught <will....@gmail.com> wrote:
>
> > People who already know what the command does can use that short summary to remind themselves of the available options.
>
> Which options do you mean? My point was that it doesn't document any options.

Oh, sorry, I see what you mean. That's true, that isn't very helpful.
Want to send a patch?

Ian

[Will Faught]

Sure thing.

Just want to make sure we're on the same page. We would be changing the clean command help message to document its clean and build flags like the flags package does:

usage: go clean [clean flags] [build flags] [packages]

  -i    remove the corresponding installed archive or binary (what 'go install' would create)

  -n    print the remove commands it would execute, but not run them
  -r    apply recursively to all the dependencies of the packages named by the import paths

  -a
        force rebuilding of packages that are already up-to-date.
  -p n
        the number of programs, such as build commands or
        test binaries, that can be run in parallel.
        The default is GOMAXPROCS, normally the number of CPUs available.

  -race
        enable data race detection.
        Supported only on linux/amd64, freebsd/amd64, darwin/amd64, darwin/arm64, windows/amd64,
        linux/ppc64le and linux/arm64 (only for 48-bit VMA).

[...]

Run 'go help clean' for details.

The clean and build flags would be mixed together and ordered alphabetically, like flags does.

Does that look right?

Will

[Ian Lance Taylor]

On Sat, Jun 22, 2024 at 12:03 AM Will Faught <will....@gmail.com> wrote:
>
> Sure thing.
>
> Just want to make sure we're on the same page. We would be changing the clean command help message to document its clean and build flags like the flags package does:
>
> usage: go clean [clean flags] [build flags] [packages]
>
> -i remove the corresponding installed archive or binary (what 'go install' would create)
> -n print the remove commands it would execute, but not run them
> -r apply recursively to all the dependencies of the packages named by the import paths
> -a
> force rebuilding of packages that are already up-to-date.
> -p n
> the number of programs, such as build commands or
> test binaries, that can be run in parallel.
> The default is GOMAXPROCS, normally the number of CPUs available.
> -race
> enable data race detection.
> Supported only on linux/amd64, freebsd/amd64, darwin/amd64, darwin/arm64, windows/amd64,
> linux/ppc64le and linux/arm64 (only for 48-bit VMA).
> [...]
>
> Run 'go help clean' for details.
>
> The clean and build flags would be mixed together and ordered alphabetically, like flags does.
>
> Does that look right?

No, I was thinking of something different. The current pattern is
that "go CMD -h" prints a short summary of the flags. For example

> go fmt -h
usage: go fmt [-n] [-x] [packages]
Run 'go help fmt' for details.

This is useful for a quick reminder for how to run the command, and
shows people who need more information how to get more information.
So I think "go clean -h" should print something like

go clean [-i] [-r] [-cache] [-testcache] [-modcache] [-fuzzcache]

[build flags] [packages]
Run ' go help clean' for details

Ian

[Will Faught]

Ian,

I see. I'm concerned that approach wouldn't scale to the number of clean and build flags there are. I count 8 clean flags and 10+ build flags. That would look like:

> go clean [-i] [-n] [-r] [-x] [-cache] [-testcache] [-modcache] [-fuzzcache] [-C dir] [-a] [-p n] [-race] [-msan] [-asan] [-cover] [-covermode set,count,atomic] [-coverpkg pattern1,pattern2,pattern3] ...

That doesn't seem too useful.

Will

[Ian Lance Taylor]

On Sat, Jun 22, 2024 at 5:45 PM Will Faught <will....@gmail.com> wrote:
>
> Ian,refer>

> I see. I'm concerned that approach wouldn't scale to the number of clean and build flags there are. I count 8 clean flags and 10+ build flags. That would look like:
>
> > go clean [-i] [-n] [-r] [-x] [-cache] [-testcache] [-modcache] [-fuzzcache] [-C dir] [-a] [-p n] [-race] [-msan] [-asan] [-cover] [-covermode set,count,atomic] [-coverpkg pattern1,pattern2,pattern3] ...
>
> That doesn't seem too useful.

Agreed, which is why I did not suggest expanding the build flags. I
wrote exactly what I think the output "go clean -h" should be. We
already don't expand the build flags in most of the "go CMD -h"
output.

Ian

[Will Faught]

I see. That doesn't seem very useful to me, so I won't be making a patch for it. Thanks anyways.

[Ian Lance Taylor]

On Sat, Jun 22, 2024, 6:21 PM Will Faught <will....@gmail.com> wrote:

I see. That doesn't seem very useful to me, so I won't be making a patch for it. Thanks anyways.

No worries.  We're trying to strike a balance between a reminder and full documentation.  I don't think we need two different ways to get the full docs, as long as people can find them.

Ian

[qrta...@gmail.com]

I tried a patch as my first contribution :) https://github.com/golang/go/issues/68242

Laszlo