ruborg 0.6.2 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 310a71ee8419f02ac2bee2fc03438a9d7b85e838e911202d99bb933bd21564d1
-  data.tar.gz: c7785d3fa514d20c901bd53b0923d0ccc044fa4fbf69b616009ba1ef16be9451
+  metadata.gz: 5b1659a54e64ed15742467c6e95ea96fd311f0332e2fafdee7e560cec5c2385c
+  data.tar.gz: ec49de1e1231ad2bd189e08aedb70d22ec10f4f322f1b4690c9c3ec41be590bb
 SHA512:
-  metadata.gz: 3532053d345494458c7c4eeee5c79808e73748d95360d71cac880d3db29a14205a4028c8d83aecff4a3fce3db217cf090403053be6fd860609d306271ee9c687
-  data.tar.gz: 0a22d49b96fb91c79eb3d5ee264f524f8712ca40c61523be12b0186e9a604c0e77e1d8f9507f970edefa21802c0bd74176e6db89c8d75c8234caef25fad0a57a
+  metadata.gz: '0593d8521ab13110b3fefe00b9a1bc3cd6a8c28ffa70e93dda6e3bfa6b763f0562abd564af25a14c5619b2fe7dabb7ef76ffbe1341c6dcdb4dcac7efbb7be847'
+  data.tar.gz: 9486465c9803962569b5f376556efafa8147d72a294e9a6e3137d29e67c9664b212bed69addc0bab0ad434ddc5f42416e3aa7426087bbf4dd7c9a4ce2c71192f

data/CHANGELOG.md

@@ -7,6 +7,93 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.1] - 2025-10-08
+
+### Added
+- **Paranoid Mode Duplicate Detection**: Per-file backup mode now uses SHA256 content hashing to detect duplicate files
+  - Skips unchanged files automatically (same path, size, and content hash)
+  - Creates versioned archives (-v2, -v3) when content changes but modification time stays the same
+  - Protects against edge cases where files are modified with manual `touch -t` operations
+  - Archive metadata stores: `path|||size|||hash` for comprehensive verification
+  - Backward compatible with old archive formats (plain path, path|||hash)
+- **Smart Skip Statistics**: Backup completion messages show both backed-up and skipped file counts
+  - Example: "✓ Per-file backup completed: 50000 file(s) backed up, 26456 skipped (unchanged)"
+  - Provides visibility into deduplication efficiency
+
+### Fixed
+- **Per-File Backup Archive Collision**: Fixed "Archive already exists" error in per-file backup mode
+  - Archives are now verified by path, size, and content hash before skipping
+  - Different files with same archive name get automatic version suffixes
+  - File size changes detected even when modification time is manually reset
+  - Logs warning messages for collision scenarios with detailed context
+
+### Changed
+- **Archive Comment Format**: Per-file archives now store comprehensive metadata
+  - New format: `path|||size|||hash` (three-part delimiter-based format)
+  - Enables instant duplicate detection without re-hashing files
+  - Backward compatible parsing handles old formats gracefully
+- **Enhanced Collision Handling**: Intelligent version suffix generation
+  - Appends `-v2`, `-v3`, etc. for archive name collisions
+  - Prevents data loss from conflicting archive names
+  - Logs warnings for all collision scenarios
+
+### Security
+- **No Security Impact**: Security review found no exploitable vulnerabilities in new features
+  - Content hashing uses SHA256 (cryptographically secure)
+  - Archive comment parsing uses safe string splitting (no injection risks)
+  - File paths from archives only used for comparison, not file operations
+  - Array-based command execution prevents shell injection
+  - JSON parsing uses Ruby's safe `JSON.parse()` with error handling
+  - All existing security controls maintained
+
+## [0.7.0] - 2025-10-08
+
+### Added
+- **List Files in Archives**: New `--archive` option for list command to view files within a specific archive
+  - `ruborg list --repository documents --archive archive-name`
+  - Lists all files and directories contained in the specified archive
+  - Useful for finding specific files before restore operations
+- **File Metadata Retrieval**: New `metadata` command to retrieve detailed file information from archives
+  - `ruborg metadata ARCHIVE --repository documents --file /path/to/file`
+  - Auto-detects per-file archives and retrieves metadata without --file option
+  - Displays file size (human-readable), modification time, permissions, owner, group, and type
+  - Supports both standard and per-file archive modes
+- **Version Command**: New `ruborg version` command to display current ruborg version
+- **Enhanced Archive Naming**: Per-file archives now include actual filename in archive name
+  - Changed from `repo-hash-timestamp` to `repo-filename-hash-timestamp`
+  - Makes archive names human-readable and easier to identify
+  - Automatic filename sanitization (alphanumeric, dash, underscore, dot only)
+- **Smart Filename Truncation**: Archive names limited to 255 characters (filesystem limit)
+  - Intelligent truncation preserves file extensions when possible
+  - Handles very long filenames and repository names gracefully
+  - Example: `very-long-name...truncated.sql` becomes `very-lon.sql` with hash and timestamp
+- **File Modification Time in Archives**: Per-file mode uses file mtime instead of backup time
+  - Archive timestamps reflect when files were last modified, not when backup ran
+  - More accurate for tracking file changes over time
+  - Enables better retention based on actual file activity
+
+### Changed
+- **Separated Console Output from Logs**: Console now shows progress, logs show results
+  - Console displays repository headers, progress indicators, and completion messages
+  - Logs contain structured operational data with timestamps
+  - Repository name appears in both console headers and log entries (format: `[repo_name]`)
+  - Cleaner separation between user feedback and audit trails
+- **Enhanced Logging**: More detailed logging for backup operations
+  - Standard mode: Logs archive name with source count
+  - Per-file mode: Logs each file with its archive name
+  - Repository name prefix in all log entries for multi-repo clarity
+
+### Security
+- **Archive Name Validation**: Enhanced sanitization for archive names containing filenames
+  - Whitelist approach allows only safe characters: `[a-zA-Z0-9._-]`
+  - Replaces unsafe characters with underscores
+  - Prevents injection attacks via malicious filenames
+  - Archive names still passed as array elements to prevent shell injection
+- **Path Normalization**: Improved file path handling in metadata retrieval
+  - Correctly handles borg's path format (strips leading slash)
+  - Safe matching within JSON data from borg
+  - No path traversal vulnerabilities introduced
+
 ## [0.6.2] - 2025-10-08
 
 ### Fixed

