ruborg 0.9.0 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4d69dff5edaf281b1014e64653462df7d7af84be0f341db0c4fe389978f25b1
-  data.tar.gz: b206422e04dab022cd19a8d4ea6f9bd399988fc27b6e810fd673dfb7de0fb9ba
+  metadata.gz: 8f3c9f239a72ec2f321419eb6f4349c25fe4cec4ca5174c156e2f1d3fe84ec68
+  data.tar.gz: 4930dbbc8dc2d4e2040628a8c57e62d7bf3ac20ca58a0e7e363a649f6f8d6546
 SHA512:
-  metadata.gz: f881b5b0908afaa16729339263d1584d861cd3a3d6b613599cbdb120340a86a2dc69408dc3f630d347769b990ea6c36ced1b538d17ba1517bebfb347c5c9ef2b
-  data.tar.gz: ffd3ee5bd76b08ac9753d66ae95ac1aebaed2f4ba6db38ddc720e013970d2799a99202e4cf7295f969dd93ddf4f8b8b7df6d8730352a33f8ff86ce76eecbaff6
+  metadata.gz: ba9bd867f83d24c88abf435f4b64368b9c414080290747f107a6b5e94db6e82ddba0a59b0f700a4625e689b54724aefceecccc56f5e51f3fc8271be74601bc5e
+  data.tar.gz: e95dd232d73c7c63968c0105170928d0ab28d689342ad875a81fbc30ac56d508179a1866b476b79125fe43a85fc69cc68baef14a45cd220019be5612ce458bea

