bolthole 1.0.2__tar.gz

bolthole-1.0.2/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install bats
+        run: sudo apt-get install -y bats
+
+      - name: Install package
+        run: pip install -e ".[dev]"
+
+      - name: Test
+        run: make test

bolthole-1.0.2/.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install bolthole
+        run: pip install -e ".[dev]"
+
+      - name: Install bats
+        run: sudo apt-get install -y bats
+
+      - name: Run tests
+        run: make test
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: test
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

bolthole-1.0.2/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+*.egg-info/

bolthole-1.0.2/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+
+## [v1.0.2] - 2026-01-20
+
+Properly fix the grace period and bundle calculations.
+
+
+## [v1.0.1] - 2026-01-19
+
+Fix grace period calculation bug.
+
+
+## [v1.0] - 2026-01-19
+
+Automatically backup a directory to git — watch a directory for changes,
+and either commit the changes or mirror the directory to another that is
+a git repository, and commit changes there.
+
+There is a grace period to allow multiple edits in a short space of time,
+and multiple files changed within the grace period should be packaged as
+one commit, not many.

bolthole-1.0.2/Makefile

@@ -0,0 +1,12 @@
+.PHONY: test flake8 pytest bats
+
+test: flake8 pytest bats
+
+flake8:
+	flake8
+
+pytest:
+	pytest
+
+bats:
+	bats tests/

bolthole-1.0.2/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: bolthole
+Version: 1.0.2
+Summary: bolthole
+Author-email: Mark Norman Francis <norm@201created.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: watchdog
+Provides-Extra: dev
+Requires-Dist: flake8; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bolthole
+
+Automatically backup changes to a directory to git.
+
+## Usage
+
+```bash
+bolthole
+    [--ignore GLOB [--ignore ...]]          # autoignored: .git, .gitignore
+    [--author AUTHOR] [--message TEXT]      # override your git config
+    [--grace SECONDS] [--bundle SECONDS]    # allow for rapid edits to finish
+    [--remote NAME [--remote ...]]          # push changes upstream
+    [--verbose] [--show-git] [--timeless]
+        [--watchdog-debug]                  # control verbosity
+    [--dry-run]                             # test it first
+    [--once]                                # no ongoing monitoring
+    source_dir                              # what to monitor
+    [dest_dir]                              # optionally copy to repo
+```
+
+
+## Autocommit a directory
+
+```bash
+bolthole .
+```
+
+Assumes the directory is already git controlled, and will refuse to start if
+not. It will commit any outstanding changes. If `--once` was used, it will
+then stop, otherwise it will watch for changes until killed, committing them.
+
+
+## Autocommit to a different directory
+
+```bash
+bolthole project/ pristine-copy/
+```
+
+If `pristine-copy` doesn't exist, it will copy it and create a git repository
+there, or it will check that if directory is already git controlled and will
+refuse to start if not. It will commit any outstanding changes. If `--once`
+was used, it will then stop, otherwise it will watch for changes until killed,
+committing them.
+
+
+## Grace and bundling
+
+The `--grace SECONDS` option will wait until the amount of time specified
+has passed before committing the file, and will restart the timer after
+each change. This way, if a file is being edited repeatedly in a short
+span of time, the result would be only one commit, not many.
+
+The `--bundle SECONDS` option allows for multiple file changes to be
+bundled together in one commit rather than one commit per file, as long as
+they all happened at roughly the same time. The bundle time is how
+recently a file needs to have been changed in order to be excluded from the
+bundle.
+
+For example, with a grace period of five minutes, and a bundle window of
+one minute:
+
+- at `t = 0m00s` — `foo.txt` is edited, and a timer for it is set for 300 seconds
+- at `t = 0m30s` — `bar.txt` is edited, and a timer for it is set
+  for 300s (we now have `foo.txt` at 270s, `bar.txt` at 300s)
+- at `t = 4m30s` — `baz.txt` is edited, and a timer for it is set for 300s
+  (we now have `foo.txt` at 30s, `bar.txt` at 60s, `baz.txt` at 300s)
+- at `t = 5m00s` — the `foo.txt` timer goes off (we now have `foo.txt` at 0s,
+  `bar.txt` at 30s, `baz.txt` at 270s); the changes to `foo.txt` and `bar.txt`
+  were both made earlier than the bundle window, and one commit is made with
+  both changes
+- at `t = 9m30s` — `baz.txt` is committed
+
+
+## Installation
+
+Bolthole is installed from pypi:
+
+```bash
+pip install bolthole
+```

bolthole-1.0.2/README.md