data/README.md

@@ -25,7 +25,7 @@ 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 (220 examples, 0 failures)
+- ✅ **Well-tested** - Comprehensive test suite with RSpec (286+ examples)
 - 🔒 **Security-focused** - Path validation, safe YAML loading, command injection protection
 
 ## Prerequisites
@@ -401,8 +401,11 @@ Current value: "true" (String). Set 'allow_remove_source: true' in configuration
 ### List Archives
 
 ```bash
-# List archives for a specific repository
+# List all archives for a specific repository
 ruborg list --repository documents
+
+# List files within a specific archive
+ruborg list --repository documents --archive archive-name
 ```
 
 ### Restore from Archive
@@ -434,6 +437,40 @@ The `info` command without `--repository` displays a summary showing:
 - Retention policies (global and per-repository overrides)
 - Number of sources per repository
 
+### Get File Metadata from Archives
+
+```bash
+# Get metadata from per-file archive (auto-detects single file)
+ruborg metadata archive-name --repository documents
+
+# Get metadata for specific file in standard archive
+ruborg metadata archive-name --repository documents --file /path/to/file.txt
+```
+
+The `metadata` command displays detailed file information:
+- File path
+- Size (human-readable format)
+- Modification time
+- File permissions (mode)
+- Owner and group
+- File type
+
+**Example output:**
+```
+═══════════════════════════════════════════════════════════════
+  FILE METADATA
+═══════════════════════════════════════════════════════════════
+
+Archive: databases-backup.sql-8b4c26d05aae-2025-10-08_19-05-07
+File: var/backups/database.sql
+Size: 45.67 MB
+Modified: 2025-10-08T19:05:07.123456
+Mode: -rw-r--r--
+User: postgres
+Group: postgres
+Type: regular file
+```
+
 ### Check Repository Compatibility
 
 ```bash
@@ -468,6 +505,13 @@ Borg version: 1.2.8
     Please upgrade Borg or migrate the repository
 ```
 
+### Show Version
+
+```bash
+# Display ruborg version
+ruborg version
+```
+
 ## Passbolt Integration
 
 Ruborg can retrieve encryption passphrases from Passbolt using the Passbolt CLI:
@@ -610,10 +654,12 @@ See [SECURITY.md](SECURITY.md) for detailed security information and best practi
 | `init REPOSITORY` | Initialize a new Borg repository | `--passphrase`, `--passbolt-id`, `--log` |
 | `validate` | Validate configuration file for type errors | `--config`, `--log` |
 | `backup` | Create a backup using config file | `--config`, `--repository`, `--all`, `--name`, `--remove-source`, `--log` |
