`fabricatio-checkpoint`

MIT Python Versions

Worktree checkpointing via shadow Git repositories for fabricatio workflows. Save, diff, rollback individual files, or reset entire directories — without interfering with any existing Git repository.

Installation

pip install fabricatio[checkpoint]

For a full installation with all fabricatio components:

pip install fabricatio[full]

Overview

fabricatio-checkpoint maintains a bare Git shadow repository for each tracked worktree directory. It stages and commits file changes behind the scenes, enabling:

Checkpoints — save worktree state at any point with a message
Selective rollback — restore individual files to a previous commit without touching others
Full reset — revert the entire worktree to a prior checkpoint
Diffs — retrieve file-level changes between any commit and the current state
Status — list modified, added, or deleted files since the last checkpoint

The shadow repositories live under ~/.fabricatio-checkpoint/ by default and never touch any existing .git directory.

Key Types

`CheckpointService`

Manages the lifecycle of shadow repositories. Created once per process via the singleton helper.

Method	Description
`get_store(worktree_dir)`	Returns the `CheckPointStore` for a directory (creates on first access)
`workspaces()`	Lists all tracked worktree directories
`prune_invalid()`	Removes stores whose worktrees no longer exist on disk

from fabricatio_checkpoint.inited_service import get_checkpoint_service

svc = get_checkpoint_service()
store = svc.get_store("/path/to/project")

`CheckPointStore`

A shadow repository bound to one worktree directory. Backed by a bare Git repo (Rust implementation via PyO3).

Method	Description
`save(commit_msg=None)`	Stage all changes and commit. Returns the commit OID.
`head()`	Returns the OID of the current HEAD commit.
`commits()`	Returns all commit OIDs in chronological order.
`reset(commit_id)`	Restore the entire worktree to a given commit.
`rollback(commit_id, file_path)`	Restore a single file from a commit.
`get_file_diff(commit_id, file_path)`	Returns the unified diff for a file at a commit.
`get_status()`	Lists changed files since HEAD (staged + unstaged).

store = svc.get_store("/path/to/project")

cid = store.save("snapshot before refactor")
store.rollback(cid, "src/main.py")
store.reset(cid)
print(store.get_file_diff(cid, "src/main.py"))

`Checkpoint` (Capability Mixin)

A UseLLM-compatible mixin for use within fabricatio agent roles.

Method	Description
`save_checkpoint(msg)`	Save current state with a message
`rollback(commit_id, file_path)`	Restore one file to a previous commit
`reset_to_checkpoint(commit_id)`	Reset entire worktree to a commit
`get_file_diff(commit_id, file_path)`	Diff one file against a commit
`mount_checkpoint_store(store)`	Attach a specific store (defaults to worktree_dir)
`unmount_checkpoint_store()`	Detach the current store

from fabricatio_checkpoint.capabilities.checkpoint import Checkpoint

class MyAgent(Checkpoint, SomeLLMRole):
    worktree_dir = Path("/path/to/project")

agent = MyAgent().mount_checkpoint_store()
cid = agent.save_checkpoint("before editing")
agent.rollback(cid, "config.toml")

`prune_stores(stores_root)`

Free function: deletes shadow repositories under stores_root whose worktree directories no longer exist.

from fabricatio_checkpoint.rust import prune_stores

prune_stores(Path.home() / ".fabricatio-checkpoint")

CLI

The package ships a ckpt command (requires pip install fabricatio-checkpoint[cli]):

ckpt --workspace /path/to/project save "checkpoint message"
ckpt --workspace /path/to/project reset <commit_id>
ckpt --workspace /path/to/project diff
ckpt --workspace /path/to/project ls
ckpt workspaces

Configuration

All options below are read through the fabricatio configuration chain (see the Configuration Guide). Set them under the [ext.checkpoint] table in fabricatio.toml, equivalently under [tool.fabricatio.ext.checkpoint] in pyproject.toml, or via FABRICATIO_EXT__CHECKPOINT__<FIELD_UPPER> environment variables.

[ext.checkpoint]
checkpoint_dir = "~/.fabricatio-checkpoint"
cache_size = 100

Option	Type	Default	Description
`checkpoint_dir`	`Path`	`~/.fabricatio-checkpoint`	Directory to store checkpoints. Aka the shadow repositories.
`cache_size`	`int`	`100`	Maximum number of checkpoints to keep in memory.

