Home

Awesome

Lolcate

Crates.io

A comically fast way of indexing and querying your filesystem. Replaces locate / mlocate / updatedb. Written in Rust.

Lolcate is a fast, lightweight, versatile alternative to locate / mlocate / updatedb.

It features:

Lolcate comes as a single binary executable.

Lolcate doesn't try to be compatible with mlocate / updatedb.

Synopsis

Lolcate operates in two phases:

  1. It indexes parts of your filesystem by obeying some indexing rules you specified to populate one of its databases with the list of matching path names.

    Only the path names of the files are indexed, Lolcate isn't concerned with their contents.

    Different databases can be created for different purposes.

  2. Whenever needed, you can run lolcate to perform queries against its databases and it will return the path names matching the querying rules you specified.

The same lolcate binary executable performs both indexing and querying.

Suggested use

Use shell aliases and functions to query your databases to your liking, e.g.

alias d='lolcate --db documents'

alias zik='lolcate --db music --type audio'
z(){ mpv --playlist <(zik $1); }
zs(){ mpv --playlist <(zik $1|shuf); }

Guide

Creating a database

Before using Lolcate, a database needs to be created. Let's create one:

$ lolcate --create
Created database 'default'.
Please edit:
- the configuration file: /home/ngirard/.config/lolcate/default/config.toml
- the ignores file:       /home/ngirard/.config/lolcate/default/ignores

Since we didn't specify the name of the database, Lolcate chose the name default. We could have specified the name of the database using lolcate --create --db <db_name>.

Indexing rules: specifying what to index

Next, we need to specify what to index by editing two files (this might change in a future version), the config.toml file and the ignores file.

The config.toml file doesn't come empty but filled with boilerplate contents you'll need to customize. It should look like this:

description = ""

# Directories to index.
dirs = [
  # "~/first/dir",
  # "/second/dir"
]

# Set to "Dirs" or "Files" to skip directories or files.
# If unset, or set to "None", both files and directories will be included.
# skip = "Dirs"

# Set to true if you want skip symbolic links
ignore_symlinks = false

# Set to true if you want to index hidden files and directories
ignore_hidden = false

# Set to true to read .gitignore files and ignore matching files
gitignore = false

Let's modify it and add two directories for indexing:

dirs = [
  "~/Images",
  "~/Documents"
]

As you noticed, the directories must be quoted and comma-separated. Also, tildes in directories are expanded, but not environment variables.

We can choose to index only files by setting skip = "Dirs", and only directories by setting skip = "Files". Additionally, symbolic links and hidden files and directories can be skipped by setting ignore_symlinks = true and ignore_hidden = true respectively.

The ignores file contains patterns Lolcate will use to ignore matching path names while indexing the filesystem. The syntax of the ignores file is the same as for the .gitignore files. You can leave it empty if you want to index everything according to the config.toml file.

Let's modify it and add these two patterns:

.git
*~

Indexing the filesystem

Now, we are ready to tell Lolcate to index the filesystem according to the rules we just specified:

$ lolcate --update
Updating default...

Again, Lolcate updates the default database by default. We can choose to update another one by typing lolcate --update --db <other_db>. We can also ask Lolcate to update all the databases we have by typing lolcate --update --all.

Querying a database

Now that our database is populated, we can run queries against it.

Where does Lolcate store its files ?

Differences with mlocate

The following Locate options do not have an equivalent in Lolcate: --count, --existing, --follow, --transliterate, --limit, --nofollow, --null.

Installation

Using the pre-compiled binaries

This is the easiest and recommended way.

Download the latest lolcate pre-compiled binary from Github into a directory belonging to your PATH.

Pre-compiled binaries are available for Linux, MacOS and Windows.

Installation from sources

  1. If needed, install the current stable release of Rust and Cargo using

    $ curl https://sh.rustup.rs -sSf | sh

  2. If needed, add ~/.cargo/bin to your PATH using e.g.:

    $ export PATH=$HOME/.cargo/bin:$PATH

  3. Run

    $ cargo install lolcate-rs

    to compile the sources from the latest release, or

    $ cargo install --git https://github.com/ngirard/lolcate-rs

    to compile the latest version of the sources from the GitHub repository.

Contributing

While all contributions are welcome, the ideal contributions for me would be finely-grained pull requests, as they would allow me to improve my Rust literacy while reviewing them. Thanks in advance !

There are a number of areas you might want to consider contributing to:

Acknowledgements