-| `list` | List all archives in repository | `--config`, `--repository`, `--log` |
+| `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` |
 | `info` | Show repository information | `--config`, `--repository`, `--log` |
 | `check` | Check repository integrity and compatibility | `--config`, `--repository`, `--all`, `--verify-data`, `--log` |
+| `version` | Show ruborg version | None |
 
 ### Options
 
@@ -729,9 +775,12 @@ repositories:
 
 **How it works:**
 - **Per-File Archives**: Each file is backed up as a separate Borg archive
-- **Hash-Based Naming**: Archives are named `repo-{hash}-{timestamp}` (hash uniquely identifies the file path)
-- **Original Path Stored**: The complete original file path is stored in the archive comment
+- **Hash-Based Naming**: Archives are named `repo-filename-{hash}-{timestamp}` (hash uniquely identifies the file path)
+- **Metadata Storage**: Archive comments store `path|||size|||hash` for comprehensive duplicate detection
 - **Metadata Preservation**: Borg preserves all file metadata (mtime, size, permissions) in the archive
+- **Paranoid Mode Duplicate Detection** (v0.7.1+): SHA256 content hashing detects file changes even when size and mtime are identical
+- **Smart Skip**: Automatically skips unchanged files during backup (compares path, size, and content hash)
+- **Version Suffixes**: Creates versioned archives (`-v2`, `-v3`) for archive name collisions, preventing data loss
 - **Smart Pruning**: Retention reads file mtime directly from archives - works even after files are deleted
 
 **File Metadata Retention Options:**

data/SECURITY.md

@@ -229,6 +229,32 @@ We will respond within 48 hours and work with you to address the issue.
 
 ## Security Audit History
 
+- **v0.7.1** (2025-10-08): Paranoid mode duplicate detection - security review passed
+  - **NEW FEATURE**: SHA256 content hashing for detecting file changes even when mtime/size are identical
+  - **NEW FEATURE**: Smart skip statistics showing backed-up and skipped file counts
+  - **BUG FIX**: Fixed "Archive already exists" error in per-file backup mode
+  - **ENHANCED**: Archive comment format now stores comprehensive metadata (`path|||size|||hash`)
+  - **ENHANCED**: Version suffix generation for archive name collisions (`-v2`, `-v3`)
+  - **SECURITY REVIEW**: Comprehensive security analysis found no exploitable vulnerabilities
+  - SHA256 hashing is cryptographically secure (using Ruby's Digest::SHA256)
+  - Archive comment parsing uses safe string splitting with `|||` delimiter (no injection risks)
+  - File paths from archives only used for comparison, never for file operations
+  - Array-based command execution prevents shell injection (maintained from previous versions)
+  - JSON parsing uses Ruby's safe `JSON.parse()` with error handling
+  - All existing security controls maintained - no security regressions
+  - Backward compatibility with three metadata formats (plain path, path|||hash, path|||size|||hash)
+
+- **v0.7.0** (2025-10-08): Archive naming and metadata features - security review passed
+  - **NEW FEATURE**: List files within archives (--archive option)
+  - **NEW FEATURE**: File metadata retrieval from archives
+  - **NEW FEATURE**: Enhanced archive naming with filenames in per-file mode
+  - **SECURITY REVIEW**: Comprehensive security analysis found no exploitable vulnerabilities
+  - Archive name sanitization uses whitelist approach `[a-zA-Z0-9._-]`
+  - Array-based command execution prevents shell injection
+  - Safe JSON parsing without deserialization risks
+  - Path normalization handles borg's format safely (strips leading slash for matching only)
+  - All new features maintain existing security controls
+
 - **v0.6.1** (2025-10-08): Enhanced logging with sensitive data protection
   - **NEW FEATURE**: Comprehensive logging for backup operations, restoration, and deletion
   - Passwords and passphrases are NEVER logged (neither CLI nor Passbolt passwords)

data/lib/ruborg/backup.rb

@@ -25,41 +25,125 @@ 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}"
+
       cmd = build_create_command(archive_name)
 
       execute_borg_command(cmd)
 
+      # Log successful action
+      @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
       files_to_backup = collect_files_from_paths(@config.backup_paths, @config.exclude_patterns)
 
       raise BorgError, "No files found to backup" if files_to_backup.empty?
 
