git-ofrenda: An Ofrenda for Deleted Code

*# git-ofrenda: An Ofrenda for Deleted Code

GitHub Repository: https://github.com/elonmasai7/git-ofrenda

Run this in any repository that is a few years old:

git log --diff-filter=D --name-only

Every path it prints is a file someone wrote, fixed late at night, and eventually deleted. Git did not forget any of them. It still has who wrote each one, how many times it was touched, and the one-line commit message that ended it.

That felt like the right ghost for this week's theme, so I built something to give them a proper send-off.

What I Built

git-ofrenda is a command-line tool that finds the files a repository has lost and builds an ofrenda for them.

For each deleted file, it works out when it was created, when it was deleted, who worked on it, who removed it and why, and what its last contents were. Then, a model running on your own machine writes the file some last words and a calavera literaria.

There are five commands:

• build generates the ofrenda as a self-contained HTML page, Markdown document, or JSON file.
• seance serves the page locally and lets you chat with individual files using their final contents and Git history.
• scan lists deleted files without requiring a model.
• exhume restores the last contents of deleted files, byte for byte, into a directory.
• doctor checks whether Git and the model server are configured correctly.

How I Read the Theme

An ofrenda is specific. It is the photograph, the favourite food, the marigolds, and a candle for each person. Those details make it an act of remembrance rather than a generic memorial.

A calavera literaria is an affectionate, teasing epitaph in verse associated with the Day of the Dead tradition. I borrowed the shape of these traditions for a programmer's joke, trying to keep the tone fond rather than mocking.

I wanted the verses to know things.

Not just, "Here lies a file. Rest in peace," but a verse about a file that spoke FTP to a partner's server for four years, only to be ended by a commit titled:

remove ftp, partner moved to S3

That is why the model receives the file's actual final contents and its Git history. The tool also extracts concrete details, such as function names, imports, and header comments, for its no-model fallback.

Why Open Models Matter Here

Deleted code is precisely the kind of code you may not want to upload anywhere. It can contain old credentials, internal hostnames, deprecated integrations, and embarrassing workarounds.

Building an ofrenda with a hosted model could mean sending a repository's history to a third party. With an open-weight model, the entire pipeline can stay between Git and a server running on localhost, even without an internet connection.

The design also supports multiple backends, verse caching, and operation without a model. The goal is to keep the project private, flexible, and independent of a single provider.

The Moment It Landed

Things That Went Wrong

The Fallback Was Making Things Up

The first template-generated verses sometimes treated filenames or meaningless comments as important parts of a file's history. Reviewing the output exposed the problem. The templates now mention functions only when they exist and quote header comments only when they contain enough meaningful information. I also added a regression test.

A Git Flag Failed Only on Large Repositories

The pre-ranking step used when many deleted files exist passed --format=@@, which Git interpreted as a named format and rejected.

The issue appeared only when the repository contained more than 60 deleted files. A test that deletes 70 files exposed the bug.

Renames Can Misrepresent a File's History

A file renamed in 2020 and deleted in 2024 can appear to have been created in 2020, even if its history began much earlier.

Using git log --follow helps recover its actual age. The command --diff-filter=D -M also helps distinguish deleted files from files that were simply renamed.

How It Works

The project separates repository analysis, verse generation, and presentation into distinct components.

1. gitscan: Finds deleted files, examines their history, and recovers their final contents from Git.
2. poet: Generates verses by checking the cache, querying the configured model, retrying once if generation fails, and falling back to templates when necessary.
3. render and server: Present the ofrenda as a document or serve it through the local séance interface.

Every verse identifies its source, whether template or the model's name. The page header also reports how many verses were model-generated.

The séance server listens on 127.0.0.1, rejects foreign Host headers, and requires a custom header for POST requests. Repository contents and model-generated output are HTML-escaped before being inserted into the page.

Tests

The project includes 45 tests covering repository analysis, file history, model integration, and HTTP behaviour.

The tests build real Git repositories to exercise deletions, renames, binary files, large numbers of deleted files, model server failures, malformed responses, and HTTP streaming.

Mock Ollama and OpenAI-compatible servers verify that the client follows the expected protocols. These tests provide confidence in the tool's behaviour, but they do not measure poetry quality.

Try It

Repository: github.com/elonmasai7/git-ofrenda

Clone and install the project:

git clone https://github.com/elonmasai7/git-ofrenda.git
cd git-ofrenda
pip install .

If you want to use Ollama, install and start it first, then pull the model:

ollama pull gemma3

Check your environment:

git-ofrenda doctor

Generate an ofrenda or start a local séance:

git-ofrenda build
git-ofrenda seance

Terminal Session

Chatting With a File

Limitations and What's Next

Heavily rewritten files can still look like a death followed by a birth. Only the first 2,500 characters of a file are sent to the model, and smaller models sometimes ignore the requested verse format, causing the tool to fall back to a template.

The next feature I would like to build is a GitHub Action that publishes an ofrenda each year for the files deleted during that year.

It would turn an ordinary maintenance history into a small annual ritual: a chance to revisit the code that once mattered, understand why it disappeared, and remember the work that went into building it.

Final Thoughts

Git is excellent at remembering what happened to a codebase. It records changes, authors, and commit messages with remarkable persistence.

But it does not usually encourage us to stop and reflect on what those changes mean.

git-ofrenda is my attempt to add that missing moment of reflection. It takes something as ordinary as a deleted file and turns its history into a small memorial, using local models to keep the process private and accessible.

Sometimes, even deleted code deserves a proper goodbye.

---

Explore the project on GitHub: https://github.com/elonmasai7/git-ofrenda