sortof - sort a directory into a set of directories

sortof is an interactive command-line tool that walks through the files in a messy directory one at a time and lets you file each one into a subdirectory of your choice. It is designed for cleaning out folders like ~/Downloads, where you know roughly where things should go but need to look at each file before deciding.

For every entry, sortof shows you a preview (image, text, table, archive contents, directory listing, or a media player), then asks what to do: skip it, move it to an existing subdirectory, open it, play it, or create a new subdirectory on the fly.

Features

• Interactive single-key workflow. Each entry is shown with a preview and a prompt; one keystroke picks an action and, when moving, a second keystroke picks the destination subdirectory.
• Rich inline previews rendered directly in the terminal:
  • Images (png, jpg, jpeg, gif, webp, avif, tiff, heic, bmp, and more) displayed as sixel graphics via ImageMagick.
  • PDFs previewed as a sixel rendering of the first page.
  • PowerPoint files (.pptx) shown via their embedded thumbnail when available, or as extracted slide text otherwise.
  • Word documents (.docx) shown as the first paragraphs of text.
  • Excel workbooks (.xlsx, .xlsm) and CSV files shown as an aligned table of the first rows and columns.
  • Plain text and Markdown files (.txt, .md, .markdown) shown as the first ten lines.
  • Archives (.zip, .tar.gz, .tar.xz, .tar.bz2) shown as a compact tree of their top-level directories and files.
  • Directories shown as a short listing of their contents with subdirectories highlighted.
• Built-in media playback. Audio and video files (mp3, flac, m4a, opus, mp4, mkv, mov, webm, and more) can be played in place via mpv, with keys to seek forward or stop without leaving sortof.
• Flexible sorting. Entries can be processed in the order they were added to the directory (the default, using the macOS "Date Added" attribute), or by modified, created, or name. Ascending or descending order can be forced with --asc / --desc.
• Size filter. --size skips files (and directories, measured recursively) below a given threshold, with human-friendly units like 5B, 1k, 2 M, or 3 GiB.
• Glob filter. An optional trailing PATTERN argument restricts the session to entries matching a case-insensitive fnmatch glob such as '*.jpg' or 'report-*'.
• On-the-fly directory creation. If none of the existing destination subdirectories fit, you can create a new one from the prompt and the file is moved into it immediately; the new directory becomes a choice for the rest of the session.
• Graceful exit. Pressing Ctrl-C or Ctrl-D at any prompt cleanly ends the session and prints how many files are left in the source directory.

Usage

sortof (1.0)

Clean up some files.

Usage:
    sortof [options] PATH DESTINATION [PATTERN]

Options:
    -h, --help              Display this message.
    --version               Show version information.
    -S SIZE, --size SIZE    Skip files smaller than SIZE (e.g. 5B, 1k, 2 M, 3 GiB).
    -s TYPE, --sort TYPE    Sort by TYPE: added (default), modified, created, name.
    --asc                   Sort in ascending order.
    --desc                  Sort in descending order.

PATTERN is an optional case-insensitive fnmatch glob (e.g. '*.jpg') that
restricts which entries are shown.

sortof takes a source PATH to clean up and a DESTINATION directory whose immediate subdirectories are the buckets you can move files into. An optional PATTERN argument filters which entries are considered.

For each entry that passes the size and pattern filters, sortof prints a preview and then shows a prompt like:

[Skip,Move,Open,Play,Create,?]

Type the first letter of an action (case-insensitive) and press Enter:

• Skip — leave the file alone and move to the next entry. Type s to skip. Note that the default action (when you just press Enter) is Play for audio/video files and Open for everything else, so pressing Enter previews the file rather than skipping it.
• Move — file the entry into one of the destination subdirectories. sortof shows a second prompt listing every subdirectory of DESTINATION (plus ! to abort the move); pick one by its first letter and the entry is renamed into that directory. You can also type both letters at once, e.g. md to move to a directory starting with d.
• Open — open the file with the system default application (open on macOS) and return to the same prompt so you can decide what to do next.
• Play — only offered for audio and video files. Launches mpv in the background and hands the terminal a small control surface:
  • f or n — seek forward by 10 seconds.
  • x or Esc — stop playback and return to the prompt.
• Create — type a new subdirectory name; sortof creates it under DESTINATION, moves the current entry into it, and adds it to the list of move targets for the rest of the session.
• ? — print a short description of each available choice.

Press Ctrl-C or Ctrl-D at any prompt to end the session early. sortof will print how many files remain in the source directory before exiting.

Installation

sortof is a Python package. From a checkout of this repository:

pip install .

The sortof command will then be on your PATH.

External tools used for previews and playback are optional but strongly recommended:

• ImageMagick (magick) — image, PDF, and PowerPoint thumbnail previews as sixel graphics. Your terminal also needs to support sixel output (e.g. recent iTerm2, WezTerm, or xterm with sixel enabled).
• mpv — audio and video playback from the Play action.

On macOS both can be installed via Homebrew:

brew install imagemagick mpv

sortof currently relies on macOS-specific APIs (NSURL and the "Date Added" attribute) for the default sort order, so it is primarily tested on macOS.

Development

Clone the repository and install it in editable mode so changes to the source are picked up immediately:

git clone <repo-url> sortof
cd sortof
pip install -e .

The entire tool lives in a single file, src/sortof/sortof.py, which is deliberately kept dependency-light and script-like so it is easy to read and hack on.

Articles

• Implementing Undo with Python and Group Theory

Copyright

Copyright © Michał Moroz <michal@makimo.pl>. Released under the MIT License; see the LICENSE file (or the License :: OSI Approved :: MIT License classifier in setup.py) for details.