-      @logger&.info("Per-file mode: Found #{files_to_backup.size} file(s) to backup")
+      # Get list of existing archives for duplicate detection
+      existing_archives = get_existing_archive_names
 
-      timestamp = Time.now.strftime("%Y-%m-%d_%H-%M-%S")
+      # Show repository header in console only
+      print_repository_header
 
+      puts "Found #{files_to_backup.size} file(s) to backup"
+
+      backed_up_count = 0
+      skipped_count = 0
+
+      # rubocop:disable Metrics/BlockLength
       files_to_backup.each_with_index do |file_path, index|
-        # Generate hash-based archive name
+        # Generate hash-based archive name with filename
         path_hash = generate_path_hash(file_path)
-        archive_name = name_prefix || "#{@repo_name}-#{path_hash}-#{timestamp}"
-
-        @logger&.info("Backing up file #{index + 1}/#{files_to_backup.size}: #{file_path}")
+        filename = File.basename(file_path)
+        sanitized_filename = sanitize_filename(filename)
+
+        # Use file modification time for timestamp (not backup creation time)
+        file_mtime = File.mtime(file_path).strftime("%Y-%m-%d_%H-%M-%S")
+
+        # 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}"
+
+        # Check if archive already exists AND contains this exact file
+        if existing_archives.key?(archive_name)
+          stored_info = existing_archives[archive_name]
+          if stored_info[:path] == file_path
+            # Same file, same mtime -> check if size changed (rare: manual content edit + touch -t)
+            current_size = File.size(file_path)
+            stored_size = stored_info[:size]
+
+            if current_size == stored_size
+              # Size same -> verify content hasn't changed (paranoid mode)
+              current_hash = calculate_file_hash(file_path)
+              stored_hash = stored_info[:hash]
+
+              if current_hash == stored_hash
+                # Content truly unchanged
+                puts " - Archive already exists (file unchanged)"
+                @logger&.info(
+                  "[#{@repo_name}] Skipped #{file_path} - archive #{archive_name} already exists (file unchanged)"
+                )
+                skipped_count += 1
+                next
+              else
+                # Size same but content changed (rare: edited + truncated/padded to same size)
+                archive_name = find_next_version_name(archive_name, existing_archives)
+                @logger&.warn(
+                  "[#{@repo_name}] File content changed but size/mtime unchanged for #{file_path}, " \
+                  "using #{archive_name}"
+                )
+              end
+            else
+              # Size changed but mtime same -> content changed, add version suffix
+              archive_name = find_next_version_name(archive_name, existing_archives)
+              @logger&.warn(
+                "[#{@repo_name}] File size changed but mtime unchanged for #{file_path}, using #{archive_name}"
+              )
+            end
+          else
+            # Different file, same archive name -> add version suffix
+            archive_name = find_next_version_name(archive_name, existing_archives)
+            @logger&.warn(
+              "[#{@repo_name}] Archive name collision: #{archive_name} exists for different file, using version suffix"
+            )
+          end
+        end
 
         # Create archive for single file with original path as comment
         cmd = build_per_file_create_command(archive_name, file_path)
 
         execute_borg_command(cmd)
+        puts ""
+
+        # Log successful action with details
+        @logger&.info("[#{@repo_name}] Archived #{file_path} in archive #{archive_name}")
+        backed_up_count += 1
       end
+      # rubocop:enable Metrics/BlockLength
 
-      @logger&.info("Per-file backup completed: #{files_to_backup.size} file(s) backed up")
+      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
 
       # NOTE: remove_source handled per file after successful backup
       remove_source_files if remove_source
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity, Metrics/BlockNesting
 
     def collect_files_from_paths(paths, exclude_patterns)
       require "find"
@@ -97,12 +181,79 @@ module Ruborg
       Digest::SHA256.hexdigest(file_path)[0...12]
     end
 
