yobi 0.3.1 → 1.1.0

data/lib/yobi/repository/repair.rb

@@ -2,12 +2,10 @@
 
 module Yobi
   class Repository
-    # `restic repair index`: creates a new index based on the pack files
+    # +restic repair index+: creates a new index based on the pack files
     # present in this repository. Successor to the deprecated
-    # `rebuild-index` command.
-    #
-    # @param read_all_packs [Boolean] read every pack file fully instead of just headers
-    # @return [true]
+    # +rebuild-index+ command. +read_all_packs: true+ reads every pack file
+    # fully instead of just headers.
     def repair_index(read_all_packs: false)
       argv = build_argv("repair", "index") do |a|
         a.flag(:read_all_packs) if read_all_packs
@@ -16,34 +14,29 @@ module Yobi
       true
     end
 
-    # `restic repair packs`: extracts intact blobs from the given pack
-    # files, rebuilds the index to drop the damaged packs, and removes
+    # +restic repair packs+: extracts intact blobs from the given pack
+    # +ids:+, rebuilds the index to drop the damaged packs, and removes
     # them from the repository. Restic also writes a backup copy of each
-    # given pack file (named `pack-<id>`) into the calling process's
+    # given pack file (named +pack-<id>+) into the calling process's
     # current working directory before removing it. There's no flag to
     # disable this.
-    #
-    # @param ids [Array<String>, String] pack IDs
-    # @return [true]
     def repair_packs(ids:)
       argv = build_argv("repair", "packs", ids)
       run_restic(argv)
       true
     end
 
-    # `restic repair snapshots`: scans the given snapshots and generates
-    # new ones with damaged directories/file contents removed. This
-    # causes data loss for the content actually removed; prefer a fresh
-    # {Yobi::Repository#backup} where the source data is still available.
-    # Depends on a correct index. Call {#repair_index} first.
+    # +restic repair snapshots+: scans the given snapshots and generates
+    # new ones with damaged directories/file contents removed. This causes
+    # data loss for the content actually removed; prefer a fresh
+    # Yobi::Repository#backup where the source data is still available.
+    # Depends on a correct index - call #repair_index first.
     #
-    # @param snapshot_ids [Array<String>, String] snapshots to repair; all of them if empty
-    # @param dry_run [Boolean] report what would happen without doing it
-    # @param forget [Boolean] remove the original damaged snapshots after repairing
-    # @param hosts [Array<String>, String] filter by hostname(s)
-    # @param paths [Array<String>, String] filter by originally backed-up path(s)
-    # @param tags [Array<String>, String] filter by tag(s)
-    # @return [true]
+    # +snapshot_ids:+ names the snapshots to repair, or all of them if
+    # empty. +dry_run:+ reports what would happen without doing it.
+    # +forget:+ removes the original damaged snapshots after repairing.
+    # +hosts:+, +paths:+, and +tags:+ each accept a single value or an
+    # Array to filter by.
     def repair_snapshots(snapshot_ids: [], dry_run: false, forget: false, hosts: [], paths: [], tags: [])
       argv = build_argv("repair", "snapshots", snapshot_ids) do |a|
         a.flag(:dry_run) if dry_run

data/lib/yobi/repository/restore.rb

@@ -2,32 +2,28 @@
 
 module Yobi
   class Repository
-    # `restic restore`: extracts a snapshot's contents to a target directory.
+    # +restic restore+: extracts a snapshot's contents to a target directory.
     #
