backup_paradise 1.3.5

data/doc/README.gen

@@ -0,0 +1,390 @@
+DEFAULT_HEADER
+
+<img src="https://i.imgur.com/Imkvsgs.png" style="margin: 1em">
+
+# The Backup Paradise project
+
+This project attempts to assist you - and me - in backing up data
+to an **external USB** device specifically.
+
+The project is mostly catering to my own use cases, so it may not
+be very useful to other ruby users. I will try to make adjustments
+so that other ruby users can use it (see the file called 
+**config.yml**), but this is an ongoing effort that may take
+some time.
+
+The project is primarily just a fancy **recursive copy** operation,
+but it will do some minor additional notifications on the commandline,
+make use of colours (if the colours gem has been installed),
+automatically create some log files and even provide ruby-gtk3
+bindings, as well as tk-bindings (although the latter ones are
+currently incomplete).
+
+So it is a **recursive copy** script with some add-ons really,
+nothing really sophisticated aside from this on top.
+
+The project has **one major goal** and a **few minor goals**.
+
+The **major goal** is **to be usable as a backup-assistant**,
+on both linux, but also on windows systems.
+
+The **minor goals** include:
+
+- **Flexibility**, to also allow us to back up only 
+individual files or individual directories. The user should
+be able to specify **what** has to be backed up.
+
+- Notify the user about the status of the backup-operation
+and prior backup-operations.
+
+- Provide some **simple GUI bindings** to use this project,
+in particular for both ruby-gtk and ruby-tk. The latter
+so that we can use this on windows.
+
+## General usage of the BackupParadise project - backing up data via ruby
+
+For the time being, I have aliased the main executable at 
+**bin/backup_paradise** onto:
+
+    backup_paradise
+
+To then use this, I can issue the following commands:
+
+    backup_paradise usb1
+    backup_paradise usb2
+    backup_paradise tousb1
+    backup_paradise tousb2
+    backup_paradise tousb3
+    backup_paradise tousb4
+
+Depending on where the **external USB device** is mounted.
+
+What does an argument, such as **usb1**, imply?
+
+This used to refer to the hardcoded path at <b>/Mount/USB1/</b>
+on my home system. **usb2** would then point at
+<b>/Mount/USB2/</b> and so forth. 
+
+These 'main aliases' can also be accessed via some shortcuts,
+such as "tousb1", without the quotes. See the examples listed
+above.
+
+I adopted this scheme after having used **GoboLinux**. Note that
+this used to be valid from **December 2018** up to **May 2021**.
+
+In **May 2021** this approach was changed. While I still use
+the above instructions, such as via **backup_paradise usb1**,
+a .yml file now decides the target directory. So, usb1,
+usb2 and so forth, are now simply aliases to whatever the
+.yml file specifies. The advantage of this approach is that
+other users can re-define the targets there - simply have
+a look at the **config.yml** file and change it if you 
+would like to. (Of course overruling this via the commandline
+still works, so you don't really need to have to modify the
+config.yml file.)
+
+Other mount points can also be used, although not with a
+convenience shortcut. Have a look at the option
+**--backup-to=/opt/** documented elsewhere in this
+file, to specify another base-directory to use.
+
+## The configuration file called config.yml
+
+The **BackupParadise project** comes with a small configuration file,
+called **config.yml**, in the **yaml/** subdirectory.
+
+This is an optional file, though - if it does not exist then the
+project will ignore this file completely and use internal
+defaults as-is. But if it is available, and it can be found by
+ruby, then it will be used as **the default configuration**.
+
+Since as of **September 2021* the **config.yml** file
+has the following **five main configuration settings**:
+
+    use_this_program_to_rename_tabs: String
+    show_popup_notification:         Boolean
+    use_system_cp:                   Boolean
+    backup_these_directories:        Array
+    local_audio_directory:           String
+
+The first three entries are not so important, but the fourth
+entry is quite important, because this Array specifies which
+directories we want to back up and thus copy. The fifth entry
+can be used to denote your local collection of audio files,
+if these are kept in a directory. I use **/home/x/songs/** for
+this.
+
+More options may be added in the future, but I will try to only
+add options that make sense, rather than overwhelm users with
+lots of configuration options.
+
+The individual aliases, such as usb1, usb2, and so forth, are
+also specified now:
+
+    usb1: /Mount/USB1/
+    usb2: /Mount/USB2/
+    usb3: /Mount/USB3/
+    usb4: /Mount/USB4/
+    usb5: /Mount/USB5/
+
+The rationale for these default to my home setup, where I
+mount devices to these directories (on Linux).
+
+## Log files
+
+The BackupParadise project will try to log as to what has happened,
+since as of **May 2018**. Several different log files may be created.
+
+If there is more than one log file stored at the target device
+then the current behaviour is to delete all but one log file.
+
+Another log file that may commonly be used is the one
+that targets the file <b>/Depot/Temp/backup.log</b>. This
+will, however had, only work if the directory **/Depot/Temp/** 
+exists, which is the case on my home system. The whole gem here
+is heavily tailored to my own needs - I can adapt it to meet
+other people's wishes if necessary, of course.
+
+The **format** of the log file going into **backup.log** is
+simply how long it took to make the backup, in seconds, and
+the exact date when that particular log file was created. This
+is equal to when the backup-operation happened, too.
+
+## Backing up individual directories
+
+If you have a directory called **FOOBAR/**, then you can back
+it up simply by issuing:
+
+    backup_paradise --FOOBAR
+    backup_paradise FOOBAR
+
+Whichever variant you prefer. Note that this requires that the
+external device has been mounted already. You can set where
+the device should reside via:
+
+    BackupParadise.set_mounted_path()
+
+Simply pass the directory that you may wish to use for backup
+purpose there.
+
+Note that **class AdvancedBackup** will assume a certain target
+device automatically, tailored to my own system. This is usually
+at **/Mount/USB1** for the first mounted USB device on my
+system.
+
+If you wish to overrule that and use another target, which you
+may most likely want to do, then you can use any of the
+following commandline flags for this:
+
+    backup_paradise --use-this-as-target-for-backup=/opt/
+    backup_paradise --use-this-as-target=/opt/
+    backup_paradise --backup-to=/opt/
+
+In this case **/opt/** would be the target that you use as **source
+directory** for the backup-operation.
+
+If you wish to backup the **/Programs/** hierarchy, should you
+keep an **AppDir layout** on your system, then this commandline
+invocation may be of help:
+
+    backup_paradise --programs-dir
+
+To backup the **/home/x/studium/** directory, the following 
+commands are possible:
+
+    backup_paradise --studium-dir
+    backup_paradise --studium-directory
+    backup_paradise --studium
+
+To backup, on my home system, the **/AUTOGENERATED/**
+directory, I do:
+
+    backup_paradise --autogenerated
+
+## Miscellaneous comments
+
+The **BackupParadise** project has been rewritten a few times already
+over the years.
+
+In the past there was an instance variable in class AdvancedBackup
+called **@last_backup_directory**, which was pointing to an absolute
+path such as **/Mount/USB1/last_backup-13.08.2018-21:11:15/**.
+
+It is no longer in use, but I keep it as a reference hint to
+myself - who knows what may be changed in the future.
+
+## Specific examples
+
+This subsection details some invocation examples in a short way.
+
+Some of these will only work on my home system for the time being,
+until I have sufficiently changed the project to allow more 
+flexibility in this regard.
+
+Backup all audio-files to **/opt/**:
+
+    backup_paradise --backup-to=/opt/ --audio-dir
+
+Backup all relevant entries into the default chroot target (on
+my home system):
+
+    backup_paradise --chroot
+
+## How do I make use of this project
+
+I make use of the **backup_paradise** project to back up relevant
+data on my home system. For example, all source-archives that
+are registered within the **RBT project** I also keep available
+locally. Then there is my ruby code, other files, and possibly
+books, papers and tutorials stored in .pdf format.
+
+In **September 2020**, the regular backup size was **54G** per
+backup-action, mostly owing to the source archives (krita
+alone occupies more than 167 MB, for example). This is way too
+much, in my opinion, because it takes about **half an hour**
+or so to back up on USB 2.0 already.
+
+I will have to keep reducing file size and removing stuff that
+I no longer need; aka do some clean-up. Or perhaps hope that 
+future USB variants will improve things here.
+
+At any rate, this subsection shows just a bit how I may use
+the project.
+
+My usual go-to alias is:
+
+    rbackup usb1
+
+to backup to the mount point /Mount/USB1.
+
+This is the command invocation I tend to use most frequently
+so.
+
+## class BackupParadise::Backup
+
+This class is the main interface for the BackupParadise project.
+
+For a list of documented options, pass in **--help**.
+
+A few examples will be mentioned here as well, in a succinct
+manner:
+
+    rbackup --pwd # backup into the current working directory
+
+## BackupParadise.simple_backup
+
+**BackupParadise.simple_backup** can be used as a simpler alternative
+to class BackupParadise::Backup. While the latter class is very
+feature-rich, sometimes you may want to use 
+**BackupParadise.simple_backup()** instead.
+
+Usage examples:
+
+    BackupParadise.simple_backup(:audio, '/Mount/HDD1/')
+    BackupParadise.simple_backup(:audio, :usb1)
+
+## Backup time (statistics)
+
+This subsection is just a remainder for me how long backing up all
+my dataset (which is a LOT) takes. These times are gathered on
+Linux.
+
+Ideally this time should be as small as possible, but evidently,
+the more time that has to be transferred, the longer it will
+take. This refers to about 100 GB or more right now. I am open
+for any suggestions to cut the time down.
+
+The measurements happen when there is a low CPU load. 
+
+    04.06.2021: 39.17 minutes
+
+## GUI components
+
+Right now the **GTK3 version** (ruby-gtk3) is the most advanced GUI
+component of this project - but it is still rather limited. The
+primary point of the gtk-widgets for the project is to demonstrate
+what **could** be done: we want to show what is possible, in
+the event that others may want to build upon these ideas.
+
+Additionally I am working on **ruby-tk** code as well, just so 
+that this project can be used on windows (addendum in August 
+2021: this has been superceded by ruby-libui, which is a LOT
+simpler to use on windows). The priority for ruby-tk is lower
+than that of the ruby-gtk3 code. (In the future, one
+day, we may try to use the same, unified code base for
+GUIs, but this is a minor, additional goal.)
+
+Yet another use case is ruby-libui, so in the long run it is
+planned to add at the least three different widget sets,
+as well as "GUIs" for the world wide web, such as via
+<b>sinatra</b>.
+
+You can try to invoke the **GUI components** from the commandline,
+possibly via any of the following flags:
+
+    backup_paradise --gui
+    backup_paradise --gtk # This variant now defaults to ruby-gtk3.
+
+Or more specifically:
+
+    backup_paradise --gtk3
+
+There used to be gtk2-bindings, but they currently (**May 2021**)
+do not work very well. In **August 2021** I abandoned the ruby-gtk2
+code completely - new GUI code will be written either in ruby-gtk3
+and/or in ruby-libui. ruby-gtk2 is still nice, but ruby-gtk3 allows
+for more flexibility, in particular in regards to **CSS**.
+
+In **September 2021** I rewrote the old ruby-gtk3 code. The current
+iteration now looks like this:
+
+<img src="https://i.imgur.com/g1dxzAb.png" style="margin-left: 2em">
+
+The code base for that class is now largely a module, which I use
+for libui-bindings too. In the long run I would like to have 
+ruby-tk and fxruby support as well as for the www (via sinatra
+and .cgi files). Stay tuned in this regard, but don't expect this
+to come too soon.
+
+## Automounting
+
+Since as of <b>March 2023</b> it is possible to automount a
+second harddisc (should it exist). This is currently only
+the case when the underlying system is a roebe-system,
+and when the default mount target /Mount/HDD, is NOT 
+mounted yet. If this is the case then automounting will
+occur, using a hardcoded command.
+
+In the future this may be improved, including automounting
+of USB-devices. This has to be revisited eventually; for
+now the code that was added has to suffice.
+
+## Using the backup_paradise gem on Windows
+
+On Linux the code I write in ruby tends to work just fine. On Windows,
+this is a bit more difficult. For instance, Windows does not know 
+symlinks in the way that Linux does. I tried this recently in July
+2023, and had awkward error messages - for instance, if you have
+a directory called <b>C++</b> or <b>Cpp</b> and then symlink to
+it via C++ or Cpp. The C++ symlink in particular led to some oddities
+on windows where I could not copy the whole directory. This was
+very confusing. Removing the symlink suddenly allowd the copy-operation.
+Windows is strange.
+
+At any rate, since symlinks are not so useful on windows, and may lead
+to errors, since as of August 2023 the backup_paradise gem will 
+remove all symlinks found in the backup-target IF a NTFS file system
+is used. Not everyone may want this behaviour by default, but for my
+use case, I found it to work better. I document this behaviour here
+in the event that other users may want to change this for their own
+use cases.
+
+## Licence
+
+Since as of **August 2021** the MIT licence is used for new releases of
+this gem. While the GPL is a fine licence in and by itself, I simply do
+not have the time or willingness to want to enforce it for such a simple
+project like **backup_paradise**. MIT is much simpler to adhere to as
+well, so there we go.
+
+ADD_CONTACT_INFORMATION

data/doc/TODO.md

@@ -0,0 +1,130 @@
+...........................................................................
+(1) → Continue with the ruby-tk bindings on windows. Make this useable
+      one day. Improve the ruby-tk bindings. And the fxruby bindings
+      too.
+...........................................................................
+(2) → (Of course overruling this via the commandline
+       still works, so you don't really need to have to modify the
+config.yml file.)
+^^^ enable this
+^^^ we need a way to overrule these dirs such as:
+   --use-these-directories=/home/x,/home/z
+  ^^^ and test it. AND document it too.
+...........................................................................
+(3) → target_hdd_does_not_have_enough_space_left?
+      ^^^ fix this. hmmm
+...........................................................................
+(4) → add some functionality to mount USB devices and umount them again
+  # ========================================================================= #
+  # === mount_device
+  #
+  # Normal usage is to call this from: 
+  #
+  #   scan_for_usb_entries
+  #
+  # ========================================================================= #
+  def mount_device(which_one = ENV['USB1'])
+    @target_device = which_one
+    e "Now mounting device #{@which_device_entry} "+
+    "to #{@target_device}", CII
+    tmp = "mount #{@which_device_entry} #{@target_device}"
+    system(tmp)
+    @date # zeigt einfach nur das aktuelle datum an
+  end
+
+  # ========================================================================= #
+  # === pre_backup_process
+  #
+  #
+  # What is this method doing?
+  #
+  # It does these things in the following order:
+  ##
+  #   (a) renames last_backup dir to backup_DAY.MONTH.YEAR
+  #   (b) Deletes log_last_backup file (which contains time of last update)
+  #   (c) Deletes already existing backup dirs before it continues.
+  #   (d) Creates directories.
+  #
+  # base_dir signifies the absolute target. 
+  # You are in /Mount/USB1 when this method is started.
+  # ========================================================================= #
+
+  # ========================================================================= #
+  # === backup_system
+  #
+  # backup_system() to backup your system. This method is the actual working 
+  # dog of this script. It accepts one main argument, a symbol, which
+  # defaults to nogtk to avoid using gtk, and which also can use tohdd
+  # to only backup to my (2nd) harddrive.
+  #
+  # The mode argument should be either one of these:
+  #   :nogtk
+  #   :tohdd
+  #   :tousb
+  #   :data_only # this also assumes :tousb
+  # ========================================================================= #
+  def backup_system(mode = :nogtk, sleep_for_this_time = 0)
+    pre_backup_process() # all processes before starting backuping
+    # Now splitting towards mode content 
+    case mode.to_sym
+    # dont use  gtk
+    when :nogtk
+      report_backup_process_to('USB device')
+      my_sys_cmd = 'cp -vr /Users/x/* .'
+      sys(my_sys_cmd)
+      synchronize
+    # Because my hdd is so slow, we nice the process
+    # on -19. Not very important.
+    when :tohdd, :festplatte, :hdd
+      report_backup_process_to('second HDD')
+      backup :audio_dir, :pkg_dir, :system_dir
+    when :data_only, :dataonly, :data, :donly, :onlydata
+      report_backup_process_to('Data only (default into USB)')
+      my_sys_cmd='nice -19 cp -vr /Users/x/DATA/* .'
+      e(my_sys_cmd)
+      sleep(sleep_for_this_time) # sleeping so that user gets a chance to view the command.
+      sys(my_sys_cmd)
+    # tousb backup
+    when :tousb, :tousb1, :tousb2, :tousb3, :tousb4
+      report_backup_process_to('USB Removable media')
+      my_sys_cmd = 'nice -19 cp -vr /Users/x/* .'
+      e(my_sys_cmd)
+      sleep(sleep_for_this_time) # sleeping so that user gets a chance to view the command.
+      pp Dir['*']
+      sys(my_sys_cmd)
+      backup :audio_dir, :pkg_dir, :system_dir
+      synchronize # must sync
+    # else. Nah, there are no "unhandled cases".
+    end
+  end
+
+  # ========================================================================= #
+  # === change_to_device_and_start_backup
+  # ========================================================================= #
+  def change_to_device_and_start_backup(which_mode = @array_arg)
+    if Dir.pwd.include? ENV['MY_MOUNT']
+      # Prepend the string 'backup_'
+      @dir_name = 'last_backup' # name for our backup dir. Normally sets to: last_backup
+      # which_mode decides what to do. default is in else
+      # The second arg to backup_system means sleep_for_n_seconds
+      case which_mode.to_s
+      when 'no-gtk','nogtk' 
+        backup_system()
+      when 'tousb3','usb3','3'
+        backup_system(:tousb3, 2)
+      when 'data_only', 'dataonly', 'data', 'donly', 'onlydata'
+        backup_system(:data_only, 2) 
+      end
+    end
+  end
+  
+_ = RBackup.new
+_.scan_for_usb_entries
+_.change_to_device_and_start_backup # also invokes backup_system
+^^^
+...........................................................................
+(5) enhance the libui interface
+     ideally we should use the same code base, but in September 2021
+     this did not work that well, so I abandoned this for now.
+     At a later point in time we have to re-evaluate this.
+...........................................................................

data/lib/backup_paradise/actions/README.md

@@ -0,0 +1,2 @@
+All activities that relate to moving, copying or deleting files
+are called "actions". They will be stored in this directory.

data/lib/backup_paradise/actions/backup.rb

@@ -0,0 +1,62 @@
+#!/usr/bin/ruby -w
+# Encoding: UTF-8
+# frozen_string_literal: true
+# =========================================================================== #
+# === BackupParadise::Actions
+# =========================================================================== #
+# require 'backup_paradise/actions/backup.rb'
+# =========================================================================== #
+module BackupParadise
+
+module Actions
+
+  require 'backup_paradise/project/project.rb'
+  require 'backup_paradise/requires/require_yaml.rb'
+  require 'backup_paradise/toplevel_methods/e.rb'
+
+  # ========================================================================= #
+  # === BackupParadise::Actions.e
+  # ========================================================================= #
+  def self.e(i = '')
+    ::BackupParadise.e(i)
+  end
+
+  # ========================================================================= #
+  # === BackupParadise::Actions.backup
+  #
+  # This method requires a Hash as input-argument. This Hash must provide
+  # some basic information, such as to which target we will backup onto.
+  # ========================================================================= #
+  def self.backup(
+      i    = ARGV,
+      hash = {
+        backup_to_this_target: :usb1
+      }
+    )
+    if block_given?
+      yielded = yield
+      if yielded.is_a? Hash
+        hash.merge!(yielded)
+      end
+    end
+    # ======================================================================= #
+    # === :commandline_arguments
+    #
+    # The key :backup_to_this_target is mandatory.
+    # ======================================================================= #
+    if i.is_a?(Array) and !i.empty?
+      hash[:commandline_arguments] = i
+    end
+    # ======================================================================= #
+    # Delegate to a specialized class next.
+    # ======================================================================= #
+    require 'backup_paradise/utility_scripts/backup/backup.rb'
+    BackupParadise::Backup.new(hash)
+  end
+
+end; end
+
+if __FILE__ == $PROGRAM_NAME
+  BackupParadise::Actions.backup(ARGV)
+end # actionbackup
+    # actionbackup --help