locate(1)

✨ locate(1) ✨

okay so bestie, welcome to the glow-up era of locate(1) — aka plocate, the tool that finds files by name and does it post-haste 🏃♀️💨 (yes that's literally the official tagline, it's giving main character energy fr).

---

🌸 NAME 🌸

plocate — find files by name, post-haste 🦋

---

🎀 SYNOPSIS 🎀

plocate [OPTION]... PATTERN...

---

💖 DESCRIPTION 💖

plocate finds all the files on your system that match the pattern you give it (or all of the patterns, if you handed it more than one 🫶). The way it pulls this off? It reads from an index — one that's made by updatedb(8), or (less commonly, lowkey rare) converted from some other index by plocate-build(8).

Here's the tea: plocate is largely argument-compatible with mlocate(1), but it's significantly faster 🔥. Like, it rarely ever has to scan through its entire database — unless your pattern is super short (less than three bytes 👀) or you're out here wanting a regular expression search. It does not try to maintain compatibility with BSD locate, and it doesn't vibe with non-UTF-8 filenames and locales, sorry not sorry. Most I/O is done asynchronously, but the results get synchronized so your output comes in the same order every time — consistency queen 💅.

When you give it multiple patterns, plocate searches for files that match all of them. And this, bestie, is the main incompatibility with mlocate(1) — because mlocate(1) searches for files matching one or more patterns, unless you pass -A.

By default, patterns are treated as substrings to search for. But! If at least one non-escaped globbing metacharacter shows up (*, ? or []), that pattern gets taken as a glob pattern instead (which means it needs to start and end in * for a substring match). If --regexp is given, patterns become (non-anchored) POSIX basic regular expressions; if --regex is given, they become POSIX extended regular expressions. All of this matches mlocate(1) behavior, no cap.

And just like mlocate(1), plocate shows all the files visible to the calling user (by virtue of having read and execute permissions on all parent directories 🫶) and none that aren't. It does this by running with the setgid bit set to access the index (which is built as root), but it tests visibility as the calling user. Iconic behavior honestly.

---

⭐ EXIT STATUS ⭐

plocate exits with 0 to say a match was found, or that --help or --version were passed. Otherwise it exits with status code 1, meaning an error happened or no matches were found 😭.

---

💅 OPTIONS 💅

• -A, --all — Ignored, purely for compatibility with mlocate(1). It's just there, chilling.
• -b, --basename — Only match against the file name portion of the path name, ie. the directory names get excluded from the match (but they're still printed 💖). This doesn't speed up the search at all, but it can suppress uninteresting matches, which is a vibe check in itself.
• -c, --count — Don't print each match. Instead, count them up and print out a total number at the end 🔢.
• -d, --database DBPATH — Find matches in the given database instead of /var/lib/plocate/plocate.db. You can pass this argument multiple times to search multiple databases 🗂️. You can also put multiple databases in one argument, separated by :. (Any character — including : and \ — can be escaped by prepending a \.)
• -e, --existing — Print only entries that refer to files that actually exist at the time locate is run. Note that unlike mlocate(1), symlinks are not followed by default (and fr, there's no option to change that).
• -i, --ignore-case — Do a case-insensitive match as given by the current locale (the default is a case-sensitive, byte-by-byte match). Heads up though: plocate does not support the full range of Unicode case folding rules — in particular, searching for ß will not give you matches on ss, even in a German locale 🙈. Also note this option is somewhat slower than a case-sensitive match, since it has to generate more candidates for searching the index.
• -l, --limit LIMIT — Stop searching after LIMIT matches have been found. If --count is given, the number printed out will be at most LIMIT.
• -N, --literal — Print entry names without quoting. Normally plocate escapes special characters in filenames so they're safe to consume by typical shells (similar to the GNU coreutils shell-escape-always quoting style), unless it's printing to a pipe — but this option turns off all that quoting.
• -0, --null — Instead of writing a newline after every match, write a NUL (ASCII 0). This is useful for creating unambiguous output when other tools (like xargs(1)) are gonna process it, since filenames are allowed to contain embedded newlines 😳.
• -r, --regexp — Patterns are taken to be POSIX basic regular expressions. See regex(7) for more info. Note that this forces a linear scan through the entire database, which is slow 🐌.
• --regex — Like --regexp, but patterns are instead taken to be POSIX extended regular expressions.
• -w, --wholename — Match against the entire path name. This is the default, so unless -b was given first (see above), it won't do anything. This option exists only for compatibility with mlocate(1).
• --help — Print out usage information, then exit successfully 🫶.
• --version — Print out version information, then exit successfully ✨.

---

🌈 ENVIRONMENT 🌈

• LOCATE_PATH — If given, it's appended after the list of --database paths (whether an explicit one is given or the default is used). Colon-delimiting and character escaping follow the exact same rules as for --database.

---

👑 AUTHOR 👑

Steinar H. Gunderson <steinar+plocate@gunderson.no>

---

🦋 SEE ALSO 🦋

plocate-build(8), mlocate(1), updatedb(8)

---

and that's the whole manual, bestie — no crumbs left behind 🍓

this page came to you from plocate, dated Oct 2020, filed under locate(1) in the General Commands Manual. go forth and find your files, periodt 💜✨