-    # @param snapshot_id [String] also accepts `"latest"`
-    # @param target [String] directory to restore into
-    # @param excludes [Array<String>, String] exclude files matching these glob patterns
-    # @param exclude_files [Array<String>, String] path(s) to file(s) listing exclude patterns
-    # @param exclude_xattrs [Array<String>, String] exclude extended attributes matching these pattern(s)
-    # @param hosts [Array<String>, String] only relevant when `snapshot_id:` is `"latest"`
-    # @param iexcludes [Array<String>, String] like `excludes`, case-insensitive
-    # @param iexclude_files [Array<String>, String] like `exclude_files`, case-insensitive
-    # @param iincludes [Array<String>, String] like `includes`, case-insensitive
-    # @param iinclude_files [Array<String>, String] like `include_files`, case-insensitive
-    # @param includes [Array<String>, String] only restore files matching these glob patterns
-    # @param include_files [Array<String>, String] path(s) to file(s) listing include patterns
-    # @param include_xattrs [Array<String>, String] only restore extended attributes matching these pattern(s)
-    # @param paths [Array<String>, String] only relevant when `snapshot_id:` is `"latest"`
-    # @param tags [Array<String>, String] only relevant when `snapshot_id:` is `"latest"`
-    # @param delete [Boolean] delete files in `target:` not present in the snapshot
-    # @param dry_run [Boolean] report what would happen without doing it
-    # @param overwrite [String, Symbol, nil] `"always"`, `"if-changed"`, or `"if-newer"`
-    # @param ownership_by_name [Boolean] map ownership by user/group name instead of numeric ID
-    # @param sparse [Boolean] write sparse files
-    # @param verbose [Boolean] stream a {Yobi::RestoreVerboseStatus} per file to the block
-    # @param verify [Boolean] verify restored file content against the repository
-    # @yieldparam message [Yobi::RestoreStatus, Yobi::RestoreVerboseStatus]
-    # @return [Yobi::RestoreOutcome]
+    # +snapshot_id:+ is a snapshot ID or +"latest"+. +target:+ is the
+    # directory to restore into.
+    #
+    # +excludes:+, +exclude_files:+, +exclude_xattrs:+, +includes:+,
+    # +include_files:+, +include_xattrs:+ and their +i+-prefixed
+    # (case-insensitive) variants each accept a single value or an Array.
+    #
+    # +hosts:+, +paths:+ and +tags:+ each accept a single value or an
+    # Array and are only relevant when +snapshot_id+ is +"latest"+.
+    #
+    # +delete:+ deletes files in +target+ not present in the snapshot.
+    # +dry_run:+ reports what would happen without doing it.
+    # +overwrite:+ is +"always"+, +"if-changed"+, or +"if-newer"+.
+    # +ownership_by_name:+ maps ownership by user/group name instead of
+    # numeric ID. +sparse:+ writes sparse files. +verify:+ verifies restored
+    # file content against the repository.
+    #
+    # When +verbose: true+, a Yobi::RestoreVerboseStatus is streamed to the
+    # block per file. The block also receives Yobi::RestoreStatus messages
+    # as they arrive. Returns a Yobi::RestoreOutcome.
     def restore(snapshot_id:, target:, excludes: [], exclude_files: [], exclude_xattrs: [], hosts: [],
       iexcludes: [], iexclude_files: [], iincludes: [], iinclude_files: [], includes: [], include_files: [],
       include_xattrs: [], paths: [], tags: [], delete: false, dry_run: false, overwrite: nil,
@@ -58,7 +54,7 @@ module Yobi
 
       output = Yobi::ResticOutput.new(transform: Yobi::RestoreMessageWrapper)
       # Restic's own restore summary isn't meant for the live block - only
-      # {RestoreOutcome#summary}'s post-hoc access sees it - but it shares
+      # RestoreOutcome#summary's post-hoc access sees it - but it shares
       # the same @transform (needed there since it isn't a status/verbose_status
       # message), so it has to be filtered back out here instead.
       live_block = block && proc { |message| block.call(message) if message.is_a?(RestoreStatus) || message.is_a?(RestoreVerboseStatus) }
@@ -67,16 +63,7 @@ module Yobi
     end
   end
 
-  # Classifies a raw restore message Hash by its own message_type, wrapping
-  # it in the matching typed class. Used both by {Yobi::Repository#restore}
-  # (as the {Yobi::ResticOutput} `transform:` for a live streaming run) and
-  # by {Yobi::RestoreOutcome}'s own post-hoc accessors.
-  #
-  # @private
-  module RestoreMessageWrapper
-    # @param raw [Hash]
-    # @return [Yobi::RestoreStatus, Yobi::RestoreVerboseStatus, Hash]
-    #   the raw Hash itself for a message_type this version of Yobi doesn't recognize
+  module RestoreMessageWrapper # :nodoc:
     def self.call(raw)
       case raw["message_type"]
       when "status" then RestoreStatus.new(raw)
@@ -86,23 +73,21 @@ module Yobi
     end
   end
 
-  # The outcome of one {Yobi::Repository#restore} call.
+  # The outcome of one Yobi::Repository#restore call.
   class RestoreOutcome
-    # @return [Yobi::ResticOutput]
+    # The Yobi::ResticOutput backing this outcome.
     attr_reader :output
 
-    # @private
-    def initialize(execution)
+    def initialize(execution) # :nodoc:
       @output = execution[:output]
     end
 
-    # @return [Hash] Restic's own `"summary"` fields (`"total_files"`, `"files_restored"`, ...)
+    # Restic's own +"summary"+ fields (+"total_files"+, +"files_restored"+, ...).
     def summary
       @summary ||= output.messages("summary").first || {}
     end
     alias_method :report, :summary
 
-    # @return [void]
     def pretty_print(q)
       q.object_group(self) do
         q.breakable
@@ -111,49 +96,41 @@ module Yobi
     end
   end
 
-  # One `"status"` message from a live restore run.
-  # https://restic.readthedocs.io/en/stable/075_scripting.html#restore
+  # One +"status"+ message from a live restore run. See
+  # https://restic.readthedocs.io/en/stable/075_scripting.html#restore.
   class RestoreStatus < Yobi::FancyHash
-    # @return [Float, nil]
     def percent_done
       self["percent_done"]
     end
 
-    # @return [Integer, nil]
     def total_files
       self["total_files"]
     end
 
-    # @return [Integer, nil]
     def files_restored
       self["files_restored"]
     end
 
-    # @return [Integer, nil]
     def total_bytes
       self["total_bytes"]
     end
 
-    # @return [Integer, nil]
     def bytes_restored
       self["bytes_restored"]
     end
   end
 
-  # One `"verbose_status"` message from a restore run, one per file. Only
-  # emitted when `verbose: true` is passed to {Yobi::Repository#restore}.
+  # One +"verbose_status"+ message from a restore run, one per file. Only
+  # emitted when +verbose: true+ is passed to Yobi::Repository#restore.
   class RestoreVerboseStatus < Yobi::FancyHash
-    # @return [String]
     def action
       self["action"]
     end
 
-    # @return [String]
     def item
       self["item"]
     end
 
-    # @return [Integer]
     def size
       self["size"]
     end

data/lib/yobi/repository/rewrite.rb

@@ -2,29 +2,24 @@
 
 module Yobi
   class Repository
-    # `restic rewrite`: creates new snapshots from existing ones with
+    # +restic rewrite+: creates new snapshots from existing ones with
     # exclude/include filters applied, or metadata changed. With
-    # `snapshot_ids:` and the other filters all left at their defaults,
+    # +snapshot_ids:+ and the other filters all left at their defaults,
     # rewrites every snapshot in the repository.
     #
-    # @param snapshot_ids [Array<String>, String] snapshots to rewrite; all of them if empty
-    # @param hosts [Array<String>, String] filter by hostname(s)
-    # @param tags [Array<String>, String] filter by tag(s)
-    # @param paths [Array<String>, String] filter by originally backed-up path(s)
-    # @param excludes [Array<String>, String] exclude files matching these glob patterns
-    # @param exclude_files [Array<String>, String] path(s) to file(s) listing exclude patterns
-    # @param iexcludes [Array<String>, String] like `excludes`, case-insensitive
-    # @param iexclude_files [Array<String>, String] like `exclude_files`, case-insensitive
-    # @param includes [Array<String>, String] only include files matching these glob patterns
-    # @param include_files [Array<String>, String] path(s) to file(s) listing include patterns
-    # @param iincludes [Array<String>, String] like `includes`, case-insensitive
-    # @param iinclude_files [Array<String>, String] like `include_files`, case-insensitive
-    # @param dry_run [Boolean] report what would happen without doing it
-    # @param forget [Boolean] remove the original snapshots afterward, instead of tagging the new ones `"rewrite"` and keeping both
-    # @param new_host [String, nil] change the recorded hostname
-    # @param new_time [String, nil] change the recorded timestamp
-    # @param snapshot_summary [Boolean] regenerate the snapshot summary
-    # @return [true]
+    # +snapshot_ids:+ names the snapshots to rewrite, or all of them if
+    # empty. +hosts:+, +tags:+, and +paths:+ each accept a single value or
+    # an Array to filter by.
+    #
+    # +excludes:+, +exclude_files:+, +includes:+, +include_files:+ and
+    # their +i+-prefixed (case-insensitive) variants each accept a single
+    # value or an Array.
+    #
+    # +dry_run:+ reports what would happen without doing it. +forget:+
+    # removes the original snapshots afterward, instead of tagging the new
+    # ones +"rewrite"+ and keeping both. +new_host:+ / +new_time:+ change
+    # the recorded hostname/timestamp. +snapshot_summary:+ regenerates the
+    # snapshot summary.
     def rewrite(snapshot_ids: [], hosts: [], tags: [], paths: [], excludes: [], exclude_files: [],
       iexcludes: [], iexclude_files: [], includes: [], include_files: [], iincludes: [], iinclude_files: [],
       dry_run: false, forget: false, new_host: nil, new_time: nil, snapshot_summary: false)

data/lib/yobi/repository/snapshots.rb

@@ -4,15 +4,14 @@ require "json"
 
 module Yobi
   class Repository
-    # `restic snapshots`: lists snapshots, optionally filtered.
+    # +restic snapshots+: lists snapshots, optionally filtered.
     #
-    # @param tags [Array<String>, String] filter by tag(s)
-    # @param hosts [Array<String>, String] filter by hostname(s)
-    # @param paths [Array<String>, String] filter by originally backed-up path(s)
-    # @param compact [Boolean] compact the printed listing
-    # @param group_by [String, nil] group results, e.g. `"host"`
-    # @param latest [Integer, nil] limit to the N most recent per group
-    # @return [Array<Yobi::Snapshot>]
+    # +tags:+, +hosts:+, and +paths:+ each accept a single value or an
+    # Array to filter by. +compact:+ compacts the printed listing.
+    # +group_by:+ (e.g. +"host"+) groups results. +latest:+ limits to the
+    # N most recent per group.
+    #
+    # Returns an Array of Yobi::Snapshot.
     def snapshots(tags: [], hosts: [], paths: [], compact: false, group_by: nil, latest: nil)
       argv = build_argv("snapshots") do |a|
         a.repeat_flag(:tag, tags)

data/lib/yobi/repository/stats.rb

@@ -2,21 +2,23 @@
 
 module Yobi
   class Repository
-    # @private
-    STATS_MODES = %w[restore-size files-by-contents blobs-per-file raw-data].each_with_object({}) do |value, hash|
+    STATS_MODES = %w[restore-size files-by-contents blobs-per-file raw-data].each_with_object({}) do |value, hash| # :nodoc:
       hash[value] = value
       hash[value.tr("-", "_").to_sym] = value
     end.freeze
 
-    # `restic stats`: accumulates statistics about the repository's data.
+    # +restic stats+: accumulates statistics about the repository's data.
     #
-    # @param snapshot_ids [Array<String>, String] restrict to these snapshot ID(s); the whole repository if empty
-    # @param hosts [Array<String>, String] filter by hostname(s)
-    # @param mode [String, Symbol, nil] `"restore-size"`/`:restore_size` (default), `"files-by-contents"`/`:files_by_contents`, `"blobs-per-file"`/`:blobs_per_file`, or `"raw-data"`/`:raw_data`
-    # @param paths [Array<String>, String] filter by originally backed-up path(s)
-    # @param tags [Array<String>, String] filter by tag(s)
-    # @return [Yobi::RepositoryStats]
-    # @raise [ArgumentError] if `mode:` isn't one of the values listed above
+    # +snapshot_ids:+ restricts to specific snapshot IDs, or the whole
+    # repository if empty. +hosts:+, +paths:+, and +tags:+ each accept a
+    # single value or an Array to filter by.
+    #
+    # +mode:+ is +"restore-size"+ / +:restore_size+ (default),
+    # +"files-by-contents"+ / +:files_by_contents+, +"blobs-per-file"+ /
+    # +:blobs_per_file+, or +"raw-data"+ / +:raw_data+. Anything else
+    # raises ArgumentError.
+    #
+    # Returns a Yobi::RepositoryStats.
     def stats(snapshot_ids: [], hosts: [], mode: nil, paths: [], tags: [])
       argv = build_argv("stats", snapshot_ids) do |a|
         a.repeat_flag(:host, hosts)
@@ -27,49 +29,52 @@ module Yobi
         a.repeat_flag(:tag, tags)
       end
       execution = run_restic(argv)
-      RepositoryStats.new(parse_json_output(execution))
+      # Permissive because Restic 0.19.0 prints a "[0:00] 100.00% ..."
+      # progress line before the JSON summary. Fixed in 0.19.1.
+      RepositoryStats.new(parse_json_output_permissively(execution))
     end
   end
 
-  # The result of one {Yobi::Repository#stats} call.
-  # https://restic.readthedocs.io/en/stable/075_scripting.html#stats
+  # The result of one Yobi::Repository#stats call. See
+  # https://restic.readthedocs.io/en/stable/075_scripting.html#stats.
   class RepositoryStats < Yobi::FancyHash
-    # @return [Integer] repository size in bytes
+    # Repository size in bytes.
     def total_size
       self["total_size"] || 0
     end
 
-    # @return [Integer] number of files backed up in the repository
+    # Number of files backed up in the repository.
     def total_file_count
       self["total_file_count"] || 0
     end
 
-    # @return [Integer] number of blobs in the repository
+    # Number of blobs in the repository.
     def total_blob_count
       self["total_blob_count"] || 0
     end
 
-    # @return [Integer] number of processed snapshots
+    # Number of processed snapshots.
     def snapshots_count
       self["snapshots_count"] || 0
     end
 
-    # @return [Integer] repository size in bytes if blobs were uncompressed
+    # Repository size in bytes if blobs were uncompressed.
     def total_uncompressed_size
       self["total_uncompressed_size"] || 0
     end
 
-    # @return [Float] factor by which the already compressed data has shrunk due to compression
+    # Factor by which the already compressed data has shrunk due to
+    # compression.
     def compression_ratio
       self["compression_ratio"] || 0.0
     end
 
-    # @return [Float] percentage of already compressed data
+    # Percentage of already compressed data.
     def compression_progress
       self["compression_progress"] || 0.0
     end
 
-    # @return [Float] overall space saving due to compression
+    # Overall space saving due to compression.
     def compression_space_saving
       self["compression_space_saving"] || 0.0
     end

data/lib/yobi/repository/tag.rb

@@ -2,18 +2,22 @@
 
 module Yobi
   class Repository
-    # `restic tag`: modifies tags on existing snapshots. Tags are part of
-    # a snapshot's content-addressed identity, so changing them produces a
+    # +restic tag+: modifies tags on existing snapshots. Tags are part of a
+    # snapshot's content-addressed identity, so changing them produces a
     # new snapshot ID for each affected snapshot.
     #
-    # @param snapshot_ids [Array<String>, String] snapshots to modify; all matching `hosts:`/`paths:` if empty
-    # @param add [Array<String>, String] tags to add, keeping existing ones
-    # @param remove [Array<String>, String] tags to remove
-    # @param set [Array<String>, String] replace all tags with exactly this set (exclusive with `add:`/`remove:`)
-    # @param tags [Array<String>, String] filter which snapshots to modify, by their current tags
-    # @param hosts [Array<String>, String] filter which snapshots to modify, by hostname
-    # @param paths [Array<String>, String] filter which snapshots to modify, by originally backed-up path
-    # @return [Yobi::TagOutcome]
+    # +snapshot_ids:+ names the snapshots to modify, or all matching
+    # +hosts:+/+paths:+ if empty.
+    #
+    # +add:+ appends tags, keeping existing ones. +remove:+ strips tags.
+    # +set:+ replaces all tags with exactly the given set (exclusive with
+    # +add:+/+remove:+).
+    #
+    # +tags:+, +hosts:+, and +paths:+ each accept a single value or an
+    # Array to filter which snapshots to modify (by current tags,
+    # hostname, or originally backed-up path respectively).
+    #
+    # Returns a Yobi::TagOutcome.
     def tag(snapshot_ids: [], add: [], remove: [], set: [], tags: [], hosts: [], paths: [])
       argv = build_argv("tag", snapshot_ids) do |a|
         a.repeat_flag(:add, add)
@@ -29,16 +33,7 @@ module Yobi
     end
   end
 
-  # Classifies a raw tag message Hash by its own message_type, wrapping it
-  # in the matching typed class. Used both as the {Yobi::ResticOutput}
-  # `transform:` for {Yobi::Repository#tag} and by {Yobi::TagOutcome}'s own
-  # post-hoc accessors.
-  #
-  # @private
-  module TagMessageWrapper
-    # @param raw [Hash]
-    # @return [Yobi::TagChange, Yobi::TagSummary, Hash]
-    #   the raw Hash itself for a message_type this version of Yobi doesn't recognize
+  module TagMessageWrapper # :nodoc:
     def self.call(raw)
       case raw["message_type"]
       when "changed" then TagChange.new(raw)
@@ -48,28 +43,26 @@ module Yobi
     end
   end
 
-  # The outcome of one {Yobi::Repository#tag} call.
+  # The outcome of one Yobi::Repository#tag call.
   class TagOutcome
-    # @return [Yobi::ResticOutput]
+    # The Yobi::ResticOutput backing this outcome.
     attr_reader :output
 
-    # @private
-    def initialize(execution)
+    def initialize(execution) # :nodoc:
       @output = execution[:output]
     end
 
-    # @return [Yobi::TagSummary] Restic's own `"summary"` fields (`"changed_snapshots"`)
+    # The Yobi::TagSummary of Restic's own +"summary"+ fields.
     def summary
       @summary ||= output.messages("summary").first || TagSummary.new({})
     end
     alias_method :report, :summary
 
-    # @return [Enumerable<Yobi::TagChange>] one per snapshot actually modified
+    # One Yobi::TagChange per snapshot actually modified.
     def changes
       @changes ||= output.messages("changed")
     end
 
-    # @return [void]
     def pretty_print(q)
       q.object_group(self) do
         q.breakable
@@ -78,25 +71,22 @@ module Yobi
     end
   end
 
-  # One `"changed"` message from a tag run. `old_snapshot_id` is now stale:
+  # One +"changed"+ message from a tag run. #old_snapshot_id is now stale:
   # tags are part of a snapshot's content-addressed identity, so changing
   # them produces a new snapshot ID.
   class TagChange < Yobi::FancyHash
-    # @return [String]
     def old_snapshot_id
       self["old_snapshot_id"]
     end
 
-    # @return [String]
     def new_snapshot_id
       self["new_snapshot_id"]
     end
   end
 
-  # The `"summary"` message from a tag run, the final result once the
-  # command finishes. Dispatched to {Yobi::TagOutcome#summary}.
+  # The +"summary"+ message from a tag run, the final result once the
+  # command finishes. Dispatched to Yobi::TagOutcome#summary.
   class TagSummary < Yobi::FancyHash
-    # @return [Integer]
     def changed_snapshots
       self["changed_snapshots"] || 0
     end

data/lib/yobi/repository/unlock.rb

@@ -2,10 +2,8 @@
 
 module Yobi
   class Repository
-    # `restic unlock`: removes stale locks left by other Restic processes.
-    #
-    # @param remove_all [Boolean] remove every lock, not just stale ones
-    # @return [true]
+    # +restic unlock+: removes stale locks left by other Restic processes.
+    # +remove_all: true+ removes every lock, not just stale ones.
     def unlock(remove_all: false)
       argv = build_argv("unlock") do |a|
         a.flag(:remove_all) if remove_all