How to make normal command `ls` and the wildcard `*` in Zsh

Question

Let's consider the interaction with Zsh on a Mac:

 % ls |grep gradle
gradle@7
 % ls gradle*
INSTALL_RECEIPT.json    LICENSE                 NOTICE                  README                  bin                     libexec

According to every description of the functionality of the * wildcard, the output of second invocation of ls should be same as the first. Yet, it lists the contents of the folder. Why is that? How can I fix it so that * behaves normally?

Obviously, in addition to Googling it (please don't suggest that I Google the answer), I tried reading man ls but that's completely unwieldy.

Answer 1

The glob is expanded by the shell and the resulting arguments passed to ls as if you had written them out in full.

1. gradle* matches once, on gradle@7.
2. ls gradle@7 is run.

Since gradle@7 is a directory, ls lists the contents. This is documented behaviour of ls:

For each operand that names a file of a type other than directory, ls displays its name […].
For each operand that names a file of type directory, ls displays the names of files contained within that directory […].

source: ls man page

The examples on your link use files, hence the files themselves are printed.

ls has an option to print the directory itself rather than its contents.

-d Directories are listed as plain files (not searched recursively).