searchfs.1

.Dd Jun 7, 2018
.Dt SEARCHFS 1
.Os Darwin
.Sh NAME
.Nm searchfs
.Nd fast filename search on HFS+ and APFS volumes
.Sh SYNOPSIS
.Nm
.Op Fl dfespixnoh
.Op Fl v Ar mount_point
.Ar search_term
.Sh DESCRIPTION
.Nm
searches for files by name on HFS+ and APFS volumes. Searching takes place
at the driver level using the file system catalog via the low-level
searchfs() function. This means the volume's entire directory tree can
be scanned much faster than with a standard recursive directory search
using e.g. find.
.Pp
Paths of files and directories with names containing the search term are
printed to STDOUT, one path per line. Search is case-insensitive by default
.Pp
The following flags are supported:
.Bl -tag -width -indent
.It Fl v, -volume Ar path
Specify volume to search (by mount point). Default is the root file system at /.
.It Fl d, -dirs-only
Return only matching directories.
.It Fl f, -files-only
Return only matching files.
.It Fl e, -exact-match
Return only exact filename matches.
.It Fl s, -case-sensitive
Case sensitive matching.
.It Fl p, -skip-packages
Don't match file system objects that are inside a package. A package is
defined as a directory whose extension matches one of the extensions that
are configured into the kernel by Launch Services.
.It Fl i, -skip-invisibles
Don't match invisible file system objects (that is, objects with the
Finder attribute "Invisible" set) or any objects within invisible directories.
.It Fl x, -skip-inappropriate
Don't match any file system objects that are within an "inappropriate" directory.
Apple's current list of inappropriate directories contains one item: /System.
.It Fl n, -negate-params
List all file system objects that do *not* match the search criteria.
.It Fl l, --limit Ar number
Exit when a certain number of matching items have been found.
.It Fl o, -version
Print program version and exit.
.It Fl h, -help
Print usage and exit.
.El
.Sh EXAMPLES
Find directories with name matching 'something' on root volume:
.Pp
.Dl searchfs -d "something"
.Pp
Find file with the exact name 'file.txt' on volume 'SomeHD':
.Pp
.Dl searchfs -v "/Volumes/SomeHD" -e "file.txt"
.Sh SEE ALSO
.Xr find 1 ,
.Xr locate 1 ,
.Xr mdfind 1 ,
.Xr searchfs 2
.Sh AUTHORS
.An Sveinbjorn Thordarson <sveinbjorn@sveinbjorn.org>