{"id":15724025,"url":"https://github.com/tbrk/muttlight","last_synced_at":"2025-05-13T10:29:44.745Z","repository":{"id":74195506,"uuid":"100703905","full_name":"tbrk/muttlight","owner":"tbrk","description":"Search and preview for MailDir files on MacOS","archived":false,"fork":false,"pushed_at":"2017-09-01T07:22:24.000Z","size":912,"stargazers_count":15,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-01T06:34:02.904Z","etag":null,"topics":["email","macos","maildir","mutt","quicklook-plugin","spotlight-plugin"],"latest_commit_sha":null,"homepage":"http://www.tbrk.org/software/muttlight.html","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tbrk.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-18T11:02:11.000Z","updated_at":"2024-03-24T11:49:43.000Z","dependencies_parsed_at":"2023-03-23T02:17:42.252Z","dependency_job_id":null,"html_url":"https://github.com/tbrk/muttlight","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbrk%2Fmuttlight","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbrk%2Fmuttlight/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbrk%2Fmuttlight/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbrk%2Fmuttlight/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tbrk","download_url":"https://codeload.github.com/tbrk/muttlight/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249977370,"owners_count":21354857,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["email","macos","maildir","mutt","quicklook-plugin","spotlight-plugin"],"created_at":"2024-10-03T22:14:22.789Z","updated_at":"2025-04-20T23:30:44.736Z","avatar_url":"https://github.com/tbrk.png","language":"C","readme":"Muttlight\n=========\n\n![Muttlight Logo](src/Assets.xcassets/AppIcon.appiconset/icon_128x128.png)\n\nMuttlight is a MacOS application that improves search and preview for email \nfiles stored in [MailDir](http://cr.yp.to/proto/maildir.html) format.\nSpecifically, it allows the associated file extensions to be specified and \nregistered via a graphical user interface, provides a Spotlight importer to \nextract meta data, integrates with Quick Look to provide previews and \nthumbnails, and allows files to be opened directly in Mutt.\n\nMuttlight Launcher was created with Sveinbjörn Þórðarson's\n[Platypus](http://sveinbjorn.org/platypus) application. It responds to \n‘open’ requests on MailDir messages by running a simple (naive) shell script \nto launch an [Iterm2](https://www.iterm2.com) session, or failing that, a \nnative Terminal session, with Mutt open on the selected message.\n\n[Documentation is available elsewhere.](http://www.tbrk.org/software/muttlight.html)\n\n**Pull requests are welcome.**\n\n## Building Muttlight\n\n1. Install prerequisites\n```\nbrew install gettext\nbrew install ncurses\n```\n\n2. Clone (or link) the Mutt source code into a `src/mutt` subdirectory\n```\nwget -qO- ftp://ftp.mutt.org/pub/mutt/mutt-1.8.3.tar.gz \\\n  | tar xvz -C ./src \u0026\u0026 ln -s mutt-1.8.3 src/mutt\n```\n\n3. Build Mutt\n```\n(cd src/mutt \u0026\u0026 ./configure \u0026\u0026 make)\n```\n\n4. Build Muttlight\n```\ncd src\nmake\n```\n\nInstall Muttlight simply by copying the Muttlight.app bundle (directory) to \n`$HOME/Applications`.\n\nBackground\n----------\n\n### Problem\n\n[Mutt](http://www.mutt.org) is a text-based email client that works as well \nin a terminal on MacOS as on any other system. It provides an efficient, \nconfigurable, programmable, and keyboard-only interface, seamless \nintegration of powerful texts editors like [Vim](http://www.vim.org), and a \nnon-vendor-specific and easy-to-synchronize storage format, namely \nindividual MIME files in [MailDirs](https://en.wikipedia.org/wiki/Maildir).\n\nUnfortunately, mail messages stored in MailDir format are not well \nintegrated into the MacOS search (Spotlight) and preview (Quick Look) \nfeatures. Mails appear in Spotlight results, since they are indexed, but \ntheir encoded filenames are all but unreadable and their contents are not \ndisplayed. Renaming these files to have the `.eml` extension causes them to \nbe properly indexed, displayed, and previewed by exploiting plugins in the \nnative Mail application. But, this violates the MailDir format and renders \nthe files unreadable by Mutt and similar applications.\n\nTwo possible solutions suggest themselves.\n\n1. Introduce a version of the MailDir specification that requires `.eml` \n   extensions and modify Mutt and similar applications accordingly.\n\n2. Somehow get the Mail application to also index these MailDir files \n   without renaming them.\n\nThe first solution is possible since Mutt is open-source software, but it \neither complicates system configuration, since Mutt must be installed with \npatches, or requires upstream acceptance of the patches. It would, \nfurthermore, be necessary to patch mail delivery agents like \n[fetchmail](http://www.fetchmail.info) and \n[postfix](http://www.postfix.org). But, is it reasonably for a relatively \nminor issue on a particular operating system to spread to such long-standing \nand widely-used pieces of software?\n\nThe second solution would be ideal, but unfortunately I was not able to make \nit work. I tried registering file extensions in the finder, with the \n[duti](http://duti.org) application, and using the `UTTypeConformsTo` \nfeature of MacOS applications. The Mail application is closed source and so \nit is not possible to investigate it directly or to patch it. If you know \nhow to do this or you work for Apple and can influence the application, \nplease [contact me](mailto://tim@tbrk.org)! I would be very pleased to make \nMuttlight redundant by finding a better solution to the problem described \nabove.\n\n### Solution\n\nMuttlight represents a third solution: an application that registers itself \nas the owner of MailDir files and leverages Mutt's source code to improve \ntheir integration into the MacOS search and preview features.\n\nA filename in the [MailDir format](https://cr.yp.to/proto/maildir.html) ends\nwith a suffix of the form `:2,DFPRST`, where the six final letters are flags \nthat are either present or absent (giving 64 different combinations). Since \nfile extensions on MacOS begin with a `.`, it is also necessary to consider \nthe characters to the left of the suffix. They are sometimes `mbox`, but \nmore often they are (part of) the host name on which the file was originally \ncreated (to ensure distinct names across multiple systems). Files in the \n`new` subdirectory are named without a `:2,DFPRST` suffix but usually \ninclude a host name. Obviously, the host name extensions will vary across \ninstallations. Muttlight provides a GUI that searches the system for MailDir \nfiles, summarizes the extensions that are being used, and allows users to \nselect those which should be treated. Note that the \n[DoveCot](https://wiki2.dovecot.org/MailboxFormat/Maildir) version of the \nMailDir scheme cannot be handled since it embeds file size information in \nthe extension.\n\nOnce the MailDir filename ‘extensions’ have been registered to the Muttlight \nfile type (`org.tbrk.muttlight.email`), the system will rely on Muttlight to \nextract metadata and provide preview images. Both features are provided by \nplugins that exploit the existing Mutt source code to parse and display mail \nmessages.\n\nMetadata is extracted from the mail header and any plain text, html, or \nenriched parts. Attachment names are indexed, but not their contents.\nThe various parts are decoded before being indexed. This should improve the \nquality of search results, particularly for emails in character sets other \nthan ASCII. I do not know whether the Mail application indexes mail \nattachments but this seems difficult to achieve using the public Spotlight \ninterfaces (since it would be necessary to recursively call other importer \nplugins).\n\nThe Quick Look plugin exploits (...hacks around...) the Mutt pager to give \npreviews that, while not as elegant as the native Mail ones, closely \nresemble the text-based display in the Mutt client. This style may even be \npreferable to some users. Rudimentary parsing is applied to colorize the \nheader fields, attachment status lines, and quoted replies.\n\nAltogether, these features, together with the Mutt Launcher component, allow \na rapid configuration and natural integration of MailDir contents into the \nMacOS user interface.\n\n### Other Solutions\n\nThere are, of course, other ways to index and search mail messages in \nMailDir format. For instance, I already use \n[mairix](http://www.rpcurnow.force9.co.uk/mairix/) on both MacOS and Linux, \nand it works well once you get the hang of it. It has the advantage of \nworking specifically with mail files and of showing the results directly \nwithin Mutt.\n\nThe advantage of Spotlight is that the indexes are kept up-to-date more \ndynamically and they span all files and file types on a system. Muttlight \nallows more convenient browsing of mail messages when they come up amongst \nother results (pdfs, text files, source code, etcetera).\n\nDebugging\n---------\n\nRun `mdimport -L` to see the list of installed Spotlight plugins.\nThe list should include \n`.../muttlight.app/Contents/Library/Spotlight/muttlight.mdimporter`.\n\nRun `mdls` on a MailDir file to check that the plugin is working correctly.\nThe `kMDItemContentType` field should be `org.tbrk.muttlight.email` and the \nother fields (`kMDItemAuthors`, `kMDItemDisplayName`, etcetera) should be \nvalid. To log the importing process and to see whether the plugin is being \ncalled, run `mdimport -d 4 \u003cfilename\u003e`.\n\nRun `qlmanage -m | egrep --color '.*muttlight.*|$` to see the list of \ninstalled Quick Look plugins (and to highlight the muttlight entry).\nThe list should include\n`org.tbrk.muttlight.email -\u003e .../muttlight.app/Contents/Library/QuickLook/muttlight.qlgenerator`.\nIt may be necessary to reset the plugin manager by running `qlmanage -r` \n(and `qlmanage -r cache`).\n\nOpen a MailDir directory in Finder to check that thumbnails are being \ngenerated correctly, press `⌘-Y` to preview a file. The thumbnails and \npreviews should show the messages more or less as they appear in mutt.\n\nThe Quick Look plugin can be debugged by running\n`qlmanage -d 4 -p \u003cfilename\u003e`. This will show detailed logging. There may be \na delay before the preview is displayed. Add `-o .` to the command line to \ndump the generated files to disk.\n\nRun `mdfind \u003ckeywords\u003e` to list indexed files that contain the given \nkeywords. Entering the same keywords into the Spotlight search box \n(`⌘-Space`) should display the same list. When muttlight is functioning \ncorrectly, any mail files in the search results are named according to their \nsubject (and not their MailDir filename) and their contents should be \npreviewed as in the mutt pager. It will probably be necessary to \n[reindex](https://support.apple.com/en-us/HT201716) your MailDir directories \nbefore the search results are named correctly (the `mds` and `mds_stores` \nprocesses become active during reindexing).\n\nThe following command deletes and regenerates the Spotlight index on the \nroot volume (regeneration may take some time).\n\n```\nsudo mdutil -E /\n```\n\nRun the following command and search for `muttlight` to see registered file \nextensions and plugin “claims”.\n\n```\n/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Versions/A/Support/lsregister -dump | less\n```\n\nReset the entire Launch Services database:\n\n```\n/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -kill -r -domain local -domain system -domain user\n```\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftbrk%2Fmuttlight","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftbrk%2Fmuttlight","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftbrk%2Fmuttlight/lists"}