btrfs-timeline 0.1.0__tar.gz

btrfs_timeline-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.coverage
+htmlcov/
+*.log
+
+# uv が開発用に生成するロックファイル (ライブラリなので固定しない)
+uv.lock

btrfs_timeline-0.1.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-23
+
+First public release. Nothing here is a change from an earlier version; this is what the
+release contains.
+
+### Browsing history
+
+- Snapshot discovery for the snapper layout (`<mount>/.snapshots/<N>/snapshot` with
+  `info.xml`) and for the flat layouts used by btrbk, Timeshift and manual setups. It
+  reads `/proc/self/mountinfo` and walks directories rather than calling
+  `btrfs subvolume list`, which requires root — so **browsing history does not**.
+- File version history, deduplicated by mtime and size, keeping the periods when a file
+  did not exist as entries of their own. Copy-on-write means an unchanged file otherwise
+  appears once per snapshot.
+- Directory history, and listing a directory as it stood at a point in time. Entries
+  deleted since then show up there, which is the only way to reach them — the current
+  filesystem no longer has them — and their own history and restore work as usual from
+  that point. Directory versions come from the directory's mtime, so they mark when
+  entries came and went, not when a file inside was edited.
+- Diffs between a version and the current file, or between any two versions.
+
+### Restoring
+
+- `restore` brings a version back with the `FICLONE` ioctl, sharing extents with the
+  snapshot: instant regardless of size, no extra space, falling back to a plain copy
+  elsewhere and reporting which happened.
+- Non-destructive by default: the recovered version is written beside the original as
+  `notes.<timestamp>.md`. `--in-place` overwrites, and even then the current content is
+  kept as a backup unless `--no-backup --force`.
+- Writes go through a temporary file in the destination directory and `rename(2)`, so an
+  interrupted restore leaves no partial file. Symlinks are recreated as symlinks; the
+  target is resolved with realpath, so restoring a symlinked dotfile in place does not
+  replace the link itself.
+
+### Command line
+
+- `history`, `restore`, `diff`, `browse`, `snapshots`, `mounts` and `serve`, every one of
+  them with `--json`. That output is the contract the other front-ends share: a Cockpit
+  module has no server side and can only spawn a process, so a JSON-emitting CLI is the
+  one shape a shared core can take.
+
+### Web UI
+
+- `serve` runs a standalone web UI with no build step and no JavaScript toolchain: walk
+  the filesystem, see a file's versions, preview one, compare it, restore it.
+- One time axis rather than a mode per feature. Picking a directory version re-lists the
+  left pane at that moment; the preview pane doubles as the diff view.
+- The screen is rendered in the browser and gets its data through `transport.js`, so the
+  Cockpit module can reuse all of it by replacing that one file.
+- Loopback only by default; it refuses any other address without `--auth` (or
+  `--allow-no-auth` said explicitly). Restoring is a `POST` and is rejected on a foreign
+  `Origin`. `--root` confines reading to a subtree, compared with realpath so a symlink
+  inside cannot escape, and `--read-only` disables restoring. The server runs
+  unprivileged, as the user.
+
+### Translations
+
+- Messages come from JSON catalogs under `btrfs_timeline/locales/`, with English as the
+  reference and fallback. English and Japanese ship with the package. The language comes
+  from `--lang`, `BTRFS_TIMELINE_LANG` or the usual locale variables, and the web UI has
+  a picker that lists each language by the name it gives itself.
+- Adding a language means adding one JSON file and touching no code. Tests check that
+  every catalog carries exactly the keys of `en.json` with matching placeholder names,
+  and that every key the code looks up exists.
+- JSON rather than gettext, because `.po` needs a compilation step and the web UI and
+  Cockpit module render in the browser, where `.mo` is unusable. One catalog format both
+  Python and JavaScript can read keeps the translations from being maintained twice.
+- Terminal tables are padded by display width, so East Asian full-width characters line
+  up.
+
+[0.1.0]: https://github.com/akivajp/btrfs-timeline/releases/tag/v0.1.0

btrfs_timeline-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akiva Miura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

btrfs_timeline-0.1.0/PKG-INFO