+    def sanitize_filename(filename)
+      # Remove or replace characters that are not safe for archive names
+      # Allow alphanumeric, dash, underscore, and dot
+      sanitized = filename.gsub(/[^a-zA-Z0-9._-]/, "_")
+
+      # Ensure the sanitized name is not empty
+      sanitized = "file" if sanitized.empty? || sanitized.strip.empty?
+
+      sanitized
+    end
+
+    def build_archive_name(repo_name, sanitized_filename, path_hash, timestamp)
+      # Maximum filename length for most filesystems (ext4, NTFS, APFS)
+      max_length = 255
+
+      # Calculate fixed portions: separators (3) + hash (12) + timestamp (19)
+      fixed_length = 3 + path_hash.length + timestamp.length
+      repo_name_length = repo_name ? repo_name.length : 0
+
+      # Calculate available space for filename
+      available_for_filename = max_length - fixed_length - repo_name_length
+
+      # Truncate filename if necessary, preserving file extension if possible
+      truncated_filename = if sanitized_filename.length > available_for_filename
+                             truncate_with_extension(sanitized_filename, available_for_filename)
+                           else
+                             sanitized_filename
+                           end
+
+      "#{repo_name}-#{truncated_filename}-#{path_hash}-#{timestamp}"
+    end
+
+    def truncate_with_extension(filename, max_length)
+      return "" if max_length <= 0
+      return filename if filename.length <= max_length
+
+      # Try to preserve extension (last .xxx)
+      if filename.include?(".") && filename !~ /^\./
+        parts = filename.rpartition(".")
+        basename = parts[0]
+        extension = parts[2]
+
+        # Reserve space for extension plus dot
+        extension_length = extension.length + 1
+
+        if extension_length < max_length
+          basename_max = max_length - extension_length
+          "#{basename[0...basename_max]}.#{extension}"
+        else
+          # Extension too long, just truncate entire filename
+          filename[0...max_length]
+        end
+      else
+        # No extension, just truncate
+        filename[0...max_length]
+      end
+    end
+
+    def calculate_file_hash(file_path)
+      require "digest"
+      Digest::SHA256.file(file_path).hexdigest
+    end
+
     def build_per_file_create_command(archive_name, file_path)
       cmd = [@repository.borg_path, "create"]
       cmd += ["--compression", @config.compression]
 
-      # Store original path in archive comment for retrieval
-      cmd += ["--comment", file_path]
+      # Store file metadata (path + size + hash) in archive comment for duplicate detection
+      # Format: path|||size|||hash (using ||| as delimiter to avoid conflicts with paths)
+      file_size = File.size(file_path)
+      file_hash = calculate_file_hash(file_path)
+      metadata = "#{file_path}|||#{file_size}|||#{file_hash}"
+      cmd += ["--comment", metadata]
 
       cmd << "#{@repository.path}::#{archive_name}"
       cmd << file_path
@@ -250,5 +401,95 @@ module Ruborg
         File.expand_path(path)
       end
     end
+
+    def print_repository_header
+      puts "\n#{"=" * 60}"
+      puts "  Repository: #{@repo_name}"
+      puts "=" * 60
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity
+    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)
+      env["BORG_PASSPHRASE"] = passphrase if passphrase
+      env["BORG_RELOCATED_REPO_ACCESS_IS_OK"] = "yes"
+      env["BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK"] = "yes"
+
+      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"] || []
+
+      # 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|
+        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: "" }
+          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 (using ||| as delimiter)
+        # For backward compatibility, handle old formats:
+        #   - Old format 1: plain path (no |||)
+        #   - Old format 2: path|||hash (2 parts)
+        #   - New format: path|||size|||hash (3 parts)
+        if comment.include?("|||")
+          parts = comment.split("|||")
+          file_path = parts[0]
+          if parts.length >= 3
+            # New format: path|||size|||hash
+            file_size = parts[1].to_i
+            file_hash = parts[2] || ""
+          else
+            # Old format: path|||hash (size not available)
+            file_size = 0
+            file_hash = parts[1] || ""
+          end
+        else
+          # Oldest format: comment is just the path string
+          file_path = comment
+          file_size = 0
+          file_hash = ""
+        end
+
+        hash[archive_name] = {
+          path: file_path,
+          size: file_size,
+          hash: file_hash
+        }
+      end
+    rescue JSON::ParserError => e
+      raise BorgError, "Failed to parse archive info: #{e.message}"
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+    def find_next_version_name(base_name, existing_archives)
+      version = 2
+      loop do
+        versioned_name = "#{base_name}-v#{version}"
+        return versioned_name unless existing_archives.key?(versioned_name)
+
+        version += 1
+      end
+    end
   end
 end

data/lib/ruborg/cli.rb

@@ -60,9 +60,9 @@ module Ruborg
       raise
     end
 
-    desc "list", "List all archives in the repository"
+    desc "list", "List all archives in the repository or files in a specific archive"
+    option :archive, type: :string, desc: "Archive name to list files from"
     def list
-      @logger.info("Listing archives in repository")
       config = Config.new(options[:config])
 
       raise ConfigError, "Please specify --repository" unless options[:repository]
