Clarify --help text and error messages to alleviate confusion especially around cache cleaning

[ByteAnnyTA]

Is your feature request related to a problem? Please describe.

Today I wanted to clean my cache since I noticed that the pacman and yay caches take up a large part of my hard drive.

I had already cleaned my pacman cache via paccache earlier without any issues, but I noticed that the ~/.cache/yay/ directory was still really large.

Like I assume most users would, I consulted yay --help and stumbled upon the following entries that looked related to cache clearing:

yay specific options:
    -c --clean            Remove unneeded dependencies (-cc to ignore optdepends)
       --gendb            Generates development package DB used for updating

[...]

pacman operation specific options:
usage:  pacman {-S --sync} [options] [package(s)]
options:
[...]
  -c, --clean          remove old packages from cache directory (-cc for all)

To me, on closer inspection this looked like --clean does not have anything to do with the cache, but rather with orphaned packages, but I tried it anyway, being met with this error message:

error: invalid option: '--clean' and '--refresh' may not be used together
 -> exit status 1

I assumed this was a bug, since I did not supply --refresh at all. I thought that perhaps the standard -Syu behaviour got in the way by mistake. I took to a search engine and found out this was intentional behaviour, without any further explanation as to why. Strange start, I think.

I found several Github issues on this, most of which recommended one of two commands to fix the 'issue' we were experiencing: yay -Ycc and yay -Scc.

I ran both. Through context clues, I understood that yay -Ycc uninstalled orphaned dependencies. This was not what I wanted to do initially. yay -Scc finally then turned out to be the cache cleaning command that I actually wanted to use, prompting me step-by-step to clean all relevant pacman and yay caches.

Now I think I understand how this entire thing works.
While all the lower-case arguments are options, you have to supply an actual operation when running yay. Operations are the upper-case letters, somewhat like feature categories.

Since yay -c/yay -cc does not include an operation like S or Y, it defaults to yay -Syu resulting in the full command yay -Syu --clean, which breaks the cleaning option of course.

Instead, I had to choose one of the operations.

But without looking at Github issues, how was I supposed to know that yay -Ycc cleaned up orphaned packages and yay -Scc allows me to clear my caches?

The -Y operation is just labelled 'yay', which I understood to be commands related to the yay program itself. The -S option is labelled 'sync', which I understood to be commands related to downloading and installing packages.

Also, there are three different -c options in the help text:

• 'used for completions', under 'show specific options', which is a headline I do not understand immediately, I can only assume it refers to the --show operation.
• 'remove unneeded dependencies', under 'yay specific options', which is something I only now understand as related to the -Y operation. Why removing orphaned packages is specifically a 'yay operation' is something I don't get right now either.
• 'remove old packages from cache directory', under 'pacman specific options' and a pacman usage guide. It does not indicate that you need to use the -S operation to actually run that option, and due to the pacman usage guide randomly inserted there, it even looks like you need to actually use the pacman command to do any of that.

Nothing indicates that -Scc is the command I am looking for here, especially not for an inexperienced user. I still don't know why clearing my local cache is a -S/--sync operation.

This is technically understandable for outsiders after a while, but it took even me as what people would call a 'power user' half an hour to debug and understand. It doesn't seem like this is really effective UX, especially for the target audience of yay: people who need a convenient AUR helper utility who are statistically more likely to be less knowledgeable about their system. I think the help text should be reworded in some way, since this confusion comes up fairly regularly even here on the Github issues:

• Unable to clean the cache #2595
• yay -c doesn't work #2099
• yay -c issue #2091
• Error: Wrong parameter: '--clean' and '--refresh' cannot be used at the same time #2086
• yay -c failed #2069
• yay 12.0.0 regression: "invalid option: '--clean' and '--refresh' may not be used together" #2049

This is an indicator that I am not alone with this confusion.

Describe the solution you'd like

Personally, I would propose the following solution:

• Reorder the --help text into clearly distinguished operation categories. This is already somewhat the case, but I did not understand that the headline yay specific options: refers to options that can only be used in conjunction with the -Y operation prefix. Every operation then has its own headline that clearly states which prefix (-S, -Y, -P etc.) to use to invoke it, and the list of options below that headline only applies to the options used with that specific operation.
• Rephrase error messages when running an option without a specified operation. There is no reason for yay --clean resulting in error: invalid option: '--clean' and '--refresh' may not be used together. It should clearly state that yay -Syu was assumed due to the lack of an operation prefix, or helpfully even refer to Did you mean yay -Scc (clean caches) or yay -Ycc (clean orphaned packages)?