Access at runtime: from fabricatio_checkpoint.config import checkpoint_config.

Dependencies

fabricatio-core — core interfaces and config system

No additional Python dependencies required for basic use. The optional [cli] extra adds typer.

License

MIT — see LICENSE

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

fabricatio_checkpoint-0.3.6-cp314-cp314-win_amd64.whl (2.4 MB view details)

Uploaded Aug 23, 2026 CPython 3.14Windows x86-64

fabricatio_checkpoint-0.3.6-cp314-cp314-manylinux_2_34_x86_64.whl (2.4 MB view details)

Uploaded Aug 23, 2026 CPython 3.14manylinux: glibc 2.34+ x86-64

fabricatio_checkpoint-0.3.6-cp314-cp314-manylinux_2_34_aarch64.whl (2.2 MB view details)

Uploaded Aug 23, 2026 CPython 3.14manylinux: glibc 2.34+ ARM64

fabricatio_checkpoint-0.3.6-cp314-cp314-macosx_11_0_arm64.whl (2.2 MB view details)

Uploaded Aug 23, 2026 CPython 3.14macOS 11.0+ ARM64

fabricatio_checkpoint-0.3.6-cp313-cp313-win_amd64.whl (2.4 MB view details)

Uploaded Aug 23, 2026 CPython 3.13Windows x86-64

fabricatio_checkpoint-0.3.6-cp313-cp313-manylinux_2_34_x86_64.whl (2.4 MB view details)

Uploaded Aug 23, 2026 CPython 3.13manylinux: glibc 2.34+ x86-64

fabricatio_checkpoint-0.3.6-cp313-cp313-manylinux_2_34_aarch64.whl (2.2 MB view details)

Uploaded Aug 23, 2026 CPython 3.13manylinux: glibc 2.34+ ARM64

fabricatio_checkpoint-0.3.6-cp313-cp313-macosx_11_0_arm64.whl (2.2 MB view details)

Uploaded Aug 23, 2026 CPython 3.13macOS 11.0+ ARM64

fabricatio_checkpoint-0.3.6-cp312-cp312-win_amd64.whl (2.4 MB view details)

Uploaded Aug 23, 2026 CPython 3.12Windows x86-64

fabricatio_checkpoint-0.3.6-cp312-cp312-manylinux_2_34_x86_64.whl (2.4 MB view details)

Uploaded Aug 23, 2026 CPython 3.12manylinux: glibc 2.34+ x86-64

fabricatio_checkpoint-0.3.6-cp312-cp312-manylinux_2_34_aarch64.whl (2.2 MB view details)

Uploaded Aug 23, 2026 CPython 3.12manylinux: glibc 2.34+ ARM64

fabricatio_checkpoint-0.3.6-cp312-cp312-macosx_11_0_arm64.whl (2.2 MB view details)

Uploaded Aug 23, 2026 CPython 3.12macOS 11.0+ ARM64

File details

Details for the file fabricatio_checkpoint-0.3.6-cp314-cp314-win_amd64.whl.

File metadata

Download URL: fabricatio_checkpoint-0.3.6-cp314-cp314-win_amd64.whl
Upload date: Aug 23, 2026
Size: 2.4 MB
Tags: CPython 3.14, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for fabricatio_checkpoint-0.3.6-cp314-cp314-win_amd64.whl
Algorithm	Hash digest
SHA256	`824c2a5f0c733846885381d4b0dfe2313eba51b144ee3ca46badce4bc62a4ff6`
MD5	`5a953027885d61d011a94763a03d319c`
BLAKE2b-256	`6010b4c9804997bdd841bf32cc57955aa4cc656c97ea3934c4630e09c401e61c`

See more details on using hashes here.

File details

Details for the file fabricatio_checkpoint-0.3.6-cp314-cp314-manylinux_2_34_x86_64.whl.

File metadata

Download URL: fabricatio_checkpoint-0.3.6-cp314-cp314-manylinux_2_34_x86_64.whl
Upload date: Aug 23, 2026
Size: 2.4 MB
Tags: CPython 3.14, manylinux: glibc 2.34+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for fabricatio_checkpoint-0.3.6-cp314-cp314-manylinux_2_34_x86_64.whl
Algorithm	Hash digest
SHA256	`3a329d867b1e1ae497def906aa6c144590d88f963d2a4b7e4a5cdc01eaf72181`
MD5	`4a9e8c0c97232c2d56f0ee38fe95dfb6`
BLAKE2b-256	`59d34f7a4dc6a6acf87c488911fa109450555c1c00645acb63cd2868be9f2395`