@@ -0,0 +1,335 @@
+Metadata-Version: 2.5
+Name: btrfs-timeline
+Version: 0.1.0
+Summary: Browse and restore previous versions of your files from btrfs snapshots, from a browser
+Project-URL: Homepage, https://github.com/akivajp/btrfs-timeline
+Project-URL: Repository, https://github.com/akivajp/btrfs-timeline
+Project-URL: Issues, https://github.com/akivajp/btrfs-timeline/issues
+Author-email: Akiva Miura <akiva.miura@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backup,btrfs,file-history,self-hosted,snapper,snapshot,web-ui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Archiving :: Backup
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: bottle>=0.12; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: webtest>=3.0; extra == 'dev'
+Provides-Extra: server
+Requires-Dist: waitress>=3.0; extra == 'server'
+Provides-Extra: web
+Requires-Dist: bottle>=0.12; extra == 'web'
+Description-Content-Type: text/markdown
+
+# btrfs-timeline
+
+Browse and restore previous versions of your files from btrfs snapshots — the way
+Time Machine does it, from a browser.
+
+[日本語版 README はこちら](README.ja.md)
+
+> **Status: early development.** Browsing history, previewing versions and restoring
+> files all work, from the CLI and from the browser. The Cockpit module is next.
+> See [Roadmap](#roadmap).
+
+![The web UI: a file browser on the left, and on the right the versions of the selected file, each with a preview and a restore button](https://raw.githubusercontent.com/akivajp/btrfs-timeline/main/docs/screenshot-en.png)
+
+One file, four rows: a stretch when it did not exist yet, two contents it has held since,
+and the file as it stands now. Forty-eight snapshots went into that — the ones that
+changed nothing are not worth a row.
+
+## Why this exists
+
+If you run btrfs with automatic snapshots (snapper, btrbk, Timeshift), you already have
+every previous version of every file. Getting one back, however, means knowing where the
+snapshots live, guessing which one is old enough, and comparing files by hand on the
+command line. It works, but it is expert-only — and it is the one thing people actually
+need snapshots for.
+
+The tools that exist today each stop somewhere short of this:
+
+| Tool | What it does | Why it may not fit |
+| --- | --- | --- |
+| [httm](https://github.com/kimono-koans/httm) | Excellent interactive file history for ZFS/btrfs | CLI/TUI only |
+| Btrfs Assistant, Snapper GUI | Snapshot management | Desktop app; not per-file history |
+| Samba `vfs_shadow_copy2` | "Previous Versions" in Windows Explorer | Requires a Windows client |
+| Rockstor, OpenMediaVault | Full NAS web UI with btrfs support | NAS-only distributions; share-level rollback, not per-file |
+| Cockpit `storaged` | btrfs filesystem/subvolume creation | No snapshot browsing; multi-device btrfs unsupported |
+
+Nothing lets you open a browser, point at a path, and walk back through time.
+That is what this is.
+
+## Design
+
+The project is meant to ship in three forms, and they share one thing:
+
+```
+btrfs_timeline/core/          Library: snapshot discovery, version history, restore
+btrfs_timeline/cli.py         CLI with --json on every subcommand  <- the shared contract
+btrfs_timeline/web/static/    The screen: index.html + app.js + style.css
+                 transport.js   <- the only file a front-end replaces
+   |- standalone web   imports core directly (single process)
+   |- Cockpit module   cockpit.spawn([... , "--json"], {superuser: "require"})
+   `- desktop GUI      imports core, or calls the CLI
+```
+
+A Cockpit module has **no server side** — it is static files plus a `manifest.json`, and
+it reaches the system by spawning processes from the browser. So the only shape a shared
+core can take is *a CLI that emits JSON*. Every subcommand here has `--json` for that
+reason; treat its output as a public API.
+
+The screen is built in the browser, not on the server. A Cockpit module has no server
+to render with, so anything baked into the HTML could not be reused there. Instead
+`app.js` imports its data from `transport.js`, and that one file is what each front-end
+swaps: `fetch('./api/history?…')` here, `cockpit.spawn` there. The rest of the UI — and
+the translations, which come from the same JSON catalogs the CLI uses — is shared.
+
+Two decisions follow from measurements rather than taste:
+
+- **No `btrfs subvolume list`.** It requires root (`Operation not permitted` otherwise),
+  while the files inside snapshots are readable under ordinary permissions. Discovery is
+  done with `/proc/self/mountinfo` plus directory traversal, so **browsing history does
+  not need root**.
+- **Deduplication is mandatory.** btrfs is copy-on-write, so an unchanged file appears
+  once per snapshot. On the author's machine, 35 snapshots collapse to a single version.
+  Versions are merged by mtime and size, and the periods when a file did *not* exist are
+  preserved as their own entries — otherwise a deleted-then-recreated file looks
+  continuous.
+
+## Installation
+
+```shell
+pipx install btrfs-timeline          # CLI only, no dependencies
+pipx install 'btrfs-timeline[web]'   # with the standalone web UI
+```
+
+Requires Python 3.9+ and Linux. `btrfs-progs` is *not* required for browsing history.
+
+## Usage
+
+```shell
+# What versions of this file exist?
+btrfs-timeline history ~/notes.md
+
+# Machine-readable, for scripts and for the Cockpit module
+btrfs-timeline history ~/notes.md --json
+
+# Which snapshots cover this path, and what layout are they in?
+btrfs-timeline snapshots ~/
+
+# Which btrfs mounts does this system have?
+btrfs-timeline mounts
+
+# What is in this directory? (the web UI uses the same call)
+btrfs-timeline browse ~/Documents --json
+
+# What was in it back then — including what has been deleted since
+btrfs-timeline browse ~/Documents --snapshot 1729
+
+# What changed between a version and the file as it is now
+btrfs-timeline diff ~/notes.md --from 2
+btrfs-timeline diff ~/notes.md --from 2 --to 3
+
+# Open the web UI
+btrfs-timeline serve
+```
+
+Example output:
+
+```
+/home/akiva/.gitconfig
+  # FIRST SEEN           LAST SEEN                  SIZE   SNAPS STATE
+  1 2024-10-02 02:00:08  2025-01-01 00:00:00           -       3 (does not exist)
+  2 2025-12-01 00:00:08  2026-03-01 00:00:00       268 B       4 ok
+  3 2026-04-01 00:00:00  2026-09-23 01:00:00       297 B      28 ok
+  4 -                    -                         297 B       - live
+```
+
+Thirty-five snapshots, three meaningful versions, and the gap before the file was
+created — which is the point.
+
+## Restoring
+
+```shell
+# Bring back the newest version found in snapshots, next to the original file
+btrfs-timeline restore ~/notes.md
+
+# Pick a version by the number shown in the "#" column of `history`
+btrfs-timeline restore ~/notes.md --index 2
+
+# Or by snapshot id
+btrfs-timeline restore ~/notes.md --snapshot 10129
+
+# Show what would happen and change nothing
+btrfs-timeline restore ~/notes.md --dry-run
+
+# Write somewhere else, or overwrite the original (a backup is kept)
+btrfs-timeline restore ~/notes.md --to /tmp/notes.old.md
+btrfs-timeline restore ~/notes.md --in-place
+```
+
+Three properties matter here:
+
+- **Nothing is overwritten by default.** The restored file is written next to the
+  original as `notes.20260401T000008.md`. The worst failure mode for a history tool is
+  destroying the current content of a file while trying to get an old one back, so it is
+  excluded by default rather than guarded by a prompt. `--in-place` overwrites, and even
+  then the current content is kept as `notes.before-restore.<timestamp>.md` unless you
+  pass both `--no-backup` and `--force`.
+- **It is a reflink, not a copy.** Restoring uses the `FICLONE` ioctl, so it shares
+  extents with the snapshot: instant regardless of file size, and no extra space used.
+  If the destination is on another filesystem it falls back to a plain copy, and the
+  output says which one happened.
+- **Writes are atomic.** Content goes to a temporary file in the destination directory
+  and is moved into place with `rename(2)`, so an interrupted restore never leaves a
+  half-written file.
+
+## Web UI
+
+```shell
+pipx install 'btrfs-timeline[web]'
+btrfs-timeline serve                       # http://127.0.0.1:8088/
+btrfs-timeline serve --root ~/Documents    # only allow reading below this directory
+btrfs-timeline serve --read-only           # history only, no restoring
+```
+
+Walk the filesystem on the left, click a file, and its versions appear on the right.
+Each version can be previewed before you decide, and restored with one button. Restoring
+always shows a dry run of exactly what it will write — and where the current content will
+be kept — before asking you to confirm.
+
+There is **one time axis, not a set of modes**. Everything the screen does is a
+combination of two things: a path, and a point in time.
+
+- Click a **directory** and you get its history too. Pick one of its versions and the
+  listing on the left becomes what that directory held at that moment.
+- Files that were **deleted since** appear there, struck through. They are invisible in
+  the current filesystem, so this is the only way to reach them — and from there their
+  history and restore work exactly as they do for any other file.
+- The preview pane doubles as a **diff**: compare a version against the current file, or
+  against any other version, with the selector next to the toggle.
+
+No tabs were added for any of this. Adding one screen per feature would mean learning the
+same "look at the past" gesture three times over.
+
+Two settings sit in the page and are remembered per browser: the **language**, picked
+from the same catalogs the CLI uses, and whether to **show hidden files** — off by
+default, because a home directory is mostly dotfiles and the things you came for get
+buried in them.
+
+It listens on loopback only by default, and it deliberately refuses to listen on any
+other address without `--auth USER:PASSWORD` (also read from `BTRFS_TIMELINE_AUTH`),
+because anyone who can reach it can read your files and write over them. `--allow-no-auth`
+overrides that if you really mean it. Restoring is a `POST` and is rejected when the
+request carries a foreign `Origin`: basic auth alone would not stop another site from
+making your browser send the request for you.
+
+The server runs as you, so it can only read what you can read. It does not need root —
+that is the point of not using `btrfs subvolume list`.
+
+## Translations
+
+Messages are translated at runtime from JSON catalogs in
+[`btrfs_timeline/locales/`](btrfs_timeline/locales/). `en.json` is the reference, and any
+key a catalog is missing falls back to English — so a partial translation is useful from
+its very first line.
+
+```shell
+btrfs-timeline history ~/notes.md --lang ja   # this invocation only
+BTRFS_TIMELINE_LANG=ja btrfs-timeline ...     # this shell
+```
+
+With neither, the language comes from `LC_ALL`, `LC_MESSAGES` or `LANG`, and falls back
+to English; `LANG=C` means English. Only human-readable output is translated. `--json` is
+byte-identical in every language, because front-ends and scripts consume it.
+
+### Adding a language
+
+Copy `en.json` to `<code>.json` — an ISO 639-1 code such as `de`, or a regional variant
+such as `pt_br`, which falls back to `pt` if that catalog exists — and translate the
+values, starting with `language.name`, which is how your language names *itself* (`日本語`,
+not `Japanese`): that string is what the web UI's language picker shows, so someone who
+reads only your language has to be able to find it. **No code changes are needed.** The
+new language is picked up automatically, both in the values `--lang` accepts and in the
+picker.
+
+The test suite (`pytest tests/test_i18n.py`) enforces two rules:
+
+- Every key from `en.json` is present, and nothing extra is.
+- Placeholder *names* match (`{path}`, `{index}`). Their order within a sentence is yours
+  to change — that is exactly why they are named rather than positional.
+
+Tables are aligned by terminal display width rather than character count, so East Asian
+full-width characters line up correctly.
+
+Why JSON and not gettext: `.po` files need a compilation step to `.mo`, and the web UI
+and Cockpit module render in the browser, where `.mo` is unusable. A single catalog
+format that both Python and JavaScript can read keeps the translations from being
+maintained twice.
+
+## Supported snapshot layouts
+
+| Layout | Path shape | Typical source |
+| --- | --- | --- |
+| snapper | `<mount>/.snapshots/<N>/snapshot` + `info.xml` | snapper |
+| flat | `<mount>/.snapshots/<name>` | btrbk, Timeshift, manual |
+
+Snapshot timestamps come from snapper's `info.xml` (which records **UTC**, despite
+carrying no timezone marker), from a timestamp embedded in the directory name, or from
+the directory mtime, in that order.
+
+## Roadmap
+
+1. **File history browser, standalone web UI** — done
+2. **Cockpit module** — the current focus: same CLI, same screen, only `transport.js`
+   differs, for people who already run Cockpit
+3. **Dashboard and device management** — devices, RAID profile, scrub/balance progress
+4. **Desktop GUI**
+
+Device management (3) can destroy a filesystem when it goes wrong, which is a different
+class of risk from reading history. It will stay a separate module with separate
+privileges.
+
+## Notes and limitations
+
+- Symlinks are resolved against the *live* filesystem, so history follows the target of a
+  link (useful for dotfiles). Links inside snapshots are never followed, so a snapshot
+  never reports live content as if it were old.
+- Versions are compared by mtime and size, not by content hash. Hashing would mean
+  reading every version of every file.
+- Restoring a whole directory is not supported yet — only individual files. You can see
+  what a directory held at any point and restore the files out of it one by one, but
+  there is no single "put this directory back". Restoring part of a tree silently would
+  be worse than refusing.
+- A directory's history comes from the directory's own mtime, which btrfs preserves. That
+  changes when entries are added, removed or renamed — not when a file inside is edited.
+  So directory versions mark *what came and went*, which is the granularity you want for
+  finding something deleted; use the file's own history for edits.
+- A restored file keeps the original's permissions and mtime, but not its owner:
+  `chown` requires root, and this tool is meant to run unprivileged.
+- btrfs RAID 5/6 is still not considered production-ready upstream; this tool does not
+  change that.
+
+## Alternatives
+
+If you want a terminal tool rather than a browser, use
+[httm](https://github.com/kimono-koans/httm) — it is mature, fast, and covers ZFS too.
+If you want a full NAS appliance, use [Rockstor](https://rockstor.com/) or
+[OpenMediaVault](https://www.openmediavault.org/).
+
+## License
+
+MIT — see [LICENSE](LICENSE).