← All commands
THE COMMAND REFERENCE

stat

Show file size, permissions, type and timestamps.

Last updated

macOS / Apple

Implementation-level reference; examples are not certified for every installed version.

Overview

stat reports details about a file that ls hides or formats loosely: exact size, permission bits, type, owner and timestamps. Its output format is different on each implementation, and so is the option that chooses the fields, so the portable use is the exit status. Pick the format option in the GNU, Apple or BusyBox section for what you need.

Background

The stat utility appeared in NetBSD 1.6 and FreeBSD 4.10, according to the FreeBSD and macOS manuals. Today the name covers GNU stat, the stat that macOS ships, and the stat applet in BusyBox. They agree only on whether a file exists, and differ on the option that chooses the fields: GNU and BusyBox use -c, macOS uses -f, and the format letters do not overlap.

Examples

Test that a file exists. The output is discarded, and stat exits with a non-zero status for a missing file:

stat notes.txt > /dev/null && echo exists

Handle a missing file:

stat missing.txt 2> /dev/null || echo missing

Common mistakes

Parsing the default output of stat in a script breaks when you move between Linux and macOS. Choose the format option for the implementation in use, or use test -e, test -d and ls where they are enough. By default stat describes a symbolic link itself; -L describes its target.

Portability

GNU and BusyBox use -c FORMAT with letters such as %s for size and %a for the octal mode. macOS uses -f FORMAT with %z for size and %Lp for the octal mode. The two format languages do not overlap, so only the existence check is common. The Common examples were executed on GNU coreutils 9.11, macOS system tools, and BusyBox 1.37.0 (see the development guide for the exact check).

About macOS stat

This is the stat in /usr/bin on macOS. It prints chosen fields with -f FORMAT, using format letters that differ from GNU's.

Apple examples

Print only the size in bytes:

stat -f '%z' notes.txt

Print the octal permission bits and the file name; %Lp is the low permission bits and %N the name:

stat -f '%Lp %N' notes.txt

Print the file type as words, such as Regular File or Directory:

stat -f '%HT' logs

Options

-f
Print using a format string instead of the default report. %z is the size in bytes, %Lp the octal
permissions, %N the name, %HT the file type, %Su the owner and %Sm the modification time.

References

Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.