See more details on using hashes here.

File details

Details for the file fabricatio_checkpoint-0.3.6-cp314-cp314-manylinux_2_34_aarch64.whl.

File metadata

Download URL: fabricatio_checkpoint-0.3.6-cp314-cp314-manylinux_2_34_aarch64.whl
Upload date: Aug 23, 2026
Size: 2.2 MB
Tags: CPython 3.14, manylinux: glibc 2.34+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for fabricatio_checkpoint-0.3.6-cp314-cp314-manylinux_2_34_aarch64.whl
Algorithm	Hash digest
SHA256	`c8e264d248b1d05a4158f91390a2503060121948dae867f95ad90474e71214cb`
MD5	`2e89ddb3079daa5c6905ce5d66974a4d`
BLAKE2b-256	`d6ff0b5c24ec38908a46dd7e55ece7e99c7e18f9ad0602ecca6e390a1285340c`

See more details on using hashes here.

File details

Details for the file fabricatio_checkpoint-0.3.6-cp314-cp314-macosx_11_0_arm64.whl.

File metadata

Download URL: fabricatio_checkpoint-0.3.6-cp314-cp314-macosx_11_0_arm64.whl
Upload date: Aug 23, 2026
Size: 2.2 MB
Tags: CPython 3.14, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for fabricatio_checkpoint-0.3.6-cp314-cp314-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`7e2cbbb23dd7d6cf30d090344920b7217afd6d91108a2bc7905507dc8b415754`
MD5	`45417d03b038b3828d50a1004884780a`
BLAKE2b-256	`f4f4988326f07039038c5f3d0bac8ec691ab52425c606c3e7192e7191b04e13d`

See more details on using hashes here.

File details

Details for the file fabricatio_checkpoint-0.3.6-cp313-cp313-win_amd64.whl.

File metadata

Download URL: fabricatio_checkpoint-0.3.6-cp313-cp313-win_amd64.whl
Upload date: Aug 23, 2026
Size: 2.4 MB
Tags: CPython 3.13, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for fabricatio_checkpoint-0.3.6-cp313-cp313-win_amd64.whl
Algorithm	Hash digest
SHA256	`217174b4c3b412a9f84424326b6c437064eadcfab9221f99440a943a4977c2d8`
MD5	`a0726d657241b2c29b5399d8b92a756c`
BLAKE2b-256	`0933598ab7d74a370f7b60e6931897c62c9c1456950bdf1e83c80e2e0f7975dd`

See more details on using hashes here.

File details

Details for the file fabricatio_checkpoint-0.3.6-cp313-cp313-manylinux_2_34_x86_64.whl.

File metadata

Download URL: fabricatio_checkpoint-0.3.6-cp313-cp313-manylinux_2_34_x86_64.whl
Upload date: Aug 23, 2026
Size: 2.4 MB
Tags: CPython 3.13, manylinux: glibc 2.34+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for fabricatio_checkpoint-0.3.6-cp313-cp313-manylinux_2_34_x86_64.whl
Algorithm	Hash digest
SHA256	`18b469a73d180f08e23ae28ad401f60f131c9fd022e34716c14b01ab64311076`
MD5	`2094e7fe88397d71b7ce6d3af696f594`
BLAKE2b-256	`66dfc15e3ede2ec1754df8e979d1b6e697b58b6d06bb2285c259e2635a50e0ab`

See more details on using hashes here.

File details

Details for the file fabricatio_checkpoint-0.3.6-cp313-cp313-manylinux_2_34_aarch64.whl.

File metadata

Download URL: fabricatio_checkpoint-0.3.6-cp313-cp313-manylinux_2_34_aarch64.whl
Upload date: Aug 23, 2026
Size: 2.2 MB
Tags: CPython 3.13, manylinux: glibc 2.34+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for fabricatio_checkpoint-0.3.6-cp313-cp313-manylinux_2_34_aarch64.whl
Algorithm	Hash digest
SHA256	`aea0a33726c31306d1c03fc4fe82018dd0d2359fa3e758b227e7b1c22c2650ad`
MD5	`15dd8d1b7969feb1e4975be105525781`
BLAKE2b-256	`4968a15c7fa1eb1eabcc076b0c95da41ced72f86d2a4d2fe178fb2713626a3bb`

