Skip to content
DavideLocontePublic

About

A file format that tracks edit to single files.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Filetale

A Rust crate, a Python library, and a CLI for reading and writing .tale files. A .tale file is a custom file format that contains a tree of transactions that represents edits (line insertion, line deletion and text updated) to a textual document.

You can check out a document at any transaction. The main idea is a single-file Git repository. The project tracks file edits made by an LLM agent.

The current version is in development. The API and file format can change.

Quick Start

CLI

Install the CLI from the repository with Rust 1.89 or newer:

cargo install --path . --features cli

To compile it without installing, run:

cargo build --release --features cli
./target/release/tale --help

Tagged releases also provide prebuilt binaries for Linux (x86_64 and arm64), macOS (arm64), and Windows (x86_64) on the GitHub Releases page.

Python

Python 3.10 or newer is supported. Install the published package with:

python -m pip install filetale

Rust

Add the crate to a Rust project with:

cargo add filetale

The CLI is optional. Enable the cli feature when building from the repository. API documentation is available on docs.rs.

Usage

CLI

Create a tale, inspect a snapshot, and record a new version:

tale init document.tale content.txt
tale checkout document.tale <id>
tale commit document.tale --parent <id> updated.txt -m "describe the edit"
tale log document.tale

The add, blame, commands, verify, heads, and prune commands support other workflows. Transaction ids accept an unambiguous prefix. Run tale --help for the complete CLI reference.

Python

import filetale

tale = filetale.Tale.from_text("hello", "seed the document")
next_id = tale.commit(tale.root(), "hello\nworld", message="add a line")
assert tale.checkout(next_id) == ["hello", "world"]

Use TaleReader and TaleWriter for persistent files. See the Python tests for more examples. See the package documentation for error types and configuration options.

Rust

use tale::Tale;

let mut tale = Tale::from_text("hello\nworld", "");
let next = tale.commit(tale.root(), "hello\nthere\nworld", "")?;
assert_eq!(tale.checkout(next)?.lines(), ["hello", "there", "world"]);

See docs.rs for the complete Rust API and examples.

License

MIT — see LICENSE.

AI Disclosure

This project was developed with the assistance of AI. The architecture and design are human.

About

A file format that tracks edit to single files.

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages