Lolcate

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:

• indexing rules allowing you to easily specify which path names to index and which ones to prune ;
• powerful, UTF8-compliant querying rules ;
• the ability to create multiple databases for multiple purposes.

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.

• The simplest form is just lolcate [--db <dbname>]:

  $ lolcate
  /home/ngirard/Images/DCIM_101CANON/_MG_0006.jpg
  /home/ngirard/Images/DCIM_101CANON/_MG_0007.jpg
  /home/ngirard/Images/DCIM_101CANON/_MG_0004.jpg
  (...)

  When no pattern is given, the query returns everything from the database.

  lolcate --all will return everything from all of your databases.

• We might also want to specify a pattern by running lolcate [--db <dbname>] <pattern>:

  $ lolcate 2018
  /home/ngirard/Images/2018/01/9/IMG_1057.JPG
  /home/ngirard/Images/2018/01/9/IMG_1059.JPG
  /home/ngirard/Images/2018/01/9/IMG_1060.JPG
  (...)

• Patterns are interpreted as regular expressions.

  For instance, let's look for any path names containing either 2018 or 2019:

  $ lolcate 201[89]
  /home/ngirard/Images/2018/01/9/IMG_1057.JPG
  /home/ngirard/Images/2018/01/9/IMG_1059.JPG
  (...)
  /home/ngirard/Images/2019/01/9/IMG_1055.JPG
  /home/ngirard/Images/2019/01/9/IMG_1058.JPG
  (...)

  The complete syntax for the regex engine used by Lolcate is available here.

• Multiple patterns can be specified using lolcate <pattern1> <pattern2> ....

  For instance, let's look for all readme files from the Images directory:

  $ lolcate Images readme
  /home/ngirard/Images/DCIM_101CANON/readme.txt
  /home/ngirard/Images/2019/01/1/Readme
  /home/ngirard/Images/2018/01/1/readme

• The search for patterns is "smart-case" by default. It means that patterns are searched case-insensitively when all in lowercase, and sensitively otherwise.

  For instance, running the latest query with "Readme" instead of "readme" gives:

  $ lolcate Images Readme
  /home/ngirard/Images/2019/01/1/Readme

  We can perform a case-insensitive search using the -i | --case-insensitive option:

  $ lolcate -i Images README
  /home/ngirard/Images/DCIM_101CANON/readme.txt
  /home/ngirard/Images/2019/01/1/Readme
  /home/ngirard/Images/2018/01/1/readme
  /home/ngirard/Documents/READMEs/2018-05-15-Cropping_images.txt
  /home/ngirard/Documents/READMEs/2018-05-15-Cropping_images_fig1.jpg
  /home/ngirard/Documents/READMEs/2018-05-15-Cropping_images_fig2.png

• A pattern can be matched against the base name of path names only, using the -b | --basename option:

  $ lolcate -b images
  /home/ngirard/Documents/READMEs/2018-05-15-Cropping_images.txt
  /home/ngirard/Documents/READMEs/2018-05-15-Cropping_images_fig1.jpg
  /home/ngirard/Documents/READMEs/2018-05-15-Cropping_images_fig2.png

• Path types can be defined and queried for.

  Path types can be defined by adding them to Lolcate's global configuration file. We can locate this file by invoking the --info option:

  $ lolcate --info
  Config file:
  /home/ngirard/.config/lolcate/config.toml
  (...)

  The following path types are predefined:

  [types]
  img = ".*\\.(jp.?g|png|gif|JP.?G)$"
  video = ".*\\.(flv|mp4|mp.?g|avi|wmv|mkv|3gp|m4v|asf|webm)$"
  doc = ".*\\.(pdf|chm|epub|djvu?|mobi|azw3|odf|ods|md|tex|txt)$"
  audio = ".*\\.(mp3|m4a|flac|ogg)$"
  

  these path types can be used in queries:

  $ lolcate --type img cropping
  /home/ngirard/Documents/READMEs/2018-05-15-Cropping_images_fig1.jpg
  /home/ngirard/Documents/READMEs/2018-05-15-Cropping_images_fig2.png

• Path name patterns, base name patterns and type patterns can be mixed altogether:

  $ lolcate --basename [eé]conomie --type doc
  /home/ngirard/Documents/Notes/2018-11-12-Economie_politique.tex
  /home/ngirard/Documents/Notes/2019-01-03-Économie_politique.md

  $ lolcate --basename [eé]conomie --type doc 2018
  /home/ngirard/Documents/Notes/2018-11-12-Economie_politique.tex

Where does Lolcate store its files ?

• the configuration files are stored either in $XDG_CONFIG_HOME/lolcate or in $HOME/.config/lolcate;

• the database files are stored either in $XDG_DATA_HOME/lolcate or in $HOME/.local/share/lolcate.

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:

• The most needed feature is the colored printout of pattern matches (#13).

• Lolcate is not yet useable as a library.

• I'm not satisfied with the ignores rules being kept in a separate configuration file (#14).

• Testing.

  I'd be very interested in advice on existing code I could reuse / take advantage of in order to provide Lolcate with a complete testing bench.

• Backend strategy.

  Lolcate currently stores its data as a lz4-compressed list of path names, and recreates it each time lolcate --update is run. It's as simple as you can get. Although it works well enough for my taste, I'd be glad to consider alternatives (#15).

• Benchmarking

  (#16)

Acknowledgements

• I wish to thank the Rust community for producing such a great developing environment. It's the best environment I've been working with so far !

• A big thanks to Andrew Gallant for his tremendous work and the invaluable crates he wrote, which Lolcate relies upon (regex, ignore, walkdir).

• The approach of simply recreating the database instead of updating it for performance purposes, which Lolcate currently uses, has been discussed multiple times on the Internet. I couldn't find my related notes, so I'd be glad to share any references you could provide.

• The name "lolcate" has already been used for a prototype shell script published as a Github Gist in 2012. It was too good a name to not reusing it !

• Credits for the laughing cat image: Rikki's Refuge