backup_paradise 1.2.40

data/lib/backup_paradise/utility_scripts/backup/backup.rb

@@ -0,0 +1,1416 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === BackupParadise::Backup
+#
+# This is the main class that will be used for making a backup, usually
+# onto an external USB device, but optionally also to another (second)
+# harddisc (HDD).
+#
+# Note that this class will still store some information on the toplevel
+# namespace where we will backup to.
+#
+# For a listing of specific options have a look at the file "help.rb",
+# or do "rbackup help" from the commandline.
+#
+# Usage example:
+#
+#   BackupParadise::Backup.new(ARGV)
+#
+# =========================================================================== #
+# require 'backup_paradise/utility_scripts/backup/backup.rb'
+# BackupParadise::Backup.new(hash)
+# =========================================================================== #
+require 'backup_paradise/base/base.rb'
+
+module BackupParadise
+
+class Backup < ::BackupParadise::Base # === BackupParadise::Backup
+
+  require 'backup_paradise/utility_scripts/backup/constants.rb'
+  require 'backup_paradise/utility_scripts/backup/initialize.rb'
+  require 'backup_paradise/utility_scripts/backup/menu.rb'
+  require 'backup_paradise/utility_scripts/backup/run.rb'
+  require 'backup_paradise/toplevel_methods/config.rb'
+  require 'backup_paradise/toplevel_methods/help.rb'
+  require 'backup_paradise/toplevel_methods/mountpoint.rb'
+
+  # ========================================================================= #
+  # === reset                                                     (reset tag)
+  # ========================================================================= #
+  def reset
+    super()
+    # ======================================================================= #
+    # === @mountpoint
+    # ======================================================================= #
+    @mountpoint = nil
+    # ======================================================================= #
+    # === @internal_hash
+    # ======================================================================= #
+    @internal_hash = {}
+    # ======================================================================= #
+    # === :simplify_the_directory_layout
+    #
+    # If the following variable is set to true then this means that the
+    # target directory will be slightly simplified. There will not be
+    # any ':' characters; these will become '_' characters.
+    #
+    # This was necessary because windows NTFS seems to struggle with
+    # ':' characters. 
+    # ======================================================================= #
+    @internal_hash[:simplify_the_directory_layout] = true
+    # ======================================================================= #
+    # === :perform_backup
+    #
+    # The next variable determines whether we will perform a backup
+    # job or not. By default this will be false - it will be set
+    # to true through the menu() interface, via its else clause.
+    # ======================================================================= #
+    @internal_hash[:perform_backup] = true
+    # ======================================================================= #
+    # === :are_we_on_windows
+    #
+    # This can be used to overrule any other windows-specific checks.
+    # ======================================================================= #
+    @internal_hash[:are_we_on_windows] = nil
+    # ======================================================================= #
+    # === :date
+    # ======================================================================= #
+    @internal_hash[:date] = dd_mm_yyyy
+    # ======================================================================= #
+    # === :show_popup_notification
+    # ======================================================================= #
+    @internal_hash[:show_popup_notification] =
+      BackupParadise.show_popup_notification?
+    # ======================================================================= #
+    # === :last_backup_directory
+    # ======================================================================= #
+    @internal_hash[:last_backup_directory] = nil
+    # ======================================================================= #
+    # === :array_store_times
+    #
+    # The next Array will keep track of how long it took to backup
+    # the data.
+    # ======================================================================= #
+    @internal_hash[:array_store_times] = []
+    # ======================================================================= #
+    # === :use_this_as_timestamp
+    #
+    # The next variable will keep the timestamp as-is.
+    #
+    # This may include ':' characters, which Windows NTFS does not seem
+    # to like. Thus, since as of September 2020, a slightly simpler
+    # variant is used here.
+    # ======================================================================= #
+    determine_the_current_timestamp
+    # ======================================================================= #
+    # === :backup_these_directories
+    #
+    # Determine the directories that we wish to back up.
+    # ======================================================================= #
+    @internal_hash[:backup_these_directories] = all_important_directories?
+  end
+
+  # ========================================================================= #
+  # === start_the_gtk3_bindings
+  #
+  # To invoke this method, try:
+  #
+  #   rbackup --gui
+  #   rbackup --gtk
+  #
+  # ========================================================================= #
+  def start_the_gtk3_bindings
+    require 'backup_paradise/gui/gtk3/simple_backup_widget/simple_backup_widget.rb'
+    BackupParadise::GUI::Gtk::SimpleBackupWidget.run
+  end
+
+  # ========================================================================= #
+  # === default_tab_title
+  # ========================================================================= #
+  def default_tab_title
+    tab_title('Backup is complete!')
+  end
+
+  # ========================================================================= #
+  # === backup_which_directories?
+  # ========================================================================= #
+  def backup_which_directories?
+    @internal_hash[:backup_these_directories]
+  end
+
+  # ========================================================================= #
+  # === return_this_absolute_directory
+  # ========================================================================= #
+  def return_this_absolute_directory(i)
+    i = case i
+    # ======================================================================= #
+    # === DATA_DIRECTORY
+    # ======================================================================= #
+    when 'DATA_DIRECTORY'
+      DATA_DIRECTORY
+    # ======================================================================= #
+    # === SRC_DIRECTORY
+    # ======================================================================= #
+    when 'SRC_DIRECTORY',
+         'SOURCE_DIRECTORY'
+      SOURCE_DIRECTORY
+    # ======================================================================= #
+    # === STUDIUM_DIRECTORY
+    # ======================================================================= #
+    when 'STUDIUM_DIRECTORY'
+      STUDIUM_DIRECTORY
+    else
+      i
+    end
+    i
+  end
+
+  # ========================================================================= #
+  # === return_the_songs_directory
+  # ========================================================================= #
+  def return_the_songs_directory
+    DIRECTORY_CONTAINING_ALL_SONGS
+  end
+
+  # ========================================================================= #
+  # === show_help
+  # ========================================================================= #
+  def show_help
+    BackupParadise.show_help
+  end; alias display_help show_help # === display_help
+
+  # ========================================================================= #
+  # === simplify_the_directory_layout?
+  # ========================================================================= #
+  def simplify_the_directory_layout?
+    @internal_hash[:simplify_the_directory_layout]
+  end
+
+  # ========================================================================= #
+  # === set_commandline_arguments
+  # ========================================================================= #
+  def set_commandline_arguments(i = ARGV)
+    @commandline_arguments = i
+  end
+
+  # ========================================================================= #
+  # === commandline_arguments?
+  # ========================================================================= #
+  def commandline_arguments?
+    @commandline_arguments
+  end
+
+  # ========================================================================= #
+  # === first_argument?
+  # ========================================================================= #
+  def first_argument?
+    @commandline_arguments.first
+  end; alias first? first_argument? # === first?
+
+  # ========================================================================= #
+  # === is_target_harddisc_a_ntfs_system?
+  #
+  # This method will return a boolean - true or false.
+  #
+  # It will return true if the target harddisc is a NTFS system, and
+  # false otherwise.
+  # ========================================================================= #
+  def is_target_harddisc_a_ntfs_system?
+    return_value = false
+    _ = '/Mount'
+    if mount_target?.include? _
+      # ===================================================================== #
+      # Next, determine what is mounted.
+      # ===================================================================== #
+      these_may_be_mounted = `df -T -ah`.split(N).select {|line| line.include? _ }
+      if these_may_be_mounted and these_may_be_mounted.first and
+        these_may_be_mounted.first.include?('fuseblk') # This may mean a NTFS system.
+        return_value = true
+      end
+    end
+    return return_value
+  end
+
+  # ========================================================================= #
+  # === determine_whether_the_target_harddisc_is_a_ntfs_system
+  # ========================================================================= #
+  def determine_whether_the_target_harddisc_is_a_ntfs_system
+    if is_target_harddisc_a_ntfs_system?
+      do_use_simplified_directory
+    end
+  end
+
+  # ========================================================================= #
+  # === return_the_assumed_mountpoint_from_this_input
+  # ========================================================================= #
+  def return_the_assumed_mountpoint_from_this_input(i)
+    BackupParadise.return_the_assumed_mountpoint_from_this_input(i)
+  end
+
+  # ========================================================================= #
+  # === set_mountpoint
+  # ========================================================================= #
+  def set_mountpoint(i)
+    i = i.dup
+    if BackupParadise.is_this_a_shortcut?(i)
+      i = return_the_assumed_mountpoint_from_this_input(i)
+    end
+    i = i.dup if i.frozen?
+    i << '/' unless i.end_with? '/'
+    @mountpoint = i
+    # ======================================================================= #
+    # Sync it back to the toplevel as well:
+    # ======================================================================= #
+    determine_the_target_mountpoint(@mountpoint)
+    determine_where_to_backup_to_exactly
+  end; alias set_backup_to_this_target set_mountpoint # === set_backup_to_this_target
+       alias set_target_mountpoint     set_mountpoint # === set_target_mountpoint
+
+  # ========================================================================= #
+  # === determine_the_current_timestamp
+  # ========================================================================= #
+  def determine_the_current_timestamp
+    if @internal_hash[:simplify_the_directory_layout]
+      @internal_hash[:use_this_as_timestamp] =
+        "#{date?}-#{current_time.tr(':','_')}"
+    else
+      @internal_hash[:use_this_as_timestamp] =
+        "#{date?}-#{current_time}"
+    end
+  end
+
+  # ========================================================================= #
+  # === date?
+# ========================================================================= #
+  def date?
+    @internal_hash[:date]
+  end
+
+  # ========================================================================= #
+  # === use_this_as_timestamp?
+  # ========================================================================= #
+  def use_this_as_timestamp?
+    @internal_hash[:use_this_as_timestamp]
+  end
+
+  # ========================================================================= #
+  # === sanitize_the_commandline_arguments
+  # ========================================================================= #
+  def sanitize_the_commandline_arguments(
+      hash = commandline_arguments?
+    )
+    copy = hash.dup
+    # ======================================================================= #
+    # === :commandline_arguments
+    # ======================================================================= #
+    if hash.is_a?(Hash) and hash.has_key?(:commandline_arguments)
+      hash[:commandline_arguments].each {|entry|
+        if BackupParadise.is_this_a_shortcut?(entry)
+          copy[:backup_to_this_target] =
+            BackupParadise.return_the_assumed_mountpoint_from_this_input(entry)
+          copy[:commandline_arguments].reject! {|inner_entry|
+            inner_entry == entry
+          }
+        end
+      }
+      set_commandline_arguments(copy)
+    end
+  end
+
+  # ========================================================================= #
+  # === can_not_backup_this_directory_as_it_does_not_exist
+  # ========================================================================= #
+  def can_not_backup_this_directory_as_it_does_not_exist(i)
+    opnn; e "Can not backup the directory at #{sdir(i)}"
+    opnn; e 'as it does not exist.'
+  end
+
+  # ========================================================================= #
+  # === try_to_unmount_the_device
+  #
+  # This method can be used to automatically unmount the target device
+  # again.
+  # ========================================================================= #
+  def try_to_unmount_the_device
+    this_is_the_mounted_device = backup_to_this_directory?
+    # ======================================================================= #
+    # Change directory to another directory where we can safely
+    # umount the directory.
+    # ======================================================================= #
+    if has_superuser_abilities?
+      if BackupParadise.target_mountpoint?.include?('HDD1')
+        # =================================================================== #
+        # Unmount harddiscs quickly.
+        # =================================================================== #
+        unmount :hdd # Since as of 17.06.2008 we will unmount the harddisc as well.
+      end
+      if File.directory? '/Depot/j/'
+        cd '/Depot/j/'
+      elsif File.directory? '/tmp'
+        cd '/tmp'
+      elsif File.directory? '/home/Temp'
+        cd '/home/Temp'
+      else
+        cd '/'
+      end
+      opnn; e "Next unmounting the device at "\
+              "`#{sfancy(this_is_the_mounted_device)}`."
+      system "umount #{this_is_the_mounted_device}"
+    end
+  end
+
+  # ========================================================================= #
+  # === consider_renaming_all_old_last_backup_directories
+  #
+  # This will rename all "last_directory*" directory entries to their
+  # corresponding equivalent without the leading 'last_' string.
+  # ========================================================================= #
+  def consider_renaming_all_old_last_backup_directories
+    # ======================================================================= #
+    # First grab all possible entries, and check that these are all existing
+    # directories. If there is at the least one entry we will continue to
+    # operate on it.
+    # ======================================================================= #
+    all_possible_entries = Dir["#{mount_target?}last_backup-*"].select {|entry|
+      File.directory?(entry)
+    }
+    if all_possible_entries.size > 0
+      # ===================================================================== #
+      # Batch-rename these directories in that case:
+      # ===================================================================== #
+      all_possible_entries.each {|this_directory|
+        new_name_of_the_new_target_directory = this_directory.sub(/^last_/,'')
+        opnn; e "Now renaming `#{sdir(this_directory)}` "\
+                "to `#{sdir(new_name_of_the_new_target_directory)}`."
+        rename(this_directory, new_name_of_the_new_target_directory)
+      }
+    end
+  end
+
+  # ========================================================================= #
+  # === verbose_create_a_directory_at_this_position
+  #
+  # The first argument to this method should be the target directory,
+  # a path, that is where you wish to create that directory.
+  #
+  # The second argument to this method, which is optional, denotes the
+  # permission that is to be used.
+  # ========================================================================= #
+  def verbose_create_a_directory_at_this_position(
+      this_position, use_this_permission = 0754
+    )
+    e "Creating a directory at `#{sdir(this_position)}` next."
+    mkdir(this_position, use_this_permission)
+  end
+
+  # ========================================================================= #
+  # === show_the_logfile
+  #
+  # To invoke this method from the commandline, try:
+  #
+  #   advanced_backup --logfile?
+  #
+  # ========================================================================= #
+  def show_the_logfile
+    _ = FILE_BACKUP_LOG
+    if File.exist? _
+      opnn; e "Now reading the dataset from the file `#{sfile(_)}`:"
+      e
+      File.readlines(_).each {|line|
+        e orangered("  #{line.chomp}")
+      }
+      e
+    else
+      opnn; e no_file_exists_at(_)
+    end
+  end
+
+  # ========================================================================= #
+  # === show_popup_notification?
+  # ========================================================================= #
+  def show_popup_notification?
+    @internal_hash[:show_popup_notification]
+  end
+
+  # ========================================================================= #
+  # === do_show_popup
+  # ========================================================================= #
+  def do_show_popup
+    @internal_hash[:show_popup_notification] = true
+  end; alias show_popup do_show_popup # === show_popup
+
+  # ========================================================================= #
+  # === determine_where_to_backup_to_exactly
+  #
+  # This is automatically called whenever set_mountpoint() is called.
+  # ========================================================================= #
+  def determine_where_to_backup_to_exactly(
+      i = @mountpoint
+    )
+    backup_to_this_target = i
+    @backup_to_this_target = backup_to_this_target.dup
+    @backup_to_this_target << "/backup-#{return_current_date_and_time}/"
+    @backup_to_this_target = @backup_to_this_target.squeeze('/')
+    @backup_to_this_target.tr!(':','_') if simplify_the_directory_layout?
+    set_last_backup_directory(@backup_to_this_target)
+  end
+
+  # ========================================================================= #
+  # === mountpoint?
+  # ========================================================================= #
+  def mountpoint?
+    @mountpoint
+  end; alias mounted_at?            mountpoint? # === mounted_at?
+       alias target_base_directory? mountpoint? # === target_base_directory?
+
+  # ========================================================================= #
+  # === opnn
+  # ========================================================================= #
+  def opnn(i = NAMESPACE)
+    if i.is_a? String
+      i = { namespace: i }
+    end
+    super(i)
+  end
+
+  # ========================================================================= #
+  # === backup_the_audio_directory_then_exit
+  #
+  # Backup the audio directory, then exit the program.
+  # ========================================================================= #
+  def backup_the_audio_directory_then_exit
+    backup_the_audio_directory
+    exit_program
+  end
+
+  # ========================================================================= #
+  # === do_use_simplified_directory
+  #
+  # The old code used to be like this:
+  #
+  #   set_last_backup_directory(mount_point?+'last_backup')
+  #
+  # ========================================================================= #
+  def do_use_simplified_directory
+    @internal_hash[:simplify_the_directory_layout] = true
+    determine_the_current_timestamp # Must sync it back again.
+  end
+
+  # ========================================================================= #
+  # === create_file_keeping_track_of_when_the_last_backup_happened
+  #
+  # This method will store date-information into a file, when the last
+  # backup happened.
+  #
+  # It is normally found in a place such as:
+  #
+  #    /home/x/data/LAST_BACKUP.md
+  #
+  # Since Dec 2012, we will also append the date to the name of said file.
+  # ========================================================================= #
+  def create_file_keeping_track_of_when_the_last_backup_happened(
+      use_this_as_timestamp = use_this_as_timestamp?
+    )
+    base_target = "#{data_directory?}LAST_BACKUP"
+    target = "#{base_target}_#{date?}.md" # Append the date here.
+    e N+'Storing '+sfile(use_this_as_timestamp)+' into '+
+      sfile(target)+' to note'
+    e 'down when the last backup was performed.'
+    write_what_into(use_this_as_timestamp, target)
+    # ======================================================================= #
+    # Next, obtain an array with potential similar names. We will have
+    # to delete stray entries so as to not clutter our original home
+    # directory there.
+    # ======================================================================= #
+    array_all_last_backup_files = Dir["#{base_target}*"]
+    if array_all_last_backup_files.size > 1
+      array_all_last_backup_files = array_all_last_backup_files.sort_by {|d|
+        d.split('.').reverse
+      } # Keep it sorted.
+      e N+'We found more than one entry in '+
+        sdir(File.dirname(base_target)+'/')+', thus removing'
+      e 'the extra-entries next.'
+      array_all_last_backup_files[0..-2].each {|my_file|
+        e "Removing `#{sfile(my_file)}` next."
+        remove_file(my_file)
+      }
+    end
+  end; alias store_when_was_the_last_backup create_file_keeping_track_of_when_the_last_backup_happened # === store_when_was_the_last_backup
+
+  # ========================================================================= #
+  # === show_available_mountpoints
+  #
+  # This helper-method can show the available mountpoints, at the least
+  # on a linux system.
+  #
+  # To invoke this, try:
+  #
+  #   rbackup --mountpoints
+  #
+  # ========================================================================= #
+  def show_available_mountpoints
+    begin
+      require 'mountpoints'
+    rescue LoadError; end
+    if Mountpoints.is_any_mountpoint_available?
+      opnn; e 'The available (and mounted) USB devices are:'
+      e
+      Mountpoints[].each {|this_usb_device|
+        e "  #{sfancy(this_usb_device)}"
+      }
+      e
+    else
+      opnn; e 'No external USB devices appear to be mounted.'
+    end
+  end
+
+  # ========================================================================= #
+  # === show_available_mountpoints_then_exit
+  # ========================================================================= #
+  def show_available_mountpoints_then_exit
+    show_available_mountpoints
+    exit_program
+  end
+
+  # ========================================================================= #
+  # === report_time_difference
+  #
+  # This method will report to the user how long it took this class
+  # to backup the system, e. g. 30 minutes or something like that.
+  # ========================================================================= #
+  def report_time_difference
+    if @internal_hash[:array_store_times].size > 1
+      start_time = @internal_hash[:array_store_times][-2]
+      end_time   = @internal_hash[:array_store_times].last
+      time_difference = end_time - start_time # This will result in a Float.
+      if time_difference.respond_to? :round
+        time_difference = time_difference.round(3)
+      end
+      n_minutes = (time_difference.to_f / 60.0).round(2).to_s
+      opnn; e "#{tomato('Time required')} for this backup-operation: "\
+              "#{sfancy(time_difference.to_s)}"\
+              " seconds (#{royalblue(n_minutes)} minutes)."
+      consider_creating_a_log_file(time_difference)
+    end
+  end
+
+  # ========================================================================= #
+  # === show_welcome_message
+  # ========================================================================= #
+  def show_welcome_message
+    print_rev
+    cliner
+    e "Welcome to the #{lightcoral('BackupParadise')} #{rev}project!"
+    report_todays_date
+    cliner
+    e "Starting to backup into the target at `#{sdir(main_target?)}`."
+    cliner
+  end
+
+  # ========================================================================= #
+  # === consider_removing_all_but_one_log_file
+  # ========================================================================= #
+  def consider_removing_all_but_one_log_file
+    log_files = return_all_log_files
+    if log_files.size > 1
+      opnn; e 'More than one log file has been found. We will delete'
+      opnn; e 'all but one next.'
+      log_files.pop
+      delete_files(log_files, :be_verbose)
+    end
+  end
+
+  # ========================================================================= #
+  # === return_all_log_files
+  # ========================================================================= #
+  def return_all_log_files(
+      from_where = mounted_at?
+    )
+    Dir["#{from_where}log_last_backup_*"].select {|entry|
+      File.file? entry # We only want files.
+    }
+  end
+
+  # ========================================================================= #
+  # === popup_notification
+  #
+  # Use this method to send a graphical popup to the user. Only invoke
+  # it when we set @show_popup_notification to true.
+  # ========================================================================= #
+  def popup_notification(
+      what = :backup_complete
+    )
+    case what
+    when :backup_complete
+      esystem 'xmessage -center Backup finished!'
+    end
+  end
+
+  # ========================================================================= #
+  # === determine_the_starting_time
+  # ========================================================================= #
+  def determine_the_starting_time
+    @internal_hash[:array_store_times] << Time.now
+  end; alias determine_starting_time determine_the_starting_time # === determine_starting_time
+
+  # ========================================================================= #
+  # === determine_end_time
+  # ========================================================================= #
+  def determine_end_time
+    @internal_hash[:array_store_times] << Time.now
+  end
+
+  # ========================================================================= #
+  # === backup_the_programs_directory
+  #  
+  # This method can be used to backup the /Programs directory.
+  # ========================================================================= #
+  def backup_the_programs_directory(
+      target_directory = PROGRAMS_DIRECTORY
+    )
+    if File.directory? target_directory
+      cliner
+      e 'Now backing up the Programs/ directory from '+
+         sfancy(target_directory)+' into '+
+         sfile(main_target?+File.basename(target_directory))
+      cliner
+      report_total_size_of(target_directory)
+      if target_hdd_does_not_have_enough_space_left?
+        opnn; e "We have to skip backing up #{sdir(target_directory)}"
+        opnn; e 'as it does not have enough space left (Threshold: '+
+                 MINIMAL_FILESIZE+' bytes)' 
+      else    
+        backup_this_directory_if_it_exists(
+          target_directory, :default, :do_not_continue
+        )
+      end
+    else
+      can_not_backup_this_directory_as_it_does_not_exist(target_directory)
+    end
+  end
+
+  # ========================================================================= #
+  # === return_default_target_directory_from_this_input
+  # ========================================================================= #
+  def return_default_target_directory_from_this_input(i)
+    rds(
+      main_target?+
+      File.basename(i)+
+      '/'
+    )
+  end
+
+  # ========================================================================= #
+  # === determine_the_target_mountpoint
+  #
+  # This method will determine the target base mountpoint that
+  # is to be used.
+  # ========================================================================= # 
+  def determine_the_target_mountpoint(
+      i = '/Mount/USB1/'
+    )
+    BackupParadise.target_mountpoint = i
+  end
+
+  # ========================================================================= #
+  # === create_the_directory_containing_the_last_backup
+  # ========================================================================= #
+  def create_the_directory_containing_the_last_backup
+    target = "#{main_target?}backup-#{use_this_as_timestamp?}"
+    # ======================================================================= #
+    # Next, create the last_backup directory:
+    # ======================================================================= #
+    begin
+      mkdir(target, 0755)
+    rescue Errno::EINVAL
+      target.tr!(':','_')
+      mkdir(target, 0755)
+    end
+    @internal_hash[:last_backup_directory] = rds(target+'/')
+    opnn; e "Creating a directory at "\
+            "`#{sdir(@internal_hash[:last_backup_directory])}`."
+  end
+
+  # ========================================================================= #
+  # === create_a_symlink_pointing_to_that_directory_that_was_just_created
+  #
+  # This method will create a symlink to the last_backup/ directory.
+  #
+  # This is synonymous to the following ruby code:
+  #
+  #   File.symlink('last_backup-13.08.2018-22:12:26/','last_backup')
+  #
+  # ========================================================================= #
+  def create_a_symlink_pointing_to_that_directory_that_was_just_created
+    cd_to_the_mounted_device
+    create_a_symlink_here = "#{backup_to_this_directory?}last_backup"
+    from_this_target = File.basename(@internal_hash[:last_backup_directory])
+    from_this_target.chop! if from_this_target.end_with? '/'
+    # ========================================================================= #
+    # First, delete the old symlink if it exists. The method delete_symlink()
+    # will do that check for us.
+    # ========================================================================= #
+    delete_symlink(create_a_symlink_here)
+    # ========================================================================= #
+    # The next action can fail on e. g. vfat filesystems, with the error
+    # being Errno::EPERM. Hence we must rescue here.
+    # ========================================================================= #
+    begin
+      do_symlink(from_this_target, create_a_symlink_here)
+      if File.exist? create_a_symlink_here
+        points_towards = File.readlink(create_a_symlink_here)
+        opnn; e 'Next setting a symlink at `'+sfancy(create_a_symlink_here)+
+                '` pointing'
+        opnn; e "towards `#{sfile(points_towards)}`."
+      else
+        opnn; e no_file_exists_at(create_a_symlink_here)
+      end
+    rescue Errno::EPERM
+    end
+  end; alias create_symlink_to_last_backup_directory create_a_symlink_pointing_to_that_directory_that_was_just_created # === create_symlink_to_last_backup_directory
+
+  # ========================================================================= #
+  # === do_sync
+  #
+  # The do_sync() method, also aliased towards synchronize(), will sync
+  # the data onto USB items, by using the sync command.
+  # ========================================================================= #
+  def do_sync
+    opnn; e 'Starting to '+steelblue('sync data')+' ...'
+    system 'sync' # Be silent since May 2014.
+    opnn; e "> Syncing finished. (At: "\
+            "#{rosybrown(return_current_date_and_time.to_s)})"
+  end; alias synchronize do_sync # === synchronize
+
+  # ========================================================================= #
+  # === backup_this_directory
+  #
+  # This method will quickly backup a given directory.
+  #
+  # The second argument will be the target-directory onto which
+  # we will copy our files.
+  # ========================================================================= #
+  def backup_this_directory(
+      i,
+      copy_to_this_target_directory = nil,
+      shall_we_sync = true
+    )
+    case shall_we_sync
+    when :do_not_sync
+      shall_we_sync = false
+    end
+    case copy_to_this_target_directory
+    when nil,
+         :default
+      copy_to_this_target_directory = return_default_target_directory_from_this_input(i)
+    end
+    unless File.directory? copy_to_this_target_directory
+      mkdir(copy_to_this_target_directory)
+    end
+    cd copy_to_this_target_directory
+    opnn; e 'Now copying '+sdir(i)+
+            ' to '+sdir(copy_to_this_target_directory)+'.'
+    if File.directory?(i)
+      i << '*'
+    end
+    cpr(
+      i, copy_to_this_target_directory
+    )
+    do_sync if shall_we_sync
+  end
+
+  # ========================================================================= #
+  # === backup_the_system_directory
+  #  
+  # This method can be used to backup the "/System/Settings/" directory,
+  # as it may be found in GoboLinux.
+  # ========================================================================= #
+  def backup_the_system_directory(
+      target_directory = SYSTEM_SETTINGS_DIRECTORY
+    )
+    if File.directory? target_directory
+      cliner
+      e 'Now backing up the system-settings directory from '+
+         sfancy(target_directory)+' into '+
+         sfile(main_target?+File.basename(target_directory))
+      cliner
+      report_total_size_of(target_directory)
+      cpr(
+        target_directory, 
+        backup_to_this_target?
+      )
+    else
+      can_not_backup_this_directory_as_it_does_not_exist(target_directory)
+    end
+  end; alias backup_system_directory backup_the_system_directory # === backup_system_directory
+
+  # ========================================================================= #
+  # === backup_to_this_target?
+  # ========================================================================= #
+  def backup_to_this_target?
+    @backup_to_this_target
+  end
+
+  # ========================================================================= #
+  # === backup_the_data_directory_then_exit
+  #
+  # Backup only Data directory.
+  # ========================================================================= #
+  def backup_the_data_directory_then_exit
+    backup_data_directory
+    exit_program
+  end; alias backup_data_directory_then_exit backup_the_data_directory_then_exit # === backup_data_directory_then_exit
+
+  # ========================================================================= #
+  # === backup_the_data_directory                                  (data tag)
+  #
+  # This method will backup the DATA directory, e. g. the one that is
+  # at "/home/x/DATA/" on my home system.
+  # ========================================================================= #
+  def backup_the_data_directory(
+      target_directory = DATA_DIRECTORY
+    )
+    if File.directory? target_directory
+      mountpoint_target = main_target?+File.basename(target_directory)
+      cliner
+      e "Now backing up the DATA directory from "\
+        "#{sfancy(target_directory)} into "\
+        "#{sfile(mountpoint_target)}."
+      cliner
+      report_total_size_of(target_directory)
+      unless File.directory? mountpoint_target
+        create_directory(mountpoint_target, 0755)
+      end
+      mkdir(backup_to_this_target?+File.basename(target_directory))
+      cpr(
+        target_directory, 
+        backup_to_this_target?
+      )
+    else
+      can_not_backup_this_directory_as_it_does_not_exist(target_directory)
+    end
+  end; alias backup_only_data_directory backup_the_data_directory # === backup_only_data_directory
+       alias backup_data_directory      backup_the_data_directory # === backup_data_directory
+
+  # ========================================================================= #
+  # === ensure_trailing_backslash_for
+  # ========================================================================= #
+  def ensure_trailing_backslash_for(i)
+    i = i.dup
+    i << '/' unless i.end_with? '/'
+    return i
+  end
+
+  # ========================================================================= #
+  # === backup_the_studium_directory
+  # ========================================================================= #
+  def backup_the_studium_directory(
+      target_directory = STUDIUM_DIRECTORY
+    )
+    target_directory = ensure_trailing_backslash_for(target_directory)
+    if File.directory? target_directory
+      tab_title('Backing up the '+target_directory+' directory.')
+      cliner
+      e 'Now backing up the studium/ directory from '+
+         sfancy(target_directory)+' into '+
+         sfile(main_target?+File.basename(target_directory))
+      cliner
+      report_total_size_of(target_directory)
+      mkdir(backup_to_this_target?+File.basename(target_directory))
+      cpr(
+        target_directory, 
+        backup_to_this_target?
+      )
+    else
+      can_not_backup_this_directory_as_it_does_not_exist(target_directory)
+    end
+  end
+
+  # ========================================================================= #
+  # === backup_the_video_directory
+  # ========================================================================= #
+  def backup_the_video_directory(
+      target_directory = VIDEO_DIRECTORY
+    )
+    target_directory = ensure_trailing_backslash_for(target_directory)
+    if File.directory? target_directory
+      cliner
+      e 'Now backing up the Video directory from '+
+         sfancy(target_directory)+' into '+
+         sfile(main_target?+File.basename(target_directory))
+      cliner
+      tab_title('Backing up the directory '+target_directory+' next.')
+      report_total_size_of(target_directory)
+      set_backup_to_this_target(target_base_directory?)
+      mkdir(
+        target_base_directory?+File.basename(target_directory)
+      )
+      cpr(
+        target_directory, 
+        target_base_directory?
+      )
+      show_all_is_done_message
+      default_tab_title
+    else
+      can_not_backup_this_directory_as_it_does_not_exist(target_directory)
+    end
+  end
+
+  # ========================================================================= #
+  # === BackupParadise::Backup[]
+  # ========================================================================= #
+  def self.[](i = '')
+    new(i)
+  end
+
+  # ========================================================================= #
+  # === try_to_backup_the_autogenerated_directory
+  # ========================================================================= #
+  def try_to_backup_the_autogenerated_directory(
+      i = AUTOGENERATED_DIRECTORY
+    )
+    i = ensure_trailing_backslash_for(i)
+    if File.directory? i
+      opnn; e 'Now trying to backup the AUTOGENERATED '\
+              'directory at `'+sdir(i)+'`.'
+      new_target = @mountpoint.squeeze('/')
+      n_gigabytes = BackupParadise.size_in_gigabytes?(i).to_s
+      opnn; e 'This directory has a total of '+
+              sfancy(n_files_in?(i).to_s)+' entries '\
+              '(Total size: '+n_gigabytes+' GB).'
+      unless File.directory? new_target
+        verbose_create_a_directory_at_this_position(new_target)
+      end
+      tab_title('Backing up the AUTOGENERATED directory.')
+      cpr(i, new_target)
+    else
+      can_not_backup_this_directory_as_it_does_not_exist(i)
+    end
+  end; alias backup_autogenerated_directory     try_to_backup_the_autogenerated_directory # === backup_autogenerated_directory
+       alias backup_the_autogenerated_directory try_to_backup_the_autogenerated_directory # === backup_the_autogenerated_directory
+
+  # ========================================================================= #
+  # === backup_into_the_default_chroot_directory                 (chroot tag)
+  # ========================================================================= #
+  def backup_into_the_default_chroot_directory(
+      i = :chroot
+    )
+    e
+    e "#{rev}Setting the target to #{sdir(i)} next."
+    e
+    set_target_mountpoint(i) # Set to the above Chroot target. We could also use :chroot.
+    set_main_target(
+      "#{main_target?.dup}#{home_dir_of_user_x?.dup}"
+    )
+    # ======================================================================= #
+    # Must copy the autogenerated directory first:
+    # ======================================================================= #
+    try_to_backup_the_autogenerated_directory
+    all_important_directories?.each {|this_directory|
+      tab_title 'Now backing up the '+this_directory+' directory ...'
+      new_target = main_target?+File.basename(this_directory)
+      mkdir(new_target)
+      cpr(this_directory, main_target?)
+    }
+    all_done_message
+  end
+
+  # ========================================================================= #
+  # === backup_src_directory                                        (src tag)
+  #
+  # This method will backup the SRC/ directory, aka "/home/x/src/". It
+  # is evidently geared towards the system at my home setup.
+  #
+  # To invoke this method from the commandline, try:
+  #
+  #   rbackup --src-dir
+  #
+  # ========================================================================= #
+  def backup_the_source_directory(
+      target_directory = SOURCE_DIRECTORY
+    )
+    target_directory = ensure_trailing_backslash_for(target_directory)
+    if File.directory? target_directory
+      tab_title('Backing up the '+target_directory+' directory.')
+      cliner
+      e 'Now backing up the '+sdir('src/')+' directory from '+
+         sfancy(target_directory)+' into '+
+         sfile(main_target?+File.basename(target_directory))
+      cliner
+      report_total_size_of(target_directory)
+      mkdir(backup_to_this_target?+File.basename(target_directory))
+      cpr(
+        target_directory, 
+        backup_to_this_target?
+      )
+    else
+      can_not_backup_this_directory_as_it_does_not_exist(target_directory)
+    end
+  end
+
+  # ========================================================================= #
+  # === backup_the_books_directory                                 (data tag)
+  #
+  # This method will backup the BOOKS directory, e. g. the one that is
+  # at "/home/x/books/" on my home system.
+  # ========================================================================= #
+  def backup_the_books_directory(
+      target_directory = BOOKS_DIRECTORY
+    )
+    target_directory = ensure_trailing_backslash_for(target_directory)
+    if File.directory? target_directory
+      tab_title('Backing up the '+target_directory+' directory.')
+      cliner
+      e 'Now backing up the books/ directory from '+
+         sfancy(target_directory)+' into '+
+         sfile(main_target?+File.basename(target_directory))
+      cliner
+      report_total_size_of(target_directory)
+      unless File.directory? backup_to_this_target?+File.basename(target_directory)
+        opnn; verbose_create_a_directory_at_this_position(
+                backup_to_this_target?+File.basename(target_directory),
+                0755
+              )
+      end
+      cpr(
+        target_directory, 
+        backup_to_this_target?
+      )
+      rename_tab('.')
+    else
+      can_not_backup_this_directory_as_it_does_not_exist(target_directory)
+    end
+  end; alias backup_only_books_directory backup_the_books_directory # === backup_only_books_directory
+       alias backup_books_directory      backup_the_books_directory # === backup_books_directory
+
+  # ========================================================================= #
+  # === do_not_perform_the_regular_backup_routine
+  # ========================================================================= #
+  def do_not_perform_the_regular_backup_routine
+    @internal_hash[:perform_backup] = false
+  end
+
+  # ========================================================================= #
+  # === perform_the_regular_backup_routine?
+  # ========================================================================= #
+  def perform_the_regular_backup_routine?
+    @internal_hash[:perform_backup]
+  end
+
+  # ========================================================================= #
+  # === report_todays_date
+  # ========================================================================= #
+  def report_todays_date
+    e "Today is the #{sfancy(date?)}."
+  end
+
+  # ========================================================================= #
+  # === create_the_log_last_backup_file                             (log tag)
+  #
+  # We also have to remove all prior log files should they exist.
+  # ========================================================================= #
+  def create_the_log_last_backup_file
+    _ = return_all_log_files
+    target = main_target?+'log_last_backup_'+use_this_as_timestamp?
+    what = dd_mm_yyyy
+    opnn; e "Keeping a backup file (a log) at"
+    opnn; e "`#{sfile(target)}`."
+    write_what_into(what, target)
+    unless _.empty?
+      # ===================================================================== #
+      # Remove all old log files next.
+      # ===================================================================== #
+      remove_these_files(_)
+    end
+  end; alias create_log_file create_the_log_last_backup_file # === create_log_file
+
+  # ========================================================================= #
+  # === last_backup_directory?
+  # ========================================================================= #
+  def last_backup_directory?
+    @internal_hash[:last_backup_directory]
+  end
+
+  # ========================================================================= #
+  # === set_last_backup_directory
+  # ========================================================================= #
+  def set_last_backup_directory(i)
+    @internal_hash[:last_backup_directory] = i
+  end
+
+  # ========================================================================= #
+  # === consider_creating_a_log_file
+  #
+  # This method will create a .log file.
+  #
+  # It accepts an argument, which should be an Integer or Float, denoting,
+  # in seconds, how long it took to make a backup.
+  # ========================================================================= #
+  def consider_creating_a_log_file(
+      n_seconds
+    )
+    if File.directory? '/Depot/Temp/'
+      n_minutes = (n_seconds.to_f / 60).round(1).to_s
+      # ===================================================================== #
+      # Make the seconds a bit prettier next, via trailing '0'.
+      # ===================================================================== #
+      n_seconds = '%.3f' % n_seconds
+      what = "#{return_full_date}: Backing up the system took #{n_seconds} "\
+             "seconds (#{n_minutes} minutes).\n"
+      into = FILE_BACKUP_LOG
+      opnn; e "Storing the time it took to backup "\
+              "into the file `#{sfile(into)}`."
+      append_what_into(what, into)
+    end
+  end
+
+  # ========================================================================= #
+  # === backup_the_audio_directory                (audio tag, audio dir tag)
+  #
+  # This method can be used to backup my audio directory, which normally
+  # resides at "/home/x/songs/".
+  #
+  # Two arguments can be supplied to this method:
+  #
+  # (1) The first argument specifies which directory is used as the
+  #     input directory, where the songs that are to be copied
+  #     should reside.
+  #
+  # (2) If the second argument is true then only those audio files
+  #     that are missing will be copied.
+  #
+  # ========================================================================= #
+  def backup_the_audio_directory(
+      i                             = DIRECTORY_CONTAINING_ALL_SONGS,
+      copy_only_missing_audio_files = true
+    )
+    if File.directory? i
+      copied_n_files = 0
+      print rev
+      cliner
+      new_target = @mountpoint.squeeze('/')
+      opnn; e "Now trying to backup the Audio directory "\
+              "at `#{sdir(i)}`."
+      colourized_target = sdir("#{new_target}#{File.basename(i)}/")
+      opnn; e "The target for this will be at "\
+              "`#{colourized_target}`."
+      n_gigabytes = BackupParadise.size_in_gigabytes?(i).to_s
+      opnn; e 'This directory has a total of '+
+              sfancy(n_files_in?(i).to_s)+' entries '\
+              '(Total size: '+n_gigabytes+' GB).'
+      cliner
+      unless File.directory? "#{new_target}#{File.basename(i)}/"
+        opnn; verbose_create_a_directory_at_this_position(
+                "#{new_target}#{File.basename(i)}/"
+              )
+      end
+      tab_title('Backing up the main audio directory.')
+      # ===================================================================== #
+      # Else we will copy only the audio files that are missing. In order
+      # to do so we have to obtain all audio-files - we will simply
+      # pick all files, anyway. We will keep these entries sorted, too.
+      # ===================================================================== #
+      these_audio_files_may_be_copied = Dir[
+        rds("#{i.delete('*')}/*")
+      ].sort
+      if copy_only_missing_audio_files
+        these_audio_files_may_be_copied.each {|this_file|
+          totally_new_target =
+            "#{new_target}#{File.basename(i)}/#{File.basename(this_file)}"
+          # ================================================================= #
+          # We check whether the target-file exists. Only if it does not
+          # exist will it be copied.
+          # ================================================================= #
+          unless File.exist? totally_new_target
+            copied_n_files += 1
+            # =============================================================== #
+            # Pad the display.
+            # =============================================================== #
+            padded_file   = this_file.ljust(40)
+            padded_target = totally_new_target.ljust(40)
+            e "Copying `#{sfile(padded_file)}` to"
+            e "        `#{sfile(padded_target)}`."
+            copy_this_file(this_file, totally_new_target)
+          end
+        }
+        # =================================================================== #
+        # Ok, now, if we removed a file from /Depot/Audio, then the Audio/
+        # directory at the mounted USB device may still have such a file.
+        # So we will warn the user about this.
+        # =================================================================== #
+        target = "#{new_target}#{File.basename(i)}/" # This will be something like "/Mount/USB1/songs/"
+        unless these_audio_files_may_be_copied.size == Dir["#{target}*"].size
+          opnn; e 'It seems as if we have an unequal amount of Audio files in '
+          opnn; e 'the two directories.'
+          opnn; e 'This usually means that the original directory '+
+                  sdir(i)+' has some files'
+          opnn; e 'deleted, but the target directory at '+sdir(target)+' does not.'
+          opnn; e 'The old directory has '+simp(i.size.to_s)+' entries.'
+        end
+      else
+        cpr(i, new_target)
+      end
+      _ = "#{new_target}#{File.basename(i)}/"
+      if copied_n_files == 0
+        opnn; e "No file was copied into the directory #{sdir(_)}."
+        opnn; e 'This may indicate that the target audio-directory already'
+        opnn; e 'contains all necessary audio-files.' 
+      else
+        opnn; e "Finished backing up the directory "\
+                "#{sdir(i.delete('*'))} into "\
+                "#{sdir(_)}."
+      end
+      default_tab_title
+    else
+      can_not_backup_this_directory_as_it_does_not_exist(i)
+    end
+  end; alias try_to_backup_the_audio_directory backup_the_audio_directory # === alias try_to_backup_the_audio_directory
+       alias backup_audio_directory            backup_the_audio_directory # === backup_audio_directory
+
+  # ========================================================================= #
+  # === unmount
+  #
+  # Use this to unmount something. Right now, we unmount only the HDD.
+  # ========================================================================= #
+  def unmount(
+      what = :hdd
+    )
+    case what.to_sym
+    when :hdd
+      system "umount -l #{ENV['FIRST_HD']}"
+    end
+  end
+
+  # ========================================================================= #
+  # === show_backup_complete_message
+  #
+  # This variant will show that the backup has been complete on the
+  # commandline. Since September 2022 there is also a backup-complete
+  # message for LibuiParadise.
+  # ========================================================================= #
+  def show_backup_complete_message
+    e "#{BackupParadise.steelblue('Backup complete!')}#{rev}" # The old colour was cyan, up until 2021.
+    if TRY_TO_SHOW_BACKUP_COMPLETE_MESSAGE_VIA_LIBUI
+      try_to_show_backup_complete_message_via_libui
+    end
+  end; alias all_done                 show_backup_complete_message # === all_done
+       alias show_all_is_done_message show_backup_complete_message # === show_all_is_done_message
+       alias all_done_message         show_backup_complete_message # === all_done_message
+
+  # ========================================================================= #
+  # === try_to_show_backup_complete_message_via_libui
+  #
+  # This method will describe the libui-widget that we will use for
+  # notifying the user.
+  # ========================================================================= #
+  def try_to_show_backup_complete_message_via_libui
+    begin
+      require 'libui_paradise'
+      text = LibuiParadise.text('Backup complete!')
+      ::LibuiParadise.run_in_the_background
+      LibuiParadise.generic_window(
+        text, :create_a_quit_button
+      ) {{
+        width:  420,
+        height: 120,
+        title:  'Backup is complete now!'
+      }}
+    rescue LoadError; end
+  end
+
+  # ========================================================================= #
+  # === do_perform_the_backup_tasks                                 (all tag)
+  #
+  # This method is the main powerhouse of this class. It connects all the
+  # various steps together, one after the other.
+  # ========================================================================= #
+  def do_perform_the_backup_tasks
+    determine_the_starting_time
+    show_welcome_message
+    create_file_keeping_track_of_when_the_last_backup_happened
+    determine_whether_the_target_harddisc_is_a_ntfs_system
+    tab_title 'Backing up some data next, onto '+backup_to_this_target?.to_s+' ...'
+    cd last_backup_directory?
+    # ======================================================================= #
+    # Remove some log-files next, if necessary.
+    # ======================================================================= #
+    consider_removing_all_but_one_log_file
+    # ======================================================================= #
+    # The next method will rename entries such as:
+    #
+    #   "last_backup-13.10.2018-21:07:20/"
+    #
+    # to
+    #
+    #   "backup-13.10.2018-21:07:20/"
+    #
+    # specifically.
+    #
+    # This is necessary so that we can only have one such directory
+    # name, after we are done with this method here.
+    # ======================================================================= #
+    consider_renaming_all_old_last_backup_directories
+    # ======================================================================= #
+    # We will also create a log file, to denote when we started to
+    # do this current backup-operation.
+    # ======================================================================= #
+    create_the_log_last_backup_file
+    create_the_directory_containing_the_last_backup
+    create_a_symlink_pointing_to_that_directory_that_was_just_created
+    # ======================================================================= #
+    # === Back up the AUTOGENERATED directory
+    #
+    # We will next attempt to backup the directory at /AUTOGENERATED/.
+    # This must come before we create a new directory at the mounted
+    # USB device, simply because we may not copy anything at all,
+    # or some error may happen that causes an interrupt.
+    # ======================================================================= #
+    try_to_backup_the_autogenerated_directory
+    # ======================================================================= #
+    # === Back up the audio directory as well
+    # ======================================================================= #
+    try_to_backup_the_audio_directory
+    unless File.directory? backup_to_this_target?
+      FileUtils.mkdir_p(backup_to_this_target?)
+    end
+    # ======================================================================= #
+    # Next, iterate over the directories that we wish to backup.
+    # ======================================================================= #
+    backup_which_directories?.each {|this_directory|
+      this_directory = ensure_trailing_backslash_for(this_directory)
+      tab_title("Backing up #{this_directory}.")
+      this_directory = this_directory.dup if this_directory.frozen?
+      # ===================================================================== #
+      # Ensure that we have a trailing '/' character here.
+      # ===================================================================== #
+      this_directory << '/' unless this_directory.end_with?('/')
+      e "#{rev}Now backing up the directory #{sdir(this_directory)}"+
+        ' onto '+
+        steelblue(
+          backup_to_this_target?+
+          File.basename(this_directory)
+        )+'.'
+      cpr(this_directory, backup_to_this_target?)
+    }
+    popup_notification(:backup_complete) if show_popup_notification?
+    do_sync # Synchronize the USB devices here, before we determine the end time.
+    determine_end_time
+    report_time_difference
+    try_to_unmount_the_device
+    show_backup_complete_message
+    tab_title('Backup is complete!')
+    # or: tab_title ''
+  end; alias start_backup      do_perform_the_backup_tasks # === start_backup
+       alias backup_everything do_perform_the_backup_tasks # === backup_everything
+       alias do_backup         do_perform_the_backup_tasks # === do_backup
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  BackupParadise::Backup.new(ARGV)
+end # rbackup
+    # rbackup --help
+    # rbackup --data_only
+    # rbackup data_only