Name & Type

By Name

Find files by exact name

find /etc -name "hostname" -type f 2>/dev/null

Case-insensitive name search

find /etc -iname "*.conf" -type f 2>/dev/null | head -20

Find by extension — all AsciiDoc files in a domus repo

find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT -name "*.adoc" -type f | head -20

-name matches the basename only — never the path

# WRONG — -name won't match a path component
# find docs -name "codex/find" -type d

# CORRECT — -path matches against the full path
find ~/atelier/_bibliotheca/domus-captures/docs -path "*/codex/find" -type d

NOT matching — exclude a pattern with ! or -not

find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/partials -type f \
  ! -name "*.adoc"

OR conditions with grouping — .adoc OR .yml files

# Parentheses are mandatory — without them -type f only applies to the first -name
find ~/atelier/_bibliotheca/domus-captures/docs -type f \
  \( -name "*.adoc" -o -name "*.yml" \) | head -20

AND with two -name predicates — files containing BOTH words

# Implicit AND — matches "R1-sets-real-numbers.adoc"
find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT \
  -type f -name "*real*" -name "*numbers*"

By Type

Find only regular files

find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages -type f | head -10

Find only directories

find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages -mindepth 1 -maxdepth 1 -type d

Find symlinks — stow-managed dotfiles in home

# Stow creates symlinks in ~ pointing into the dotfiles repo
find ~ -maxdepth 1 -type l 2>/dev/null | head -10

Find symlinks in .config — stow directories

find ~/.config -maxdepth 1 -type l 2>/dev/null | head -10

Follow symlinks with -L — resolve targets

# Default: -type f won't match through symlinks
# -L dereferences — follows symlinks to their targets
find -L ~/.config -maxdepth 2 -type f -name "*.toml" 2>/dev/null | head -10

Depth Control

Limit search depth — maxdepth (no recursion past N)

# Only immediate children of /etc — no recursion into subdirs
find /etc -maxdepth 1 -type f -name "*.conf" 2>/dev/null | head -10

Minimum depth — skip the starting-point and top levels

# Skip ROOT/ itself and pages/ — start matching at depth 2
find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages -mindepth 2 -maxdepth 2 -type d

Depth as a band-pass filter — mindepth floor, maxdepth ceiling

# Level counting from the starting-point:
#   ROOT/                                      level 0
#   ROOT/pages/                                level 1
#   ROOT/pages/codex/                          level 2
#   ROOT/pages/codex/text/                     level 3
#   ROOT/pages/codex/text/find.adoc            level 4
#
# Antora content in domus-captures sits at level 4.
# Clamp to exactly that level:
find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT \
  -mindepth 4 -maxdepth 4 -name "*find*" -type f

Why a shallow band returns nothing — content lives deeper

# Level 2 holds category directories (codex/, education/, worklog/), not files.
# -type f rejects every match — result is empty:
find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT \
  -mindepth 2 -maxdepth 2 -name "*find*" -type f

# mindepth does not stop traversal. find still walks through levels 0-3
# to reach level 4. It just skips applying tests at the excluded levels.

Target a depth range — levels 3 through 5

# Content in domus-captures spans levels 3 (index.adoc) to 5+ (deep nesting)
# Grab just levels 3 and 4:
find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages \
  -mindepth 3 -maxdepth 4 -name "*.adoc" -type f | head -15

maxdepth 0 — test only the starting-point itself

# Is this path a directory? (Checks ROOT/ only — no descent)
find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT -maxdepth 0 -type d

Glob vs Regex

-name uses shell globs (, ?, […]). There is no alternation. -regex uses regular expressions and matches the *entire path, not just the filename.

-name is a glob — the pipe character is literal, not alternation

# WRONG — looks for a literal "|" in the filename. Returns nothing:
find . -name "*real|numbers*" -type f

# RIGHT — use -o with parentheses for alternation in globs:
find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT \
  -type f \( -name "*real*" -o -name "*numbers*" \)

-regex for true alternation — requires -regextype on GNU find

# GNU find defaults to Emacs regex (\| and \(\) for groups).
# posix-extended gives the standard | and () syntax:
find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT \
  -regextype posix-extended \
  -type f -regex ".*(real|numbers).*"

-iregex — case-insensitive regex across the full path

find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT \
  -regextype posix-extended \
  -type f -iregex ".*(find|grep).*" | head -10

Regex on full path — match files in any YYYY/MM directory

find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages \
  -regextype posix-extended \
  -regex '.*/[0-9]{4}/[0-9]{2}/.*\.adoc' | head -10

Regex to find files at a specific depth pattern

# Match exactly 3 path components under pages/ (category/subcategory/file)
find ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/pages \
  -regextype posix-extended \
  -regex '.*/[^/]+/[^/]+/[^/]+\.adoc' -type f | head -10

-path with shell glob — middle ground between -name and -regex

# -path matches the full path but uses glob syntax, not regex
# Find any .adoc file under a "codex" directory at any depth:
find ~/atelier/_bibliotheca/domus-captures/docs -path "*/codex/*.adoc" -type f | head -10

# Contrast with -name which only matches the filename:
# find docs -name "codex/*.adoc"   # WRONG — -name never matches /