Skip to content

README.org

Latest commit

 

History

History
101 lines (70 loc) · 3.91 KB

README.org

File metadata and controls

101 lines (70 loc) · 3.91 KB
Raw

gnaw.el — GNAW is Not Another Workflow

3==3      <= A gnawed bone.

https://img.shields.io/badge/status-active-brightgreen.svg?style=for-the-badge https://img.shields.io/badge/versioning-intver.org-blue.svg?style=for-the-badge

gnaw.el lets you browse and manage BONE reports from Emacs.

BONE (Backlog Of Notable Emails) is a bug tracker that never asks anyone to file a bug: it watches a project’s mailing list, turns the mails tagged [BUG], [PATCH] or [FR] into reports, updates them from the replies, and publishes the result as plain reports.json files anyone can fetch (no web forms, no accounts). The essay The issue with issue trackers explains the rationale.

M-x gnaw lists the reports of the sources you follow and makes it easy to search them, to read the associated emails, to view or apply patches and attachments, and to organize your work with local sticky and dismiss marks.

It is also the data layer shared by mail front-ends like gnus-gnaw, notmuch-gnaw and mu4e-gnaw.

gnaw.png

Installation

gnaw.el requires Emacs 28.1 or later.

gnaw.el is not on MELPA yet. On Emacs 30 or later, install it straight from its git repository with the built-in package-vc; the :doc spec also builds and installs the Info manual (C-h i m gnaw RET):

(use-package gnaw
  :init
  (unless (package-installed-p 'gnaw)
    (package-vc-install
     '(gnaw :url "https://codeberg.org/bzg/gnaw.el"
            :doc "doc/gnaw.org"))))

You need the :init form because the :vc keyword of use-package does not support :doc. Interactively, without the manual:

M-x package-vc-install RET https://codeberg.org/bzg/gnaw.el RET

Update later with M-x package-vc-upgrade RET gnaw RET.

Getting started

M-x gnaw opens the *gnaw* report browser. With no source configured, it runs the full interactive setup, asking for a source URL, one or more local git repositories where its patches apply, and how to open report mail; M-x gnaw-configure reruns it later on.

In the browser, h (or ?) lists all the key bindings; / filters the list with key:value tokens. Each launch displays a tip presenting a random command; set gnaw-inhibit-startup-tip to a non-nil value to disable it.

Documentation

The Gnaw manual covers everything else: the report browser and its key bindings, the search query language, reading messages, applying patches, config.edn, all the options and the API for front-ends.

Build it as Info or PDF from the top of the repository:

make info
make pdf

Building the manual needs Emacs 29 or later (the export relies on Org 9.6), makeinfo for the Info output and texi2pdf for the PDF.

Contributing

  • Send a bug report with [BUG] gnaw.el: <SHORT EXPLICIT BUG DESCRIPTION>
  • Send a patch with [PATCH] gnaw.el: <COMMIT SUMMARY>
  • Send a feature request with [FR] gnaw.el: <FEATURE REQUEST>
  • Share any <a href=”mailto:~bzg/boneyard@lists.sr.ht “>other question or idea

You can also send me an email and support my work on liberapay.

Intentional Versioning

This project uses Intentional Versioning, with three audiences:

  • x: end users
  • y: indirect users, via the front-ends
  • z: contributors to the codebase

License

Copyright © 2026 Bastien Guerry

You can redistribute gnaw.el and/or modify it under the terms of the GNU General Public License, either version 3 of the License, or (at your option) any later version.