@@ -0,0 +1,80 @@
+# bolthole
+
+Automatically backup changes to a directory to git.
+
+## Usage
+
+```bash
+bolthole
+    [--ignore GLOB [--ignore ...]]          # autoignored: .git, .gitignore
+    [--author AUTHOR] [--message TEXT]      # override your git config
+    [--grace SECONDS] [--bundle SECONDS]    # allow for rapid edits to finish
+    [--remote NAME [--remote ...]]          # push changes upstream
+    [--verbose] [--show-git] [--timeless]
+        [--watchdog-debug]                  # control verbosity
+    [--dry-run]                             # test it first
+    [--once]                                # no ongoing monitoring
+    source_dir                              # what to monitor
+    [dest_dir]                              # optionally copy to repo
+```
+
+
+## Autocommit a directory
+
+```bash
+bolthole .
+```
+
+Assumes the directory is already git controlled, and will refuse to start if
+not. It will commit any outstanding changes. If `--once` was used, it will
+then stop, otherwise it will watch for changes until killed, committing them.
+
+
+## Autocommit to a different directory
+
+```bash
+bolthole project/ pristine-copy/
+```
+
+If `pristine-copy` doesn't exist, it will copy it and create a git repository
+there, or it will check that if directory is already git controlled and will
+refuse to start if not. It will commit any outstanding changes. If `--once`
+was used, it will then stop, otherwise it will watch for changes until killed,
+committing them.
+
+
+## Grace and bundling
+
+The `--grace SECONDS` option will wait until the amount of time specified
+has passed before committing the file, and will restart the timer after
+each change. This way, if a file is being edited repeatedly in a short
+span of time, the result would be only one commit, not many.
+
+The `--bundle SECONDS` option allows for multiple file changes to be
+bundled together in one commit rather than one commit per file, as long as
+they all happened at roughly the same time. The bundle time is how
+recently a file needs to have been changed in order to be excluded from the
+bundle.
+
+For example, with a grace period of five minutes, and a bundle window of
+one minute:
+
+- at `t = 0m00s` — `foo.txt` is edited, and a timer for it is set for 300 seconds
+- at `t = 0m30s` — `bar.txt` is edited, and a timer for it is set
+  for 300s (we now have `foo.txt` at 270s, `bar.txt` at 300s)
+- at `t = 4m30s` — `baz.txt` is edited, and a timer for it is set for 300s
+  (we now have `foo.txt` at 30s, `bar.txt` at 60s, `baz.txt` at 300s)
+- at `t = 5m00s` — the `foo.txt` timer goes off (we now have `foo.txt` at 0s,
+  `bar.txt` at 30s, `baz.txt` at 270s); the changes to `foo.txt` and `bar.txt`
+  were both made earlier than the bundle window, and one commit is made with
+  both changes
+- at `t = 9m30s` — `baz.txt` is committed
+
+
+## Installation
+
+Bolthole is installed from pypi:
+
+```bash
+pip install bolthole
+```

bolthole-1.0.2/bolthole/cli.py

@@ -0,0 +1,182 @@
+import argparse
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+from bolthole.git import GitRepo, configure_output
+from bolthole.watcher import watch
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="bolthole")
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s version v{version('bolthole')}",
+    )
+    parser.add_argument(
+        "--watchdog-debug",
+        action="store_true",
+        help="show raw filesystem events",
+    )
+    parser.add_argument(
+        "-n",
+        "--dry-run",
+        action="store_true",
+        help="take no actions, but report what would happen",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="show file updates as well as actions taken",
+    )
+    parser.add_argument(
+        "--timeless",
+        action="store_true",
+        help="omit timestamps from output",
+    )
+    parser.add_argument(
+        "--ignore",
+        action="append",
+        default=[],
+        metavar="PATTERN",
+        help="ignore files matching pattern (repeatable)",
+    )
+    parser.add_argument(
+        "--show-git",
+        action="store_true",
+        help="display git commands and their output",
+    )
+    parser.add_argument(
+        "--once",
+        action="store_true",
+        help="commit and exit without watching for changes",
+    )
+    parser.add_argument(
+        "-a",
+        "--author",
+        metavar="AUTHOR",
+        help="override commit author (format: 'Name <email>')",
+    )
+    parser.add_argument(
+        "-b",
+        "--bundle",
+        type=float,
+        default=0,
+        metavar="SECONDS",
+        help="bundle files older than threshold into single commit",
+    )
+    parser.add_argument(
+        "-g",
+        "--grace",
+        type=float,
+        default=0,
+        metavar="SECONDS",
+        help="delay commits by grace period (default: 0)",
+    )
+    parser.add_argument(
+        "-m",
+        "--message",
+        metavar="MESSAGE",
+        help="override commit message",
+    )
+    parser.add_argument(
+        "-r",
+        "--remote",
+        action="append",
+        default=[],
+        metavar="REMOTE",
+        help="push to remote after commit (repeatable)",
+    )
+    parser.add_argument("source")
+    parser.add_argument("dest", nargs="?")
+    args = parser.parse_args()
+
+    configure_output(args.timeless)
+
+    if args.grace < 0:
+        print("error: grace period cannot be negative", file=sys.stderr)
+        sys.exit(2)
+
+    if args.bundle < 0:
+        print("error: bundle threshold cannot be negative", file=sys.stderr)
+        sys.exit(2)
+
+    if args.bundle > 0 and args.grace == 0:
+        print("error: bundle requires grace period", file=sys.stderr)
+        sys.exit(2)
+
+    if args.grace and args.bundle >= args.grace:
+        print("error: bundle threshold must be less than grace period", file=sys.stderr)
+        sys.exit(2)
+
+    source = Path(args.source).resolve()
+    if not source.exists():
+        print(
+            f"error: source directory does not exist: {args.source}",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    dest = None
+    if not args.dest:
+        if not GitRepo.is_repo(source):
+            print("error: source must be a git repository in single-directory mode",
+                  file=sys.stderr)
+            sys.exit(2)
+    else:
+        dest = Path(args.dest).resolve()
+        if source == dest:
+            print("error: source and destination cannot be the same",
+                  file=sys.stderr)
+            sys.exit(2)
+        if source.is_relative_to(dest):
+            print("error: source cannot be inside destination",
+                  file=sys.stderr)
+            sys.exit(2)
+        if dest.is_relative_to(source):
+            print("error: destination cannot be inside source",
+                  file=sys.stderr)
+            sys.exit(2)
+
+        if GitRepo.is_repo(dest):
+            pass
+        elif dest.exists() and any(dest.iterdir()):
+            print("error: destination exists but is not a git repository",
+                  file=sys.stderr)
+            sys.exit(2)
+        elif not args.dry_run:
+            dest.mkdir(parents=True, exist_ok=True)
+            repo = GitRepo(dest)
+            repo.init()
+
+    if args.remote:
+        if dest:
+            repo_path = dest
+        else:
+            repo_path = source
+        repo = GitRepo(repo_path)
+        for remote in args.remote:
+            if not repo.has_remote(remote):
+                print(f"remote '{remote}' needs to be added",
+                      file=sys.stderr)
+                sys.exit(2)
+
+    watch(
+        source,
+        dest=dest,
+        dry_run=args.dry_run,
+        verbose=args.verbose,
+        watchdog_debug=args.watchdog_debug,
+        ignore_patterns=args.ignore,
+        show_git=args.show_git,
+        source_label=args.source,
+        dest_label=args.dest,
+        once=args.once,
+        author=args.author,
+        message=args.message,
+        remotes=args.remote,
+        grace=args.grace,
+        bundle=args.bundle,
+    )

bolthole-1.0.2/bolthole/debounce.py

@@ -0,0 +1,116 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Event:
+    type: str
+    path: str
+    new_path: str | None = None
+
+
+def find_origin(
+    renames: dict[str, str],
+    path: str,
+) -> str | None:
+    for origin, dest in renames.items():
+        if dest == path:
+            return origin
+    return None
+
+
+def build_result(
+    states: dict[str, str],
+    renames: dict[str, str],
+) -> list[Event]:
+    result = []
+    emitted = set()
+    for origin, dest in sorted(renames.items()):
+        if origin in emitted or dest == origin:
+            continue
+        if renames.get(dest) == origin:
+            result.append(Event("renamed", origin, dest))
+            result.append(Event("renamed", dest, origin))
+            emitted.add(dest)
+        else:
+            result.append(Event("renamed", origin, dest))
+        emitted.add(origin)
+
+    for path, state in sorted(states.items()):
+        result.append(Event(state, path))
+
+    return result
+
+
+def collapse_events(
+    events: list[Event],
+) -> list[Event]:
+    states: dict[str, str] = {}
+    renames: dict[str, str] = {}
+    vacated: set[str] = set()
+
+    for event in events:
+        if event.type == "created":
+            path = event.path
+            if states.get(path) == "deleted":
+                states[path] = "modified"
+            else:
+                states[path] = "created"
+            vacated.discard(path)
+
+        elif event.type == "modified":
+            path = event.path
+            if path in vacated:
+                continue
+            if find_origin(renames, path):
+                continue
+            if states.get(path) != "created":
+                states[path] = "modified"
+
+        elif event.type == "deleted":
+            path = event.path
+            if path in vacated:
+                continue
+            origin = find_origin(renames, path)
+            if origin:
+                del renames[origin]
+                states[origin] = "deleted"
+                continue
+            if states.get(path) == "created":
+                del states[path]
+            else:
+                states[path] = "deleted"
+
+        elif event.type == "renamed":
+            src, dst = event.path, event.new_path
+            src_origin = find_origin(renames, src)
+            if not src_origin:
+                src_origin = src
+            src_state = states.get(src)
+            dst_state = states.get(dst)
+
+            if dst_state == "deleted":
+                states[dst] = "modified"
+                if src_origin != src and src_origin in renames:
+                    del renames[src_origin]
+                vacated.add(src)
+                continue
+
+            if dst_state == "modified":
+                states[src_origin] = "deleted"
+                vacated.add(src)
+                if src_origin in renames:
+                    del renames[src_origin]
+                continue
+
+            if dst_state == "created":
+                del states[dst]
+
+            if src_state == "created":
+                states.pop(src, None)
+                states[dst] = "created"
+            else:
+                states.pop(src, None)
+                renames[src_origin] = dst
+                vacated.add(src)
+
+    return build_result(states, renames)