data/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.3] - 2026-05-09
+
+### Added
+- **`ruborg lock` command**: Check for and optionally break stale Borg repository locks
+  - `ruborg lock --repository NAME` — exits 0 if no lock, exits 1 if lock detected
+  - `ruborg lock --repository NAME --break --yes` — breaks the lock via `borg break-lock`
+  - `ruborg lock --repository NAME --force --yes` — force-removes lock files directly without invoking Borg (useful when Borg itself can't run)
+  - `--break` and `--force` are mutually exclusive; both require `--yes` as a safety guard
+  - `Repository#locked?` — pure filesystem check on `lock.exclusive` / `lock.roster`, no Borg invocation or passphrase required
+  - `Repository#break_lock` — delegates to `borg break-lock`; requires Borg >= 1.4.0
+  - `Repository#force_break_lock` — direct filesystem removal of lock files/dirs; no Borg needed
+  - Status output (lock present/absent) goes to stdout for scriptability; warning messages go to `$stderr`
+- **Pre-flight lock detection during backup**: If a repository is locked when `backup` starts, ruborg waits and retries instead of failing immediately
+  - Polls every 5 seconds, prints elapsed time via the spinner
+  - Aborts with a clear error message after `lock_wait` seconds (default 300), suggesting `ruborg lock` to inspect or clear
+- **`lock_wait` config key**: Optional integer (seconds). When set, also passed as `--lock-wait` to all Borg commands so Borg itself waits for mid-operation locks. Omitting the key leaves Borg at its own default (1 second)
+- **Minimum Borg version**: Raised to 1.4.0; `break_lock` verifies this before invoking `borg break-lock`
+- **`CLI::DEFAULT_LOCK_WAIT = 300`**: Named constant for the pre-flight wait timeout
+- Fixes [#8](https://github.com/mpantel/ruborg/issues/8)
+
+## [0.9.2] - 2026-05-09
+
+### Added
+- **CLI progress display**: Real-time feedback during backup operations
+  - Named stages printed to `$stderr`: `[1/3] Verifying repository`, `[2/3] Backing up files`, `[3/3] Pruning`
+  - Animated spinner for indeterminate operations (cache loading, `borg create`, pruning)
+  - Inline progress bar for per-file backup mode: `[=========>     ] 42/120  filename.jpg`
+  - Stage count adapts to the operation: 2 stages without pruning, 3 with
+  - Degrades gracefully to plain text lines when output is piped or redirected (non-TTY)
+  - All progress output goes to `$stderr` — `--json` stdout and piped output remain clean
+  - No external gem dependencies — pure Ruby with ANSI `\r` rewrite
+  - Fixes [#6](https://github.com/mpantel/ruborg/issues/6)
+
+## [0.9.1] - 2026-05-09
+
+### Added
+- **Archive metadata cache**: New `ArchiveCache` class eliminates N+1 `borg info` calls during per-file backup runs
+  - Metadata cached in `<repo_path>.ruborg_cache.json` — sibling file to the repository
+  - Cache is shared across machines: any host with access to the repo path shares the same cache
+  - Local repos use `File::LOCK_EX` for safe concurrent reads/writes with merge-on-conflict
+  - SSH repos (`user@host:/path`, `ssh://user@host/path`) fetch/push the cache via `scp` with optimistic locking (fetch-fresh → merge → push), avoiding deadlocks on process crashes
+  - Only archives not yet in cache trigger a `borg info` call; warm runs reduce subprocess overhead from O(n) to O(new archives)
+  - Fixes [#4](https://github.com/mpantel/ruborg/issues/4)
+- **Catalog command**: New `ruborg catalog` command for fast, offline browsing of backed-up files
+  - Reads the local cache file — no `borg` subprocess calls needed
+  - `--search PATTERN` — filter entries by file path using a regex
+  - `--stats` — show aggregate statistics (total archives, unique files, total size, source dirs)
+  - `--json` — machine-readable JSON output; default is a human-friendly text table
+  - Works per-repository like all other commands (`--repository`)
+  - Supports SSH repos transparently via the same `scp`-based cache fetch
+- **Bug fix**: `ArchiveCache` now normalises all loaded metadata to symbol keys, ensuring cache hits and cache misses return identical key types
+
 ## [0.9.0] - 2025-10-14
 
 ### Changed

data/README.md

@@ -25,13 +25,15 @@ A friendly Ruby frontend for [Borg Backup](https://www.borgbackup.org/). Ruborg
 - 📈 **Summary View** - Quick overview of all repositories and their configurations
 - 🔧 **Custom Borg Path** - Support for custom Borg executable paths per repository
 - 🏠 **Hostname Validation** - NEW! Restrict backups to specific hosts (global or per-repository)
-- ✅ **Well-tested** - Comprehensive test suite with RSpec (297 examples, 0 failures)
+- 🔒 **Lock Management** - Detect and break stale Borg repository locks with `ruborg lock`
+- ⏳ **Lock-aware Backups** - Pre-flight lock detection with configurable wait timeout before backup
+- ✅ **Well-tested** - Comprehensive test suite with RSpec (412 examples, 0 failures)
 - 🔒 **Security-focused** - Path validation, safe YAML loading, command injection protection
 
 ## Prerequisites
 
 - Ruby >= 3.2.0
-- [Borg Backup](https://www.borgbackup.org/) installed and available in PATH
+- [Borg Backup](https://www.borgbackup.org/) >= 1.4.0 installed and available in PATH
 - [Passbolt CLI](https://github.com/passbolt/go-passbolt-cli) (optional, for password management)
 
 ### Installing Borg Backup
@@ -169,8 +171,9 @@ repositories:
 - **Source Deletion Safety**: `allow_remove_source` flag to explicitly enable `--remove-source` option (default: disabled)
 - **Skip Hash Check**: Optional `skip_hash_check` flag to skip content hash verification for faster backups (per-file mode only)
 - **Type-Safe Booleans**: Strict boolean validation prevents configuration errors (must use `true`/`false`, not strings)
-- **Global Settings**: Hostname, compression, encryption, auto_init, allow_remove_source, skip_hash_check, log_file, borg_path, borg_options, and retention apply to all repositories
-- **Per-Repository Overrides**: Any global setting can be overridden at the repository level (including hostname, allow_remove_source, skip_hash_check, and custom borg_path)
+- **Lock Wait Timeout**: Optional `lock_wait` (integer, seconds) — how long ruborg waits for a locked repository before aborting. Also passed as `--lock-wait` to Borg when set. Default: 300 seconds (pre-flight), Borg default: 1 second (when not configured)
+- **Global Settings**: Hostname, compression, encryption, auto_init, allow_remove_source, skip_hash_check, lock_wait, log_file, borg_path, borg_options, and retention apply to all repositories
+- **Per-Repository Overrides**: Any global setting can be overridden at the repository level (including hostname, allow_remove_source, skip_hash_check, lock_wait, and custom borg_path)
 - **Custom Borg Path**: Specify a custom Borg executable path if borg is not in PATH or to use a specific version
 - **Retention Policies**: Define how many backups to keep (hourly, daily, weekly, monthly, yearly)
 - **Multiple Sources**: Each repository can have multiple backup sources with their own exclude patterns
@@ -472,6 +475,38 @@ Group: postgres
 Type: regular file
 ```
 
+### Manage Repository Locks
+
+Borg uses lock files to prevent concurrent access. If a backup crashes, stale locks can block all subsequent operations. Use `ruborg lock` to inspect and clear them.
+
+```bash
+# Check if a repository is locked (exits 0 = no lock, 1 = locked)
+ruborg lock --repository documents
+
+# Break the lock via borg break-lock (requires Borg >= 1.4.0)
+ruborg lock --repository documents --break --yes
+
+# Force-remove lock files directly (no Borg required, last resort)
+ruborg lock --repository documents --force --yes
+```
+
+**Lock-aware backups:** When `ruborg backup` starts and detects a lock, it waits up to `lock_wait` seconds (default 300) for the lock to clear before aborting:
+
+```
+[1/2] Verifying repository: documents
+  Repository locked — waiting for lock to clear (5s / 300s)…
+  Repository locked — waiting for lock to clear (10s / 300s)…
+  ✓ Lock cleared
+[2/2] Creating archive
+```
+
+Configure the timeout in `ruborg.yml` (also passed as `--lock-wait` to Borg when set):
+
+```yaml
+# Wait up to 60s for a lock before aborting; also passes --lock-wait 60 to borg commands
+lock_wait: 60
+```
+
 ### Validate Repository Compatibility
 
 ```bash
@@ -659,6 +694,7 @@ See [SECURITY.md](SECURITY.md) for detailed security information and best practi
 | `list` | List archives or files in repository | `--config`, `--repository`, `--archive`, `--log` |
 | `restore ARCHIVE` | Restore files from archive | `--config`, `--repository`, `--destination`, `--path`, `--log` |
 | `metadata ARCHIVE` | Get file metadata from archive | `--config`, `--repository`, `--file`, `--log` |
+| `lock` | Check for and optionally break a repository lock | `--config`, `--repository`, `--break`, `--force`, `--yes`, `--log` |
 | `info` | Show repository information | `--config`, `--repository`, `--log` |
 | `version` | Show ruborg version | None |
 

data/lib/ruborg/archive_cache.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "tempfile"
+
+module Ruborg
+  # Persistent cache of per-archive metadata, stored as a JSON file sibling to the
+  # Borg repository. Eliminates repeated `borg info` calls across runs.
+  #
+  # Supports local paths (File::LOCK_EX) and SSH paths (optimistic merge via scp).
+  # All metadata is stored and returned with symbol keys (:path, :size, :hash, :source_dir).
+  class ArchiveCache
+    SSH_PATTERN = %r{\A(?:ssh://|[^\s/]+@[^\s:]+:)}
+
+    def initialize(repo_path)
+      @repo_path = repo_path
+      @data = {}
+      @snapshot = {}
+      @loaded = false
+    end
+
+    def fetch
+      return self if @loaded
+
+      if ssh?
+        load_remote
+      else
+        load_local
+      end
+
+      @snapshot = snapshot(@data)
+      @loaded = true
+      self
+    end
+
+    def [](archive_name)
+      @data[archive_name]
+    end
+
+    def store(archive_name, metadata)
+      @data[archive_name] = symbolize(metadata)
+    end
+
+    # Returns all cached entries as an array of hashes, each including :archive_name.
+    def entries
+      @data.map { |archive_name, metadata| metadata.merge(archive_name: archive_name) }
+    end
+
+    def save_if_changed
+      return unless dirty?
+
+      if ssh?
+        save_remote
+      else
+        save_local
+      end
+    end
+
+    private
+
+    def dirty?
+      @data != @snapshot
+    end
+
+    def snapshot(hash)
+      hash.transform_values(&:dup)
+    end
+
+    def ssh?
+      SSH_PATTERN.match?(@repo_path)
+    end
+
+    def cache_path_for(path)
+      "#{path}.ruborg_cache.json"
+    end
+
+    def symbolize(metadata)
+      metadata.transform_keys(&:to_sym)
+    end
+
+    def normalize_archives(raw)
+      (raw || {}).transform_values { |v| symbolize(v) }
+    end
+
+    def load_local
+      path = cache_path_for(@repo_path)
+      return unless File.exist?(path)
+
+      File.open(path, "r") do |f|
+        f.flock(File::LOCK_SH)
+        parsed = JSON.parse(f.read)
+        @data = normalize_archives(parsed["archives"])
+      end
+    rescue JSON::ParserError
+      @data = {}
+    end
+
+    def save_local
+      path = cache_path_for(@repo_path)
+      File.open(path, File::RDWR | File::CREAT, 0o600) do |f|
+        f.flock(File::LOCK_EX)
+        existing = read_existing_local(f)
+        merged = existing.merge(@data)
+        f.rewind
+        f.write(JSON.generate({ "version" => 1, "archives" => stringify_for_storage(merged) }))
+        f.truncate(f.pos)
+      end
+    end
+
+    def read_existing_local(file)
+      content = file.read
+      return {} if content.empty?
+
+      normalize_archives(JSON.parse(content)["archives"])
+    rescue JSON::ParserError
+      {}
+    end
+
+    # JSON requires string keys; convert symbol keys back before writing.
+    def stringify_for_storage(data)
+      data.transform_values { |v| v.transform_keys(&:to_s) }
+    end
+
+    def parse_ssh
+      if @repo_path.start_with?("ssh://")
+        require "uri"
+        uri = URI.parse(@repo_path)
+        host = uri.user ? "#{uri.user}@#{uri.host}" : uri.host
+        host = "#{host}:#{uri.port}" if uri.port && uri.port != 22
+        [host, uri.path]
+      else
+        match = @repo_path.match(%r{\A([^\s/]+@[^\s:]+):(.+)\z})
+        return [nil, nil] unless match
+
+        [match[1], match[2]]
+      end
+    end
+
+    def load_remote
+      host, path = parse_ssh
+      return unless host
+
+      remote = "#{host}:#{cache_path_for(path)}"
+      loaded = nil
+      Tempfile.create(["ruborg_cache", ".json"]) do |tmp|
+        _, status = Open3.capture2e("scp", "-q", "-B", remote, tmp.path)
+        next unless status.success?
+
+        begin
+          loaded = normalize_archives(JSON.parse(File.read(tmp.path))["archives"])
+        rescue JSON::ParserError
+          loaded = {}
+        end
+      end
+      @data = loaded if loaded
+    end
+
+    def save_remote
+      host, path = parse_ssh
+      return unless host
+
+      remote = "#{host}:#{cache_path_for(path)}"
+      fresh = fetch_remote_fresh(remote)
+      merged = fresh.merge(@data)
+
+      Tempfile.create(["ruborg_cache_upload", ".json"]) do |tmp|
+        tmp.write(JSON.generate({ "version" => 1, "archives" => stringify_for_storage(merged) }))
+        tmp.flush
+        Open3.capture2e("scp", "-q", "-B", tmp.path, remote)
+      end
+    end
+
+    def fetch_remote_fresh(remote)
+      result = {}
+      Tempfile.create(["ruborg_cache_fresh", ".json"]) do |tmp|
+        _, status = Open3.capture2e("scp", "-q", "-B", remote, tmp.path)
+        next unless status.success?
+
+        begin
+          result = normalize_archives(JSON.parse(File.read(tmp.path))["archives"])
+        rescue JSON::ParserError
+          result = {}
+        end
+      end
+      result
+    end
+  end
+end

data/lib/ruborg/backup.rb

@@ -3,13 +3,15 @@
 module Ruborg
   # Backup operations using Borg
   class Backup
-    def initialize(repository, config:, retention_mode: "standard", repo_name: nil, logger: nil, skip_hash_check: false)
+    def initialize(repository, config:, retention_mode: "standard", repo_name: nil, logger: nil,
+                   skip_hash_check: false, progress: nil)
       @repository = repository
       @config = config
       @retention_mode = retention_mode
       @repo_name = repo_name
       @logger = logger
       @skip_hash_check = skip_hash_check
+      @progress = progress
     end
 
     def create(name: nil, remove_source: false)
@@ -27,36 +29,31 @@ module Ruborg
     def create_standard_archive(name, remove_source)
       archive_name = name || Time.now.strftime("%Y-%m-%d_%H-%M-%S")
 
-      # Show repository header in console only
       print_repository_header
-
-      # Show progress in console
-      puts "Creating archive: #{archive_name}"
+      @progress&.spin("Creating archive: #{archive_name}")
 
       cmd = build_create_command(archive_name)
-
       execute_borg_command(cmd)
 
-      # Log successful action
+      @progress&.done("Archive created: #{archive_name}")
       @logger&.info("[#{@repo_name}] Created archive #{archive_name} with #{@config.backup_paths.size} source(s)")
-      puts "✓ Archive created successfully"
 
       remove_source_files if remove_source
     end
 
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/BlockNesting
     def create_per_file_archives(name_prefix, remove_source)
-      # Collect all files from backup paths
+      @progress&.spin("Collecting files...")
       files_to_backup = collect_files_from_paths(@config.backup_paths, @config.exclude_patterns)
+      @progress&.stop_spin
 
       raise BorgError, "No files found to backup" if files_to_backup.empty?
 
-      # Get list of existing archives for duplicate detection
+      @progress&.spin("Loading archive catalog...")
       existing_archives = get_existing_archive_names
+      @progress&.done("Catalog loaded — #{existing_archives.size} archive(s) known")
 
-      # Show repository header in console only
       print_repository_header
-
       puts "Found #{files_to_backup.size} file(s) to backup"
 
       backed_up_count = 0
@@ -78,8 +75,8 @@ module Ruborg
         # Ensure archive name doesn't exceed 255 characters (filesystem limit)
         archive_name = name_prefix || build_archive_name(@repo_name, sanitized_filename, path_hash, file_mtime)
 
-        # Show progress in console
-        print "  [#{index + 1}/#{files_to_backup.size}] Backing up: #{file_path}"
+        @progress&.bar(index + 1, files_to_backup.size, File.basename(file_path))
+        $stderr.print "  [#{index + 1}/#{files_to_backup.size}] Backing up: #{file_path}" unless @progress
 
         # Check if archive already exists AND contains this exact file
         if existing_archives.key?(archive_name)
@@ -149,7 +146,7 @@ module Ruborg
         cmd = build_per_file_create_command(archive_name, file_path, source_dir)
 
         execute_borg_command(cmd)
-        puts ""
+        puts "" unless @progress
 
         # Log successful action with details
         @logger&.info("[#{@repo_name}] Archived #{file_path} in archive #{archive_name}")
@@ -160,11 +157,13 @@ module Ruborg
       end
       # rubocop:enable Metrics/BlockLength
 
-      if skipped_count.positive?
-        puts "✓ Per-file backup completed: #{backed_up_count} file(s) backed up, #{skipped_count} skipped (unchanged)"
-      else
-        puts "✓ Per-file backup completed: #{backed_up_count} file(s) backed up"
-      end
+      summary = if skipped_count.positive?
+                  "#{backed_up_count} file(s) backed up, #{skipped_count} skipped (unchanged)"
+                else
+                  "#{backed_up_count} file(s) backed up"
+                end
+      @progress&.done(summary)
+      puts "✓ Per-file backup completed: #{summary}" unless @progress
     end
     # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/BlockNesting
 
@@ -459,12 +458,11 @@ module Ruborg
       puts "=" * 60
     end
 
-    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def get_existing_archive_names
       require "json"
       require "open3"
 
-      # First get list of archives
       cmd = [@repository.borg_path, "list", @repository.path, "--json"]
       env = {}
       passphrase = @repository.instance_variable_get(:@passphrase)
@@ -475,73 +473,52 @@ module Ruborg
       stdout, stderr, status = Open3.capture3(env, *cmd)
       raise BorgError, "Failed to list archives: #{stderr}" unless status.success?
 
-      json_data = JSON.parse(stdout)
-      archives = json_data["archives"] || []
+      archives = JSON.parse(stdout)["archives"] || []
+      cache = ArchiveCache.new(@repository.path).fetch
 
-      # Build hash by querying each archive individually for comment
-      # This is necessary because 'borg list' doesn't include comments
-      archives.each_with_object({}) do |archive, hash|
+      result = archives.each_with_object({}) do |archive, hash|
         archive_name = archive["name"]
 
-        # Query this specific archive to get the comment
-        info_cmd = [@repository.borg_path, "info", "#{@repository.path}::#{archive_name}", "--json"]
-        info_stdout, _, info_status = Open3.capture3(env, *info_cmd)
-
-        unless info_status.success?
-          # If we can't get info for this archive, skip it with defaults
-          hash[archive_name] = { path: "", size: 0, hash: "", source_dir: "" }
+        if (cached = cache[archive_name])
+          hash[archive_name] = cached
           next
         end
 
-        info_data = JSON.parse(info_stdout)
-        archive_info = info_data["archives"]&.first || {}
-        comment = archive_info["comment"] || ""
-
-        # Parse comment based on format
-        # The comment field stores metadata as: path|||size|||hash|||source_dir (using ||| as delimiter)
-        # For backward compatibility, handle old formats:
-        #   - Old format 1: plain path (no |||)
-        #   - Old format 2: path|||hash (2 parts)
-        #   - Old format 3: path|||size|||hash (3 parts)
-        #   - New format: path|||size|||hash|||source_dir (4 parts)
-        if comment.include?("|||")
-          parts = comment.split("|||")
-          file_path = parts[0]
-          if parts.length >= 4
-            # New format: path|||size|||hash|||source_dir
-            file_size = parts[1].to_i
-            file_hash = parts[2] || ""
-            source_dir = parts[3] || ""
-          elsif parts.length >= 3
-            # Format 3: path|||size|||hash (no source_dir)
-            file_size = parts[1].to_i
-            file_hash = parts[2] || ""
-            source_dir = ""
-          else
-            # Old format: path|||hash (size and source_dir not available)
-            file_size = 0
-            file_hash = parts[1] || ""
-            source_dir = ""
-          end
-        else
-          # Oldest format: comment is just the path string
-          file_path = comment
-          file_size = 0
-          file_hash = ""
-          source_dir = ""
-        end
+        info_cmd = [@repository.borg_path, "info", "#{@repository.path}::#{archive_name}", "--json"]
+        info_stdout, _, info_status = Open3.capture3(env, *info_cmd)
+
+        metadata = if info_status.success?
+                     parse_archive_comment(JSON.parse(info_stdout).dig("archives", 0, "comment") || "")
+                   else
+                     { path: "", size: 0, hash: "", source_dir: "" }
+                   end
 
-        hash[archive_name] = {
-          path: file_path,
-          size: file_size,
-          hash: file_hash,
-          source_dir: source_dir
-        }
+        cache.store(archive_name, metadata)
+        hash[archive_name] = metadata
       end
+
+      cache.save_if_changed
+      result
     rescue JSON::ParserError => e
       raise BorgError, "Failed to parse archive info: #{e.message}"
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    def parse_archive_comment(comment)
+      if comment.include?("|||")
+        parts = comment.split("|||")
+        file_path = parts[0]
+        if parts.length >= 4
+          { path: file_path, size: parts[1].to_i, hash: parts[2] || "", source_dir: parts[3] || "" }
+        elsif parts.length >= 3
+          { path: file_path, size: parts[1].to_i, hash: parts[2] || "", source_dir: "" }
+        else
+          { path: file_path, size: 0, hash: parts[1] || "", source_dir: "" }
+        end
+      else
+        { path: comment, size: 0, hash: "", source_dir: "" }
+      end
+    end
 
     def find_next_version_name(base_name, existing_archives)
       version = 2

data/lib/ruborg/catalog.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ruborg
+  # Read-only view over the ArchiveCache for searching and reporting.
+  # Never writes back to the cache.
+  class Catalog
+    def initialize(repo_path)
+      @cache = ArchiveCache.new(repo_path).fetch
+    end
+
+    # Returns all cached entries sorted by file path.
+    def list
+      @cache.entries.sort_by { |e| e[:path].to_s }
+    end
+
+    # Returns entries whose :path matches +pattern+ (a Regexp or regex string).
+    # Raises CatalogError on invalid regex.
+    def search(pattern)
+      regex = pattern.is_a?(Regexp) ? pattern : Regexp.new(pattern)
+      list.select { |e| regex.match?(e[:path].to_s) }
+    rescue RegexpError => e
+      raise CatalogError, "Invalid regex pattern: #{e.message}"
+    end
+
+    # Returns a summary hash with aggregate statistics.
+    def stats
+      all = list
+      {
+        total_archives: all.size,
+        unique_paths: all.map { |e| e[:path] }.uniq.size,
+        total_size: all.sum { |e| e[:size].to_i },
+        source_dirs: all.map { |e| e[:source_dir] }.uniq.reject(&:empty?).size
+      }
+    end
+  end
+end

data/lib/ruborg/cli.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 require "thor"
+require "json"
 
 module Ruborg
   # Command-line interface for ruborg
   class CLI < Thor
+    DEFAULT_LOCK_WAIT = 300
     class_option :config, type: :string, default: "ruborg.yml", desc: "Path to configuration file"
     class_option :log, type: :string, desc: "Path to log file"
     class_option :repository, type: :string, aliases: "-r", desc: "Repository name (for multi-repo configs)"
@@ -74,11 +76,7 @@ module Ruborg
       merged_config = global_settings.merge(repo_config)
       validate_hostname(merged_config)
       passphrase = fetch_passphrase_for_repo(merged_config)
-      borg_opts = merged_config["borg_options"] || {}
-      borg_path = merged_config["borg_path"]
-
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
-                                                 logger: @logger)
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
 
       # Auto-initialize repository if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -121,11 +119,7 @@ module Ruborg
       merged_config = global_settings.merge(repo_config)
       validate_hostname(merged_config)
       passphrase = fetch_passphrase_for_repo(merged_config)
-      borg_opts = merged_config["borg_options"] || {}
-      borg_path = merged_config["borg_path"]
-
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
-                                                 logger: @logger)
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
 
       # Create backup config wrapper for compatibility
       backup_config = BackupConfig.new(repo_config, merged_config)
@@ -161,11 +155,7 @@ module Ruborg
       global_settings = config.global_settings
       merged_config = global_settings.merge(repo_config)
       passphrase = fetch_passphrase_for_repo(merged_config)
-      borg_opts = merged_config["borg_options"] || {}
-      borg_path = merged_config["borg_path"]
-
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
-                                                 logger: @logger)
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
 
       # Auto-initialize repository if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -311,11 +301,7 @@ module Ruborg
       merged_config = global_settings.merge(repo_config)
       validate_hostname(merged_config)
       passphrase = fetch_passphrase_for_repo(merged_config)
-      borg_opts = merged_config["borg_options"] || {}
-      borg_path = merged_config["borg_path"]
-
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
-                                                 logger: @logger)
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
 
       unless repo.exists?
         puts "  ✗ Repository does not exist at #{repo_config["path"]}"
@@ -358,6 +344,90 @@ module Ruborg
 
     public
 
+    desc "catalog", "Search or browse the local archive metadata catalog (no borg calls)"
+    option :search, type: :string, desc: "Regex pattern to filter by file path"
+    option :stats, type: :boolean, default: false, desc: "Show catalog statistics instead of listing entries"
+    option :json, type: :boolean, default: false, desc: "Output as JSON"
+    def catalog
+      config = Config.new(options[:config])
+
+      raise ConfigError, "Please specify --repository" unless options[:repository]
+
+      repo_config = config.get_repository(options[:repository])
+      raise ConfigError, "Repository '#{options[:repository]}' not found" unless repo_config
+
+      global_settings = config.global_settings
+      merged_config = global_settings.merge(repo_config)
+      cat = Catalog.new(repo_config["path"])
+
+      if options[:stats]
+        print_catalog_stats(cat.stats, options[:json])
+      elsif options[:search]
+        results = cat.search(options[:search])
+        print_catalog_entries(results, options[:json])
+      else
+        print_catalog_entries(cat.list, options[:json])
+      end
+
+      @logger.info("Catalog query on repository '#{merged_config["name"]}'")
+    rescue Error => e
+      @logger.error("Catalog failed: #{e.message}")
+      raise
+    end
+
+    desc "lock", "Check for and optionally break a Borg repository lock"
+    option :break, type: :boolean, default: false,
+                   desc: "Break the lock via borg break-lock (requires --yes)"
+    option :force, type: :boolean, default: false,
+                   desc: "Force-remove lock files directly without invoking borg (requires --yes)"
+    option :yes,   type: :boolean, default: false, desc: "Confirm the destructive operation"
+    def lock
+      config = Config.new(options[:config])
+
+      raise ConfigError, "Please specify --repository" unless options[:repository]
+      raise ConfigError, "Use --break or --force, not both" if options[:break] && options[:force]
+
+      repo_config = config.get_repository(options[:repository])
+      raise ConfigError, "Repository '#{options[:repository]}' not found" unless repo_config
+
+      global_settings = config.global_settings
+      merged_config = global_settings.merge(repo_config)
+      passphrase = fetch_passphrase_for_repo(merged_config)
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
+
+      unless repo.locked?
+        puts "No lock found for repository '#{repo_config["name"]}'"
+        @logger.info("Lock check: no lock found for '#{repo_config["name"]}'")
+        return
+      end
+
+      warn "Lock detected on repository '#{repo_config["name"]}' (#{repo_config["path"]})"
+      @logger.warn("Lock detected on repository '#{repo_config["name"]}'")
+
+      unless options[:break] || options[:force]
+        warn "  Run with --break --yes (via borg) or --force --yes (direct removal)."
+        exit 1
+      end
+
+      unless options[:yes]
+        warn "  Add --yes to confirm."
+        exit 1
+      end
+
+      if options[:force]
+        removed = repo.force_break_lock
+        puts "Force-removed lock files for '#{repo_config["name"]}': #{removed.join(", ")}"
+        @logger.info("Force-removed lock files for '#{repo_config["name"]}'")
+      else
+        repo.break_lock
+        puts "Lock broken for repository '#{repo_config["name"]}'"
+        @logger.info("Lock broken for repository '#{repo_config["name"]}'")
+      end
+    rescue Error => e
+      @logger.error("Lock command failed: #{e.message}")
+      raise
+    end
+
     desc "version", "Show ruborg and borg versions"
     def version
       require_relative "version"
@@ -408,11 +478,7 @@ module Ruborg
       merged_config = global_settings.merge(repo_config)
       validate_hostname(merged_config)
       passphrase = fetch_passphrase_for_repo(merged_config)
-      borg_opts = merged_config["borg_options"] || {}
-      borg_path = merged_config["borg_path"]
-
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
-                                                 logger: @logger)
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
 
       raise BorgError, "Repository does not exist at #{repo_config["path"]}" unless repo.exists?
 
@@ -441,6 +507,49 @@ module Ruborg
 
     private
 
+    def print_catalog_entries(entries, as_json)
+      if as_json
+        puts JSON.generate(entries.map { |e| stringify_entry(e) })
+        return
+      end
+
+      if entries.empty?
+        puts "No entries found."
+        return
+      end
+
+      puts "\n#{"FILE PATH".ljust(55)}  #{"SIZE".ljust(10)}  ARCHIVE"
+      puts "-" * 90
+      entries.each do |e|
+        puts "#{truncate(e[:path].to_s, 55).ljust(55)}  #{format_size(e[:size].to_i).ljust(10)}  #{e[:archive_name]}"
+      end
+      puts "\n#{entries.size} entry/entries."
+    end
+
+    def print_catalog_stats(stats, as_json)
+      if as_json
+        puts JSON.generate(stats)
+        return
+      end
+
+      puts "\n═══════════════════════════════════════════════════════════════"
+      puts "  CATALOG STATISTICS"
+      puts "═══════════════════════════════════════════════════════════════\n\n"
+      puts "  Total archives : #{stats[:total_archives]}"
+      puts "  Unique files   : #{stats[:unique_paths]}"
+      puts "  Source dirs    : #{stats[:source_dirs]}"
+      puts "  Total size     : #{format_size(stats[:total_size])}"
+      puts ""
+    end
+
+    def stringify_entry(entry)
+      entry.transform_keys(&:to_s)
+    end
+
+    def truncate(str, max)
+      str.length > max ? "...#{str[-(max - 3)..]}" : str
+    end
+
     def show_repositories_summary(config)
       repositories = config.repositories
       global_settings = config.global_settings
@@ -529,7 +638,7 @@ module Ruborg
         unit_index += 1
       end
 
-      format("%.2f %s", size, units[unit_index])
+      "#{format("%.2f", size)} #{units[unit_index]}"
     end
 
     def get_passphrase(passphrase, passbolt_id)
@@ -588,30 +697,31 @@ module Ruborg
       puts "\n--- Backing up repository: #{repo_name} ---"
       @logger.info("Backing up repository: #{repo_name}")
 
-      # Merge global settings with repo-specific settings (repo-specific takes precedence)
       merged_config = global_settings.merge(repo_config)
       validate_hostname(merged_config)
 
+      retention_mode = merged_config["retention_mode"] || "standard"
+      auto_prune = merged_config["auto_prune"] == true
+      retention_policy = merged_config["retention"]
+      will_prune = auto_prune && retention_policy && !retention_policy.empty?
+      stage_total = will_prune ? 3 : 2
+
+      progress = Progress.new
+      progress.stage(1, stage_total, "Verifying repository: #{repo_name}")
+
       passphrase = fetch_passphrase_for_repo(merged_config)
-      borg_opts = merged_config["borg_options"] || {}
-      borg_path = merged_config["borg_path"]
-      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
-                                                 logger: @logger)
+      lock_wait = (merged_config["lock_wait"] || DEFAULT_LOCK_WAIT).to_i
+      repo = build_repo(repo_config["path"], merged_config, passphrase)
 
-      # Auto-initialize if configured
-      # Use strict boolean checking: only true enables, everything else disables
-      auto_init = merged_config["auto_init"]
-      auto_init = false unless auto_init == true
+      auto_init = merged_config["auto_init"] == true
       if auto_init && !repo.exists?
         @logger.info("Auto-initializing repository at #{repo_config["path"]}")
         repo.create
         puts "Repository auto-initialized at #{repo_config["path"]}"
       end
 
-      # Get retention mode (defaults to standard)
-      retention_mode = merged_config["retention_mode"] || "standard"
+      wait_for_lock_clear(repo, repo_name, lock_wait, progress)
 
-      # Validate remove_source permission with strict type checking
       if options[:remove_source]
         allow_remove_source = merged_config["allow_remove_source"]
         unless allow_remove_source.is_a?(TrueClass)
@@ -622,14 +732,14 @@ module Ruborg
         end
       end
 
-      # Get skip_hash_check setting (defaults to false)
-      skip_hash_check = merged_config["skip_hash_check"]
-      skip_hash_check = false unless skip_hash_check == true
+      skip_hash_check = merged_config["skip_hash_check"] == true
+
+      backup_label = retention_mode == "per_file" ? "Backing up files (per-file mode)" : "Creating archive"
+      progress.stage(2, stage_total, backup_label)
 
-      # Create backup config wrapper
       backup_config = BackupConfig.new(repo_config, merged_config)
       backup = Backup.new(repo, config: backup_config, retention_mode: retention_mode, repo_name: repo_name,
-                                logger: @logger, skip_hash_check: skip_hash_check)
+                                logger: @logger, skip_hash_check: skip_hash_check, progress: progress)
 
       archive_name = options[:name] ? sanitize_archive_name(options[:name]) : nil
       @logger.info("Creating archive#{"s" if retention_mode == "per_file"}: #{archive_name || "auto-generated"}")
@@ -640,27 +750,55 @@ module Ruborg
       backup.create(name: archive_name, remove_source: options[:remove_source])
       @logger.info("Backup created successfully")
 
-      if retention_mode == "per_file"
-        puts "✓ Per-file backups created"
-      else
-        puts "✓ Backup created: #{archive_name || "auto-generated"}"
-      end
       puts "  Sources removed" if options[:remove_source]
 
-      # Auto-prune if configured and retention policy exists
-      # Use strict boolean checking: only true enables, everything else disables
-      auto_prune = merged_config["auto_prune"]
-      auto_prune = false unless auto_prune == true
-      retention_policy = merged_config["retention"]
-
-      return unless auto_prune && retention_policy && !retention_policy.empty?
+      return unless will_prune
 
       mode_desc = retention_mode == "per_file" ? "per-file mode" : "standard mode"
+      progress.stage(3, stage_total, "Pruning old archives (#{mode_desc})")
+      progress.spin("Pruning...")
       @logger.info("Auto-pruning repository: #{repo_name} (#{mode_desc})")
-      puts "  Pruning old backups (#{mode_desc})..."
       repo.prune(retention_policy, retention_mode: retention_mode)
       @logger.info("Pruning completed successfully for #{repo_name}")
-      puts "  ✓ Pruning completed"
+      progress.done("Pruning completed")
+    end
+
+    def wait_for_lock_clear(repo, repo_name, lock_wait, progress)
+      return unless repo.locked?
+
+      @logger.warn("Repository '#{repo_name}' is locked — waiting up to #{lock_wait}s")
+      elapsed = 0
+      interval = 5
+
+      progress.spin("Repository locked — waiting for lock to clear (0s / #{lock_wait}s)…")
+
+      while repo.locked? && elapsed < lock_wait
+        sleep interval
+        elapsed += interval
+        progress.spin("Repository locked — waiting for lock to clear (#{elapsed}s / #{lock_wait}s)…")
+      end
+
+      progress.stop_spin
+
+      if repo.locked?
+        raise BorgError,
+              "Repository '#{repo_name}' is still locked after #{lock_wait}s. " \
+              "Run 'ruborg lock --repository #{repo_name}' to inspect, or " \
+              "'ruborg lock --repository #{repo_name} --break --yes' to clear."
+      end
+
+      @logger.info("Lock cleared for '#{repo_name}' after #{elapsed}s")
+    end
+
+    def build_repo(repo_path, merged_config, passphrase)
+      Repository.new(
+        repo_path,
+        passphrase: passphrase,
+        borg_options: merged_config["borg_options"] || {},
+        borg_path: merged_config["borg_path"],
+        lock_wait: merged_config["lock_wait"]&.to_i,
+        logger: @logger
+      )
     end
 
     def fetch_passphrase_for_repo(repo_config)

data/lib/ruborg/config.rb

@@ -41,7 +41,7 @@ module Ruborg
 
     def global_settings
       @data.slice("passbolt", "compression", "encryption", "auto_init", "borg_options", "log_file", "retention",
-                  "auto_prune", "hostname", "allow_remove_source", "borg_path", "skip_hash_check")
+                  "auto_prune", "hostname", "allow_remove_source", "borg_path", "skip_hash_check", "lock_wait")
     end
 
     private
@@ -54,12 +54,12 @@ module Ruborg
     # Valid configuration keys at each level
     VALID_GLOBAL_KEYS = %w[
       hostname compression encryption auto_init auto_prune allow_remove_source
-      log_file borg_path passbolt borg_options retention repositories skip_hash_check
+      log_file borg_path passbolt borg_options retention repositories skip_hash_check lock_wait
     ].freeze
 
     VALID_REPOSITORY_KEYS = %w[
       name description path hostname retention_mode passbolt retention sources
-      compression encryption auto_init auto_prune borg_options allow_remove_source skip_hash_check
+      compression encryption auto_init auto_prune borg_options allow_remove_source skip_hash_check lock_wait
     ].freeze
 
     VALID_SOURCE_KEYS = %w[name paths exclude].freeze

data/lib/ruborg/progress.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Ruborg
+  # Terminal progress display: named stages, inline progress bar, and spinner.
+  # Writes to $stderr so stdout remains clean for --json or piped output.
+  # Degrades to plain text lines when output is not a TTY (piped / redirected).
+  class Progress
+    SPINNER_FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+    BAR_WIDTH = 28
+    LINE_WIDTH = 80
+
+    def initialize(output: $stderr)
+      @output = output
+      @tty = output.respond_to?(:isatty) && output.isatty
+      @spinner_thread = nil
+    end
+
+    # Print a numbered stage header: "[2/3] Label"
+    def stage(index, total, label)
+      stop_spin
+      clear_line if @tty
+      @output.puts "[#{index}/#{total}] #{label}"
+    end
+
+    # Start a spinner on the current line for an indeterminate operation.
+    # Call stop_spin (or done) to halt it.
+    def spin(label)
+      stop_spin
+      return unless @tty
+
+      frame = 0
+      @spinner_thread = Thread.new do
+        loop do
+          @output.print "\r  #{SPINNER_FRAMES[frame % SPINNER_FRAMES.size]}  #{label}"
+          frame += 1
+          sleep 0.1
+        end
+      end
+    end
+
+    # Stop the spinner and erase its line.
+    def stop_spin
+      return unless @spinner_thread
+
+      @spinner_thread.kill
+      @spinner_thread.join(0.2)
+      @spinner_thread = nil
+      clear_line if @tty
+    end
+
+    # Redraw an inline progress bar. Call once per item in a loop.
+    # label is truncated to fit the terminal line.
+    def bar(current, total, label = "")
+      return unless @tty
+
+      pct = total.positive? ? (current.to_f / total) : 0
+      filled = (BAR_WIDTH * pct).round
+      bar_str = filled.positive? ? "#{"=" * (filled - 1)}>" : ""
+      bar_str = bar_str.ljust(BAR_WIDTH)
+      short_label = truncate_left(label.to_s, 28)
+      @output.print "\r  [#{bar_str}]  #{current}/#{total}  #{short_label.ljust(28)}"
+    end
+
+    # Halt any in-progress display and print a completion line.
+    def done(label = nil)
+      stop_spin
+      clear_line if @tty
+      @output.puts "  ✓ #{label}" if label
+    end
+
+    private
+
+    def clear_line
+      @output.print "\r#{" " * LINE_WIDTH}\r"
+    end
+
+    def truncate_left(str, max)
+      str.length > max ? "...#{str[-(max - 3)..]}" : str
+    end
+  end
+end

data/lib/ruborg/repository.rb

@@ -6,11 +6,13 @@ module Ruborg
   class Repository
     attr_reader :path, :borg_path
 
-    def initialize(path, passphrase: nil, borg_options: {}, borg_path: nil, logger: nil)
+    def initialize(path, passphrase: nil, borg_options: {}, borg_path: nil, lock_wait: nil, logger: nil)
+      @original_path = path
       @path = validate_repo_path(path)
       @passphrase = passphrase
       @borg_options = borg_options
       @borg_path = validate_borg_path(borg_path || "borg")
+      @lock_wait = lock_wait&.to_i
       @logger = logger
     end
 
@@ -18,6 +20,37 @@ module Ruborg
       File.directory?(@path) && File.exist?(File.join(@path, "config"))
     end
 
+    MINIMUM_BORG_VERSION = "1.4.0"
+
+    def locked?
+      File.exist?(File.join(@path, "lock.exclusive")) ||
+        File.exist?(File.join(@path, "lock.roster"))
+    end
+
+    def break_lock
+      raise BorgError, "Repository does not exist at #{@path}" unless exists?
+
+      check_borg_version!
+      cmd = [@borg_path, "break-lock", @path]
+      execute_borg_command(cmd)
+      @logger&.info("Lock broken for repository at #{@path}")
+    end
+
+    def force_break_lock
+      raise BorgError, "Repository does not exist at #{@path}" unless exists?
+
+      require "fileutils"
+      removed = %w[lock.exclusive lock.roster].select do |name|
+        target = File.join(@path, name)
+        next false unless File.exist?(target)
+
+        FileUtils.rm_rf(target)
+        true
+      end
+      @logger&.info("Force-removed lock files at #{@path}: #{removed.join(", ")}")
+      removed
+    end
+
     def create
       raise BorgError, "Repository already exists at #{@path}" if exists?
 
@@ -278,62 +311,67 @@ module Ruborg
       nil # Failed to parse, skip this archive
     end
 
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def get_archives_grouped_by_source_dir
       require "json"
       require "time"
       require "open3"
 
-      # Get list of all archives
       cmd = [@borg_path, "list", @path, "--json"]
       env = build_borg_env
 
       stdout, stderr, status = Open3.capture3(env, *cmd)
       raise BorgError, "Failed to list archives: #{stderr}" unless status.success?
 
-      json_data = JSON.parse(stdout)
-      archives = json_data["archives"] || []
-
-      # Group archives by source directory from metadata
+      archives = JSON.parse(stdout)["archives"] || []
+      cache = ArchiveCache.new(@original_path).fetch
       archives_by_source = Hash.new { |h, k| h[k] = [] }
 
       archives.each do |archive|
         archive_name = archive["name"]
-
-        # Get archive info to read comment (metadata)
-        info_cmd = [@borg_path, "info", "#{@path}::#{archive_name}", "--json"]
-        info_stdout, _, info_status = Open3.capture3(env, *info_cmd)
-
-        unless info_status.success?
-          # If we can't get info, put in legacy group
-          archives_by_source[""] << {
-            name: archive_name,
-            time: Time.parse(archive["time"])
-          }
-          next
-        end
-
-        info_data = JSON.parse(info_stdout)
-        comment = info_data.dig("archives", 0, "comment") || ""
-
-        # Parse source_dir from comment
-        # Format: path|||size|||hash|||source_dir
-        source_dir = if comment.include?("|||")
-                       parts = comment.split("|||")
-                       parts.length >= 4 ? (parts[3] || "") : ""
+        archive_time = Time.parse(archive["time"])
+
+        metadata = if (cached = cache[archive_name])
+                     cached
+                   else
+                     info_cmd = [@borg_path, "info", "#{@path}::#{archive_name}", "--json"]
+                     info_stdout, _, info_status = Open3.capture3(env, *info_cmd)
+
+                     if info_status.success?
+                       comment = JSON.parse(info_stdout).dig("archives", 0, "comment") || ""
+                       parsed = parse_archive_comment(comment)
+                       cache.store(archive_name, parsed)
+                       parsed
                      else
-                       ""
+                       cache.store(archive_name, { path: "", size: 0, hash: "", source_dir: "" })
+                       { path: "", size: 0, hash: "", source_dir: "" }
                      end
+                   end
 
-        archives_by_source[source_dir] << {
-          name: archive_name,
-          time: Time.parse(archive["time"])
-        }
+        archives_by_source[metadata[:source_dir] || ""] << { name: archive_name, time: archive_time }
       end
 
+      cache.save_if_changed
       archives_by_source
     rescue JSON::ParserError => e
       raise BorgError, "Failed to parse archive metadata: #{e.message}"
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    def parse_archive_comment(comment)
+      if comment.include?("|||")
+        parts = comment.split("|||")
+        if parts.length >= 4
+          { path: parts[0], size: parts[1].to_i, hash: parts[2] || "", source_dir: parts[3] || "" }
+        elsif parts.length >= 3
+          { path: parts[0], size: parts[1].to_i, hash: parts[2] || "", source_dir: "" }
+        else
+          { path: parts[0], size: 0, hash: parts[1] || "", source_dir: "" }
+        end
+      else
+        { path: comment, size: 0, hash: "", source_dir: "" }
+      end
+    end
 
     def prune_per_directory_standard(retention_policy)
       # Apply standard retention policies (keep_daily, etc.) per source directory
@@ -587,6 +625,26 @@ module Ruborg
       borg_path
     end
 
+    def inject_lock_wait(cmd)
+      return cmd if @lock_wait.nil? || cmd[1] == "break-lock"
+
+      [cmd[0], "--lock-wait", @lock_wait.to_s] + cmd[1..]
+    end
+
+    def check_borg_version!
+      version = self.class.borg_version(@borg_path)
+      return if version_sufficient?(version, MINIMUM_BORG_VERSION)
+
+      raise BorgError,
+            "Borg #{MINIMUM_BORG_VERSION}+ is required but found #{version}. Please upgrade Borg."
+    end
+
+    def version_sufficient?(actual, minimum)
+      actual_parts  = actual.split(".").map(&:to_i)
+      minimum_parts = minimum.split(".").map(&:to_i)
+      (actual_parts <=> minimum_parts) >= 0
+    end
+
     def find_in_path(command)
       ENV["PATH"].split(File::PATH_SEPARATOR).each do |directory|
         path = File.join(directory, command)
@@ -610,6 +668,9 @@ module Ruborg
       env["BORG_RELOCATED_REPO_ACCESS_IS_OK"] = allow_relocated ? "yes" : "no"
       env["BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK"] = allow_unencrypted ? "yes" : "no"
 
+      # Inject --lock-wait for all commands except break-lock (which breaks, not acquires)
+      cmd = inject_lock_wait(cmd)
+
       # Redirect stdin from /dev/null to prevent interactive prompts
       result = system(env, *cmd, in: "/dev/null")
       raise BorgError, "Borg command failed: #{cmd.join(" ")}" unless result

data/lib/ruborg/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruborg
-  VERSION = "0.9.0"
+  VERSION = "0.9.3"
 end

data/lib/ruborg.rb

@@ -3,6 +3,9 @@
 require_relative "ruborg/version"
 require_relative "ruborg/logger"
 require_relative "ruborg/config"
+require_relative "ruborg/archive_cache"
+require_relative "ruborg/catalog"
+require_relative "ruborg/progress"
 require_relative "ruborg/repository"
 require_relative "ruborg/backup"
 require_relative "ruborg/passbolt"
@@ -13,4 +16,5 @@ module Ruborg
   class ConfigError < Error; end
   class BorgError < Error; end
   class PassboltError < Error; end
+  class CatalogError < Error; end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ruborg
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.3
 platform: ruby
 authors:
 - Michail Pantelelis
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: psych
@@ -144,11 +143,14 @@ files:
 - SECURITY.md
 - exe/ruborg
 - lib/ruborg.rb
+- lib/ruborg/archive_cache.rb
 - lib/ruborg/backup.rb
+- lib/ruborg/catalog.rb
 - lib/ruborg/cli.rb
 - lib/ruborg/config.rb
 - lib/ruborg/logger.rb
 - lib/ruborg/passbolt.rb
+- lib/ruborg/progress.rb
 - lib/ruborg/repository.rb
 - lib/ruborg/version.rb
 - ruborg.gemspec
@@ -161,7 +163,6 @@ metadata:
   source_code_uri: https://github.com/mpantel/ruborg.git
   changelog_uri: https://github.com/mpantel/ruborg/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -176,8 +177,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.7.1
 specification_version: 4
 summary: A friendly Ruby frontend for Borg backup
 test_files: []