Explain flag

[Superpat]

Is there any interest in an --explain flag that would give an offline version of the wiki documentation? I dislike needing to have a browser open to get the longer descriptions.

Basically exactly what rustc --explain OPT does.

For new checks and feature suggestions

• [ x ] I searched through https://github.com/koalaman/shellcheck/issues and didn't find anything related

Here's a snippet or screenshot that shows the feature:

$ shellcheck --explain SC2148

Correct code:

#!/bin/sh
echo "$RANDOM"  # Unsupported in sh. Produces warning.

#!/bin/bash
echo "$RANDOM"  # Supported in bash. No warnings.

Rationale:

Different shells support different features. To give effective advice, ShellCheck needs to know which shell your script is going to run on. You will get a different numbers of warnings about different things depending on your target shell.

ShellCheck normally determines your target shell from the shebang (having e.g. #!/bin/sh as the first line). The shell can also be specified from the CLI with -s, e.g. shellcheck -s sh file.

If you don't specify shebang nor -s, ShellCheck gives this message and proceeds with some default (bash).

Note that this error can not be ignored with a directive. It is not a suggestion to improve your script, but a warning that ShellCheck lacks information it needs to be helpful.

Exceptions

None. Please either add a shebang or use -s.

[matthewpersico]

You effectively want to ship the wiki with the code?

[Superpat]

That's one way of putting it. I believe there's precedent, notably in the rust compiler and maybe also elm? But I feel that the practice of shipping man pages with a binary is also similar.

This might imply a shift in the way the wiki is maintained (into being more of an integral part of the project, living side by side with the code), that could be a good thing?

Nonetheless, those pages are helpful and it's annoying to have to switch from my editor to look them up or not have them available when offline.

A quick example of my use case would be similar to what I do here (except the explanation would be opened in a editor split rather than mpv)

Edit: To be clear, I'm open to implementing it myself, but before I do that, I'd like to know if it would be welcome.

[matthewpersico]

I see. I guess it is like shipping man pages and having a web site of same, ala Perl for one example. I guess that’s @koalaman ‘s call.

[koalaman]

One of the major purposes of the wiki is to serve as an errata, so I really don't want it hard-coded into the binary.

Just a couple of weeks ago ShellCheck started advertising the fact that it has a wiki (#920), so this information is already more discoverable than with an --explain flag. The Integration checklist also has wiki links as a point.

How about doing this as an add-on, like a fancier version of:

shellcheck-explain() { curl -Lqs "https://www.shellcheck.net/wiki/$1.md" | fold | less;  }

Or if the point is to work offline, how about converting the wiki pages to man pages for a shellcheck-man package that distros can easily update outside of regular shellcheck releases?

[Superpat]

I'll see what I can do about that. Would such a project be maintained in the same repo? Can a github project maintain multiple types of releases? Or should I create another repo?

[Gandalf-]

Another similar issue is #1122

[msanders]

Updated workaround for fish shell using bat:

function shellcheckwiki --description "Display shellcheck wiki in terminal"
    argparse "h/help" "o/offline" -- $argv; or return
    if set --query _flag_help; or not test (count $argv) = 1
        printf >&2 "Usage: %s [-h | --help] [-o | --offline] <code>\n" (status current-function)
        return (set --query _flag_help)
    end
    set --local code $argv[1]
    if set --query _flag_offline
        bat --language md /path/to/shellcheck.wiki/$code.md
    else
        set --local display_name "https://www.shellcheck.net/wiki/$code"
        set --local md_url "https://raw.githubusercontent.com/wiki/koalaman/shellcheck/$code.md"
        curl --proto '=https' --tlsv1.2 -sS $md_url | bat --language md --file-name $display_name
    end
end

The wiki can be cloned for offline use via:

git clone https://github.com/koalaman/shellcheck.wiki.git

[Superpat]

This should probably be tagged with wontfix or something like it. I'm closing it.

For the record, I currently use a plan9port plumber rule so that when I right click SC2148 it's explanation is downloaded with links then displayed in a plan9port acme window. Works pretty nicely.