@@ -77,7 +77,8 @@ module Ruborg
       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 = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
+                                                 logger: @logger)
 
       # Auto-initialize repository if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -89,10 +90,17 @@ module Ruborg
         puts "Repository auto-initialized at #{repo_config["path"]}"
       end
 
-      repo.list
-      @logger.info("Successfully listed archives")
+      if options[:archive]
+        @logger.info("Listing files in archive: #{options[:archive]}")
+        repo.list_archive(options[:archive])
+        @logger.info("Successfully listed files in archive")
+      else
+        @logger.info("Listing archives in repository")
+        repo.list
+        @logger.info("Successfully listed archives")
+      end
     rescue Error => e
-      @logger.error("Failed to list archives: #{e.message}")
+      @logger.error("Failed to list: #{e.message}")
       raise
     end
 
@@ -116,7 +124,8 @@ module Ruborg
       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 = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
+                                                 logger: @logger)
 
       # Create backup config wrapper for compatibility
       backup_config = BackupConfig.new(repo_config, merged_config)
@@ -155,7 +164,8 @@ module Ruborg
       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 = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
+                                                 logger: @logger)
 
       # Auto-initialize repository if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -234,7 +244,8 @@ module Ruborg
 
         if errors.any?
           puts "Configuration has errors that must be fixed.\n\n"
-          raise ConfigError, "Configuration validation failed"
+          @logger.error("Configuration validation failed")
+          exit 1
         else
           puts "Configuration is valid but has warnings.\n\n"
         end
@@ -246,76 +257,57 @@ module Ruborg
       raise
     end
 
-    desc "validate", "Validate configuration file for errors and type issues"
-    def validate_config
-      @logger.info("Validating configuration file: #{options[:config]}")
+    desc "version", "Show ruborg version"
+    def version
+      require_relative "version"
+      puts "ruborg #{Ruborg::VERSION}"
+      @logger.info("Version checked: #{Ruborg::VERSION}")
+    end
+
+    desc "metadata ARCHIVE", "Get file metadata from an archive"
+    option :file, type: :string, desc: "Specific file path (required for standard archives, auto for per-file)"
+    def metadata(archive_name)
+      @logger.info("Getting metadata for archive: #{archive_name}")
       config = Config.new(options[:config])
 
-      puts "\n═══════════════════════════════════════════════════════════════"
-      puts "  CONFIGURATION VALIDATION"
-      puts "═══════════════════════════════════════════════════════════════\n\n"
+      raise ConfigError, "Please specify --repository" unless options[:repository]
 
-      errors = []
-      warnings = []
+      repo_config = config.get_repository(options[:repository])
+      raise ConfigError, "Repository '#{options[:repository]}' not found" unless repo_config
 
-      # Validate global boolean settings
       global_settings = config.global_settings
-      errors.concat(validate_boolean_setting(global_settings, "auto_init", "global"))
-      errors.concat(validate_boolean_setting(global_settings, "auto_prune", "global"))
-      errors.concat(validate_boolean_setting(global_settings, "allow_remove_source", "global"))
+      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"]
 
-      # Validate borg_options booleans
-      if global_settings["borg_options"]
-        warnings.concat(validate_borg_option(global_settings["borg_options"], "allow_relocated_repo", "global"))
-        warnings.concat(validate_borg_option(global_settings["borg_options"], "allow_unencrypted_repo", "global"))
-      end
+      repo = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
+                                                 logger: @logger)
 
-      # Validate per-repository settings
-      config.repositories.each do |repo|
-        repo_name = repo["name"]
-        errors.concat(validate_boolean_setting(repo, "auto_init", repo_name))
-        errors.concat(validate_boolean_setting(repo, "auto_prune", repo_name))
-        errors.concat(validate_boolean_setting(repo, "allow_remove_source", repo_name))
+      raise BorgError, "Repository does not exist at #{repo_config["path"]}" unless repo.exists?
 
-        if repo["borg_options"]
-          warnings.concat(validate_borg_option(repo["borg_options"], "allow_relocated_repo", repo_name))
-          warnings.concat(validate_borg_option(repo["borg_options"], "allow_unencrypted_repo", repo_name))
-        end
-      end
+      # Get file metadata
+      metadata = repo.get_file_metadata(archive_name, file_path: options[:file])
 
