find
| Function | Recursively lists page, space, or folder paths, or searches page bodies with -exec grep. |
| Options | -name PATTERN, -maxdepth N, `-mtime [+ |
| Limitations | At most one PATH. Default -maxdepth is 5. Results cap at 5000 paths; child fetches (walk) or CQL pages (-mtime / -label) cap at 250; -exec grep fetches at most 100 bodies. Mutating commands refuse folder paths. |
With no PATH, find searches under the current directory (same as find .). It prints matching paths, one absolute path per line (leading /, same style as pwd).
Without -mtime / -label, it prints the start path, then descendants depth-first (pages and folders). With -mtime or -label, results come from the CQL search index (last update = content version when) and are sorted by path segments (parent before child). That order can differ from a plain walk. The index may lag ls -l by seconds to minutes after edits or after label add / label rm. Folder listings use the same search index, so a just-created or just-moved folder may be missing briefly.
| Predicate | Meaning |
|---|---|
-name PATTERN | Match the space, page, or folder title. * matches any sequence; ? matches one character (same as ls). |
-maxdepth N | Limit depth from the start path. 0 is only the start path; 1 is the start path plus direct children. An explicit -maxdepth always wins, including values higher than 5. Unchanged when -mtime / -label is given, so those results stay a subset of a plain find. |
| `-mtime [+ | -]N` |
-label NAME | Pages that have this global label (CQL; multiple flags are AND). Same name rules as label add. Walk mode does not apply -label. |
-prune | Print a matching node and do not descend under it. With -mtime / -label, keeps the top-most matches so find … | mv -n DEST does not flatten parent and child. Without those filters, the walk is unchanged aside from honoring -prune. |
-ls | Long listing (one hit per line). Columns: id status vN owner last_update title path url. First 5 columns are padded (same as ls -l). Use -ls; --format long is rejected. |
--format csv / --format=csv | CSV (header row + one hit per line). Same columns as ls --format csv plus a trailing path column. RFC 4180; UTC ISO timestamps; printed to the terminal (no > redirect). |
-exec grep … | Last action only. For each path find would print, fetch the page body and run grep. v1 supports grep only. Can’t combine with -ls / --format. |
find … | grep PATTERN filters path strings. find … -exec grep PATTERN searches page bodies.
-exec grep reuses grep’s -i / -v / -n / -c. Default output is a path header plus matching lines (pages with no matches are omitted). With -c, each hit is path:count.
owner is an Atlassian accountId (display names are not shown). Space hits leave version / last_update empty (- in -ls).
Pipe -ls / --format csv to head / grep / less. Do not pipe them to mv / cp / rm / label / archive — those expect plain path lines. For those pipes, use a bare find (no -ls / --format csv). find … | mv DEST accepts sources in another space, but the whole batch needs -y / --yes (preview with -n); find … | cp DEST copies cross-space without -y. At most 100 piped sources.
PATH and predicates may appear in any order before -exec. Prefer -prune and mv -n when piping stale pages into Archive so children are not moved beside their parents.
Quoted paths: './Name', "./Name", and ./Name\ with\ spaces resolve like ./'Name'. A quoted span is one title ('./a/b' is the single title a/b); write ./'a'/'b' for nested titles.
Examples
Section titled “Examples”$ find$ find .$ find ./MySpace$ find -name Alpha*$ find ./MySpace -maxdepth 1$ find -name '*Notes*' -maxdepth 3$ find ./MySpace | head 20$ find ./MySpace -mtime +365$ find -label needs-review$ find ./SPACE -mtime +365 -label needs-review -prune$ find ./SPACE -mtime +365 --format csv$ find ./MySpace -ls$ find . -name '*Notes*' -mtime +180 -maxdepth 5$ find ./MySpace/Projects -mtime +365 -prune | mv -n ./MySpace/Archive$ find ./MySpace/Projects -mtime +365 -prune | head 100 | mv ./MySpace/Archive$ find ./MySpace -maxdepth 2 -exec grep error$ find -name '*Notes*' -exec grep -i TODO$ find ./MySpace -exec grep -c error$ find ./MySpace | grep Notes$ find ./folder -name 'Draft*' | mv -n ./ArchiveWhile working…, press Esc or Ctrl+C to abort (conshell: interrupted). If a cap is hit, Shell prints paths collected so far, then a marker asking you to refine with -maxdepth or -name.