The manpage says:
execute/search only if the file is a directory or already has execute
permission for some user (X
)
POSIX says:
The perm symbol X shall represent the execute/search portion of the file mode bits if the file is a directory or if the current (unmodified) file mode bits have at least one of the execute bits (S_IXUSR, S_IXGRP, or S_IXOTH) set. It shall be ignored if the file is not a directory and none of the execute bits are set in the current file mode bits.
This is a conditional permission flag: chmod
looks at whatever it is currently processing, and if it’s a directory, or if it has any execute bit set in its current permissions (owner, group or other), it acts as if the requested permission was x
, otherwise it ignores it. The condition is verified at the time chmod
applies the specific X
instruction, so you can clear execute bits in the same run with a-x,a=rwX
to only set the executable bit on directories.
You can see whether a file has an execute bit set by looking at the “access” part of stat
’s output, or the first column of ls -l
. Execute bits are represented by x
. -rwxr-xr-x
is common for executables and indicates that the executable bit is set for the owner, group and other users; -rw-r--r--
is common for other files and indicates that the executable bit is not set (but the read bit is set for everyone, and the write bit for the owner). See Understanding UNIX permissions and their attributes which has much more detail.
Thus in your example, u=rwX
sets the owner permissions to read and write in all cases, and for directories and executable files, execute; likewise for group (g=rX
) and other (o=rX
), read, and execute for directories and executable files.
The intent of this operator is to allow the user to give chmod
a variety of files and directories, and get the correct execute permissions (assuming none of the files had an invalid execute bit set). It avoids having to distinguish between files and directories (as in the traditional find . -type f -exec chmod 644 {} +
and find . -type d -exec chmod 755 {} +
commands), and attempts to deal with executables in a sensible way.
(Note that macOS chmod
apparently only supports X
for +
operations.)