# fs.stat

Inspect file types and byte sizes without reading file contents.

## Usage

```python
fs.stat(path, follow_symlinks = True)
```

- **`path`**
  The file or directory to inspect.
- **`follow_symlinks`**
  Follow the target by default. Set to 
  `False`
   to inspect
  a symlink itself, including a dangling link.

Returns an immutable object:

- **`size`**
  Size in bytes. Use for regular-file size checks; directory sizes are platform-specific.
- **`is_file`**
  Whether the inspected object is a regular file.
- **`is_dir`**
  Whether it is a directory.
- **`is_symlink`**
  Whether it is a symlink. Use 
  `follow_symlinks = False`
   to detect links.

A missing path, dangling target with the default options, or inaccessible path
raises an error.

```python
info = fs.stat("CLAUDE.md")
if info.is_file and info.size > 40000:
    errors.build("CLAUDE.md exceeds 40,000 bytes").fail()
```

Relative paths resolve against the script's working directory, including when
called from a loaded module. Absolute paths are used as given. These functions
inspect the local filesystem; they do not isolate access to the repository.
Calls honor cancellation before and after the filesystem operation.

See [reading files](/functions/automation/fs.read_file) and
[Git hooks](/cli/configuration/git#local-git-hooks).