Shebang warning should give different advice

[dseynhae]

For bugs

• Rule Id (if any, e.g. SC1000): SC2148
• My shellcheck version (shellcheck --version or 'online'): online
• I tried on shellcheck.net and verified that this is still a problem on the latest commit
• It's not reproducible on shellcheck.net, but I think that's because it's an OS, configuration or encoding issue

For new checks and feature suggestions

• shellcheck.net (i.e. the latest commit) currently gives no useful warnings about this
• I searched through https://github.com/koalaman/shellcheck/issues and didn't find anything related
  Related:
  Regarding shell scripts that are only meant to be source (SC2148) #581
  add a warning when people put comments above the shebang #844

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

# shellcheck disable=SC2148
export SHELLCHECK=1

Here's what shellcheck currently says:

Line 1	SC2148: Tips depend on target shell and yours is unknown. Add a shebang.

Here's what I wanted or expected to see:

SC2148: Tips depend on target shell and yours is unknown.
For an executable script add a shebang (#!<full_path>/<shell>).
For a sourced script add a pseudo-shebang (#!/<shell>).

I tried to ignore the tip with

# shellcheck disable SC2148

But that doesn't work (the tip still shows up). Maybe this should turn of the tip after all?

[gromgit]

Shellcheck's output tips are one-liners so they can be "stacked" efficiently when a single script line contains multiple issues. Making the tips more verbose clutters the output while adding minimum utility; explanations, detailed hints and alternatives should go in the corresponding wiki page, where they can be tailored/enhanced/expanded without having to re-release shellcheck itself.

I tried to ignore the tip with

# shellcheck disable SC2148

But that doesn't work (the tip still shows up).

Aside from a missing =, SC2148 is red for a reason: It's an error, not a warning or something less serious. Disabling errors kinda defeats the purpose of shellcheck.

[dseynhae]

The actual code that I put in originally does have the '=' sign, sorry for transcribing this wrong in my later comments.
I understand that we should pay attention to the feedback. However I consider my scripts "done", if it doesn't list any issues. And that means I want to locally shut up "false" errors.

For this specific case: I know that spellcheck is not aware of the specific shell... But I consider putting a shebang in a script that is supposed to be sourced an error in itself...

I just found out about the 'shell' directive, and consider the following code more appropriate to solve my dilemma:

# shellcheck shell=bash
export SHELLCHECK=1

I agree that pursuing one-liners keeps the tool readable. But shouldn't the error message assume that a shebang is not needed, and suggest:

Line 1	SC2148: Tips depend on target shell and yours is unknown. Add a 'shell' directive.

[gromgit]

But shouldn't the error message assume that a shebang is not needed

Shellcheck has no way of knowing how you intend to use the code it's checking (executable script or sourced file), and the consequences w.r.t. shebangs (or lack thereof) are very different:

1. If you give shellcheck a sourced file with a shebang, it'll happily check against the specified shell, exactly as if you'd specified a shell directive. No harm done.
2. If you give shellcheck a script without a shebang, but with a shell directive, shellcheck will check against the shell you specify. But since there's no shebang, your OS will default to /bin/sh for your script, so it'll likely crash at the first bashism. Not good.

Therefore, rewording SC2148 to recommend adding a "shell" directive instead of a shebang is not a good idea.

[dseynhae]

Counterpoints

1. Your first point is true (a shebang doesn't prevent a script from being sourced), but I think there is harm after all.

If the script has a shebang, the shebang will make the script "executable" (granted, you do need execution privileges as well, but some people are careless with their umask).
It definitely gives the illusion that the intent of the author is to execute the script.

So that is why I never put a shebang in a script that is meant to be sourced; And I also change the permissions to non-executable.

Therefore, if I don't have a shebang in my script, that's not an error:

• First of all, the shell specifications do not require it!
• And it is my full intention, to clearly indicate that you should NOT execute this. I do not want the semantics of a shebang to kick in...

Therefore, shellcheck should not assume that I forgot the shebang. I believe it is harmful, for my purposes.

2. Your second point definitely gives cause to more reflection.
   I always thought that when you source a script, it will be sourced in the context of your active shell. That is not necessarily /bin/sh (it is up to your /etc/passwd configuration). So it can be sh, csh, tcsh, bash, ksh,...
   So, the 'shell' directive is to let shellcheck know which shell the calling shell will be.

Which in my case is bash (we document our scripts that way). And the 'shell' directive is actually the most appropriate reinforcement of this requirement.

Conclusion

• Not having a shebang is not an error. It is not illegal. It is a desired feature.
• When the author of a script doesn't have a shebang, assume that they don't want one. And the reminder to put a 'shell' directive is the most appropriate way to solve the conflict.
• Even if the author forgot the shebang, the directive instruction will trigger them to add the shebang after all.

[austin987]

Or a compromise solution:
SC2148: Tips depend on target shell and yours is unknown. Add a shebang or a 'shell' directive.

[dseynhae]

Or a compromise solution:
SC2148: Tips depend on target shell and yours is unknown. Add a shebang or a 'shell' directive.

Seems like this is not a compromise. It is a superior recommendation!
:-)

[koalaman]

A shell directive is obviously the best choice, but for the principle of least astonishment, you're now additionally able to disable the warning with a directive.

The fact that you couldn't was just a bug in the AST traversal: it didn't visit the shebang, and therefore failed to associate the shebang warnings with the script's list of directives.