Make SC2154 only show for lower case unassigned and also assign a separate error code for optional check "check-unassigned-uppercase" about shellcheck

[bruce-ricard]

I agree that the feature works as intended. I understand that the code is flagged when you pass these parameters.

What I'm saying is that the error message and the documentation is not the one associated with that error.

I now understand that I am seeing the appropriate warning. But at the beginning, because the message was so confusing, I thought that the warning was a bug. Now I understand that the problem is the documentation.
What I'm saying is that people will keep getting confused by the warning if we don't fix the documentation.

If you want to change the wording of the wiki you can and are welcome to.

I don't think that this will do. It seems to me like the issue is that the same SC warning is issued for both uppercase and lowercase variables.

I guess we could try to add to the wiki page something like: "by the way, if you happened to get this warning for your all uppercase external variables, it's because you ran with --enable=all or your enabled the uppercase check. In this case, the note doesn't apply to you, and the uppercase variables are correctly flagged by ShellCheck".
It doesn't look great to me, but it would at least share the information.

[bruce-ricard]

I've got new data. It appears that the issue is not with SC2154, but with the check-unassigned-uppercase check, for which I don't know the code. Because when you run shellcheck --enable=check-unassigned-uppercase, it displays the error message for SC2154, which appears not to be the correct one.

[brother]

For your example code above I would consider SC2154 appropriate. You try to use a variable that is not assigned in a context known to shellcheck.

[bruce-ricard]

For your example code above I would consider SC2154 appropriate. You try to use a variable that is not assigned in a context known to shellcheck.

The documentation states that it doesn't check all caps global variables. Something's wrong.

a variable that is not assigned in a context known to shellcheck

We cannot start checking for this. Otherwise we also need to warn about

ls

with: WARNING, the function ls may or may not be defined in this context.

Of course both ls and global variables need to be present for the script to run properly. And we add set -eu so that the script fails fast at runtime when they are not.

[bruce-ricard]

This check is equivalent to warn about

function add(int x, int y) {
   return x + y;
}

with "WARNING, x and y may be undefined. They are not set anywhere in this file!"

[brother]

Chill. It's hard to follow when you change the OP.

brother /tmp/test$ cat example.sh 
#!/bin/bash


echo "${GLOBAL_VARIABLE}"
brother /tmp/test$ shellcheck example.sh 
brother /tmp/test$ echo $?
0
brother /tmp/test$ shellcheck --enable=check-unassigned-uppercase example.sh 

In example.sh line 4:
echo "${GLOBAL_VARIABLE}"
      ^----------------^ SC2154 (warning): GLOBAL_VARIABLE is referenced but not assigned.

For more information:
  https://www.shellcheck.net/wiki/SC2154 -- GLOBAL_VARIABLE is referenced but...
brother /tmp/test$ echo $?
1

SC2154 will warn about usage of uninitialized variables. The default behavior is to skip upper case because they are considered to be global from outside the script.
If you explicitly enable the check to include the upper case variables by --enable=check-unassigned-uppercase or via --enable=all. it will ofc trigger for upper case as well.

There are examples of developers not knowing the scope handling of bash and they put something that looks like instance variables in upper case at the top to define certain things and then use them as "global for the script". In that style of code you need to include them in the check, hence --enable=check-unassigned-uppercase.
Enable the check and vet the use, remove errors found. And then leave it default disabled.

[brother]

--enable= is used to enable a list of optional checks. There are currently nine extra checks not enabled by default.
If you enable a optional check it can alter the default behavior, this is true for SC2154 with check-unassigned-uppercase.

SC2154 is a default check. You can disable a default check with --exclude=SC2154.

You can also provide a list of codes to check with --include=SC2154, that would disable all the other checks.

[bruce-ricard]

SC2154 will warn about usage of uninitialized variables. The default behavior is to skip upper case because they are considered to be global from outside the script.

I agree.

If you explicitly enable the check to include the upper case variables by --enable=check-unassigned-uppercase or via --enable=all. it will ofc trigger for upper case as well.

--enable=all does not explicitly enable this check, but implicitly.

When I ran shellcheck --enable=all, I got this warning message, telling me that uppercase variables are not included in this check, despite my variable being all uppercase. I had no idea that there existed a check that also validates global variables. That is a bug.
I don't know the relationship between check-unassigned-uppercase and SC2154. AFAICT they are not the same check. One is about local variables, the other about global ones.

There are examples of developers not knowing

Oh yes. That doesn't mean that we need to make the tools worse for those who know. I actually mentioned this in my initial post:

More generally, I don't understand this check. IMO, it shouldn't exist. If anything, we should be checking the opposite. If a global, all caps, variable is set and accessed in the same file, we should get a warning of the type:
this global variable is both set and read in the same file, making it a local variable. You should make it a local variable by using lowercase.
The assignment of a global variable should pretty much never be in the same file as its usage.

Chill.

??

It's hard to follow when you change the OP.

It's hard to follow when you use acronyms others don't know

[brother]

When I ran shellcheck --enable=all, I got this warning message, telling me that uppercase variables are not included in this check, despite my variable being all uppercase. I had no idea that there existed a check that also validates global variables. That is a bug.
I don't know the relationship between check-unassigned-uppercase and SC2154. AFAICT they are not the same check. One is about local variables, the other about global ones.

I t works as intended.

By default, without any --enable at all, the uppercase will not get flagged.
If you provide either all or check-unassigned-uppercase it will be flagged.

It is hard to cater for everyone using the tool but most people finding the --enable=all option is also capable of finding the list of the checks.
This behavior documented both in --list-optional and the wiki. If you want to change the wording of the wiki you can and are welcome to.