-      # Display results
-      if errors.empty? && warnings.empty?
-        puts "✓ Configuration is valid"
-        puts "  No type errors or warnings found\n\n"
-      else
-        unless errors.empty?
-          puts "❌ ERRORS FOUND (#{errors.size}):"
-          errors.each do |error|
-            puts "  - #{error}"
-          end
-          puts ""
-        end
-
-        unless warnings.empty?
-          puts "⚠️  WARNINGS (#{warnings.size}):"
-          warnings.each do |warning|
-            puts "  - #{warning}"
-          end
-          puts ""
-        end
-
-        if errors.any?
-          puts "Configuration has errors that must be fixed.\n\n"
-          exit 1
-        else
-          puts "Configuration is valid but has warnings.\n\n"
-        end
-      end
+      # Display metadata
+      puts "\n═══════════════════════════════════════════════════════════════"
+      puts "  FILE METADATA"
+      puts "═══════════════════════════════════════════════════════════════\n\n"
+      puts "Archive: #{archive_name}"
+      puts "File: #{metadata["path"]}"
+      puts "Size: #{format_size(metadata["size"])}"
+      puts "Modified: #{metadata["mtime"]}"
+      puts "Mode: #{metadata["mode"]}"
+      puts "User: #{metadata["user"]}"
+      puts "Group: #{metadata["group"]}"
+      puts "Type: #{metadata["type"]}"
+      puts ""
 
-      @logger.info("Configuration validation completed")
+      @logger.info("Successfully retrieved metadata for #{metadata["path"]}")
     rescue Error => e
-      @logger.error("Validation failed: #{e.message}")
-      error_exit(e)
+      @logger.error("Failed to get metadata: #{e.message}")
+      raise
     end
 
     desc "check", "Check repository integrity and compatibility"
@@ -363,7 +355,8 @@ module Ruborg
       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 = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
+                                                 logger: @logger)
 
       unless repo.exists?
         puts "  ✗ Repository does not exist at #{repo_config["path"]}"
@@ -480,6 +473,21 @@ module Ruborg
       parts.empty? ? "none" : parts.join(", ")
     end
 
+    def format_size(bytes)
+      return "0 B" if bytes.nil? || bytes.zero?
+
+      units = %w[B KB MB GB TB]
+      size = bytes.to_f
+      unit_index = 0
+
+      while size >= 1024 && unit_index < units.length - 1
+        size /= 1024.0
+        unit_index += 1
+      end
+
+      format("%.2f %s", size, units[unit_index])
+    end
+
     def get_passphrase(passphrase, passbolt_id)
       return passphrase if passphrase
       return Passbolt.new(resource_id: passbolt_id, logger: @logger).get_password if passbolt_id
@@ -543,7 +551,8 @@ module Ruborg
       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 = Repository.new(repo_config["path"], passphrase: passphrase, borg_options: borg_opts, borg_path: borg_path,
+                                                 logger: @logger)
 
       # Auto-initialize if configured
       # Use strict boolean checking: only true enables, everything else disables
@@ -571,7 +580,8 @@ module Ruborg
 
       # 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)
+      backup = Backup.new(repo, config: backup_config, retention_mode: retention_mode, repo_name: repo_name,
+                                logger: @logger)
 
       archive_name = options[:name] ? sanitize_archive_name(options[:name]) : nil
       @logger.info("Creating archive#{"s" if retention_mode == "per_file"}: #{archive_name || "auto-generated"}")

data/lib/ruborg/repository.rb

@@ -41,6 +41,95 @@ module Ruborg
       execute_borg_command(cmd)
     end
 