See more details on using hashes here.

File details

Details for the file fabricatio_checkpoint-0.3.6-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

Download URL: fabricatio_checkpoint-0.3.6-cp313-cp313-macosx_11_0_arm64.whl
Upload date: Aug 23, 2026
Size: 2.2 MB
Tags: CPython 3.13, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for fabricatio_checkpoint-0.3.6-cp313-cp313-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`e1439e0e190110cc66e10578110bd3b605656ddf654525aabf4e0b88e2220216`
MD5	`7eda3ec3bf67edffd648591534649ecc`
BLAKE2b-256	`c822be01f1c2fdf0b5a095d55a6067256ac809c2a94ee53d474acc4084f7a0de`

See more details on using hashes here.

File details

Details for the file fabricatio_checkpoint-0.3.6-cp312-cp312-win_amd64.whl.

File metadata

Download URL: fabricatio_checkpoint-0.3.6-cp312-cp312-win_amd64.whl
Upload date: Aug 23, 2026
Size: 2.4 MB
Tags: CPython 3.12, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for fabricatio_checkpoint-0.3.6-cp312-cp312-win_amd64.whl
Algorithm	Hash digest
SHA256	`1fcb7e8f0f4288471181dacbb01434ec99c390e4008e7ccd126b505e93be917a`
MD5	`f948a73f9ab66b2710ab2d81269dbaf7`
BLAKE2b-256	`ae18bcf01f9e50dce8cbe042a9009a1763432b9da2821cf76b145747d2347f16`

See more details on using hashes here.

File details

Details for the file fabricatio_checkpoint-0.3.6-cp312-cp312-manylinux_2_34_x86_64.whl.

File metadata

Download URL: fabricatio_checkpoint-0.3.6-cp312-cp312-manylinux_2_34_x86_64.whl
Upload date: Aug 23, 2026
Size: 2.4 MB
Tags: CPython 3.12, manylinux: glibc 2.34+ x86-64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for fabricatio_checkpoint-0.3.6-cp312-cp312-manylinux_2_34_x86_64.whl
Algorithm	Hash digest
SHA256	`d174543945631768a1aac66d5a511535ac6428f138290577e7efb74db9814478`
MD5	`80c6a40eec6fbef0ac214913eed4b8e0`
BLAKE2b-256	`36a42b6df9f4b44b834ff84e3245a7edfa3cfb135fb74b9bea6574f95fc94db9`

See more details on using hashes here.

File details

Details for the file fabricatio_checkpoint-0.3.6-cp312-cp312-manylinux_2_34_aarch64.whl.

File metadata

Download URL: fabricatio_checkpoint-0.3.6-cp312-cp312-manylinux_2_34_aarch64.whl
Upload date: Aug 23, 2026
Size: 2.2 MB
Tags: CPython 3.12, manylinux: glibc 2.34+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for fabricatio_checkpoint-0.3.6-cp312-cp312-manylinux_2_34_aarch64.whl
Algorithm	Hash digest
SHA256	`11aa31e3255e1fa9c558fad48485b5dc36ad2adfd5ce748de21ab1a471e93553`
MD5	`1054c29bf02b33c33e16dc9e3fae8f9b`
BLAKE2b-256	`0647302a6015a46854caf9ec721b73e4c10b328b8465c7b0a5108c7d7031f76a`

See more details on using hashes here.

File details

Details for the file fabricatio_checkpoint-0.3.6-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

Download URL: fabricatio_checkpoint-0.3.6-cp312-cp312-macosx_11_0_arm64.whl
Upload date: Aug 23, 2026
Size: 2.2 MB
Tags: CPython 3.12, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for fabricatio_checkpoint-0.3.6-cp312-cp312-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`156c121e5c57291f2a7426129d1728831a8515efab2ccd0e0e91f03fe73a2c9d`
MD5	`3d5095260bd3d09009645125abc87abb`
BLAKE2b-256	`e6314d5e1ed52e1d11faa1d31d45fa862052dab57c9bfd489f0758c6e1890555`