+    def list_archive(archive_name)
+      raise BorgError, "Repository does not exist at #{@path}" unless exists?
+      raise BorgError, "Archive name cannot be empty" if archive_name.nil? || archive_name.strip.empty?
+
+      cmd = [@borg_path, "list", "#{@path}::#{archive_name}"]
+      execute_borg_command(cmd)
+    end
+
+    def get_archive_info(archive_name)
+      raise BorgError, "Repository does not exist at #{@path}" unless exists?
+      raise BorgError, "Archive name cannot be empty" if archive_name.nil? || archive_name.strip.empty?
+
+      require "json"
+      require "open3"
+
+      cmd = [@borg_path, "info", "#{@path}::#{archive_name}", "--json"]
+      env = build_borg_env
+
+      stdout, stderr, status = Open3.capture3(env, *cmd)
+      raise BorgError, "Failed to get archive info: #{stderr}" unless status.success?
+
+      JSON.parse(stdout)
+    rescue JSON::ParserError => e
+      raise BorgError, "Failed to parse archive info: #{e.message}"
+    end
+
+    def get_file_metadata(archive_name, file_path: nil)
+      raise BorgError, "Repository does not exist at #{@path}" unless exists?
+      raise BorgError, "Archive name cannot be empty" if archive_name.nil? || archive_name.strip.empty?
+
+      require "json"
+      require "open3"
+
+      # Get archive info to check if it's a per-file archive
+      archive_info = get_archive_info(archive_name)
+      comment = archive_info.dig("archives", 0, "comment")
+
+      # If it's a per-file archive (has comment with original path), get metadata for that file
+      # Otherwise, require file_path parameter
+      if comment && !comment.empty?
+        # Per-file archive - get metadata for the single file
+        get_file_metadata_from_archive(archive_name, nil)
+      else
+        # Standard archive - require file_path
+        raise BorgError, "file_path parameter required for standard archives" if file_path.nil? || file_path.empty?
+
+        get_file_metadata_from_archive(archive_name, file_path)
+      end
+    end
+
+    private
+
+    def get_file_metadata_from_archive(archive_name, file_path)
+      require "json"
+      require "open3"
+
+      cmd = [@borg_path, "list", "#{@path}::#{archive_name}", "--json-lines"]
+      env = build_borg_env
+
+      stdout, stderr, status = Open3.capture3(env, *cmd)
+      raise BorgError, "Failed to list archive contents: #{stderr}" unless status.success?
+
+      # Parse JSON lines
+      files = stdout.lines.map do |line|
+        JSON.parse(line)
+      end
+
+      # If file_path specified, find that specific file
+      if file_path
+        # Borg stores absolute paths by stripping the leading slash
+        # For example: /var/folders/foo -> var/folders/foo
+        # Try both the original path and the path with leading slash removed
+        normalized_path = file_path.start_with?("/") ? file_path[1..] : file_path
+        file_metadata = files.find { |f| f["path"] == file_path || f["path"] == normalized_path }
+        raise BorgError, "File '#{file_path}' not found in archive" unless file_metadata
+
+        file_metadata
+      else
+        # Per-file archive - return metadata for the single file (first file)
+        raise BorgError, "Archive appears to be empty" if files.empty?
+
+        files.first
+      end
+    rescue JSON::ParserError => e
+      raise BorgError, "Failed to parse file metadata: #{e.message}"
+    end
+
+    public
+
     def prune(retention_policy = {}, retention_mode: "standard")
       raise BorgError, "Repository does not exist at #{@path}" unless exists?
       raise BorgError, "No retention policy specified" if retention_policy.nil? || retention_policy.empty?

data/lib/ruborg/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruborg
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.1
 platform: ruby
 authors:
 - Michail Pantelelis
@@ -149,7 +149,6 @@ files:
 - lib/ruborg/passbolt.rb
 - lib/ruborg/repository.rb
 - lib/ruborg/version.rb
-- ruborg.gemspec
 - ruborg.yml.example
 homepage: https://github.com/mpantel/ruborg
 licenses:

data/ruborg.gemspec

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "lib/ruborg/version"
-
-Gem::Specification.new do |spec|
-  spec.name = "ruborg"
-  spec.version = Ruborg::VERSION
-  spec.authors = ["Michail Pantelelis"]
-  spec.email = ["mpantel@aegean.gr"]
-
-  spec.summary = "A friendly Ruby frontend for Borg backup"
-  spec.description = "Ruborg provides a user-friendly interface to Borg backup. " \
-                     "It reads YAML configuration files and orchestrates backup operations, " \
-                     "supporting repository creation, backup management, and Passbolt integration."
-  spec.homepage = "https://github.com/mpantel/ruborg"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.2.0"
-
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "#{spec.homepage}.git"
-  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
-  spec.metadata["rubygems_mfa_required"] = "true"
-
-  # Specify which files should be added to the gem when it is released.
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
-    end
-  end
-  spec.bindir = "exe"
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
-
-  # Dependencies
-  spec.add_dependency "psych", "~> 5.0"
-  spec.add_dependency "thor", "~> 1.3"
-
-  # Development dependencies
-  spec.add_development_dependency "bundler", "~> 2.0"
-  spec.add_development_dependency "bundler-audit", "~> 0.9"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec", "~> 3.0"
-  spec.add_development_dependency "rubocop", "~> 1.0"
-  spec.add_development_dependency "rubocop-rspec", "~> 3.0"
-end