######### JWM Kit Repair & Restore  ############################################
######### Understanding JWM Kit Restore Points   ###############################

NOTE: This document explains the technical aspects of JWM Kit Restore Points


################################################################################
######## The Straight Facts about JWM Kit's Restore Points #####################

* Created and stored in $HOME/.config/jwmkit/restore/
* Simply a tar archive with the extention .restore
* No compression. Compression would offer little benifit for the complexity
* Filename must be YYYY-MM-DD_at_HH-MM.restore.
    Example: 2020-05-31_at_05-15 for a restore created at 5:15am on May 31, 2020
* Includes all files that are part of the JWM Configuration
* Also includes the JWM Kit settings files. $HOME/.config/jwmkit/settings
* To avoid conflicts archived files are renamed with leading 3 digits and dash.
* Files are numbered using the above renaming method
* Archive must include a file called: _FILE_PATHS_.RFL (details in next section)
* Files are restored to their orginal path/filename . . . except
* Files stored outside of the user's home will be migrated to $HOME/.config/jwm/
* In case of file/path conflicts during Migration files will be renamed
* Migration of files is done on restore, not creation of the restore.
* When extracting a restore point the main jwmrc is extracted to the
  default location of the installed version of JWM.  This means
  - JWM 2.4 uses : $HOME/.config/jwm/jwmrc
  - Older version use : $HOME/.jwmrc

################################################################################
######## About _FILE_PATHS_.RFL ################################################

* All files in the archive with full path.
* Base name of files includes the 3 digits and dash (must be removed on restore)

Example _FILE_PATHS_.RFL for the files $HOME/.jwmrc, $HOME/.config/jwm/tray-top,
$HOME/.config/jwm/menu-apps, $HOME/.config/jwm/icons

$HOME/000-.jwmrc
$HOME/.config/jwm/001-tray-top
$HOME/.config/jwm/002-menu-apps
$HOME/.config/jwm/003-icons

Of course this is not a complete config and it's missing the JWM Kit settings
file so this an incomplete example.

################################################################################
######## Example of how the restore works ######################################

* Filename: 002-menu1
* Entry in _FILE_PATHS_.RFL: $HOME/.config/jwm/test/002-menu1

On restore the file 002-menu1 from the archive will be copied
to $HOME/.config/jwm/test/menu1

################################################################################
######## Example of restore with file outside of home ##########################

* Filename: 001-keys
* Entry in _FILE_PATHS_.RFL: /etc/jwm/test/001-keys

On restore the file 001-keys from the archive will be copied
to $HOME/.config/jwm/keys

All references to the file with in the Config files will be updated

################################################################################
######## Example of restore with filename conflicts ############################

* Filename: 001-keys
* Entry in _FILE_PATHS_.RFL: /etc/jwm/test/001-keys

* Filename: 002-keys
* Entry in _FILE_PATHS_.RFL: $HOME/.config/jwm/002-keys

The problem is that both files will be copied to $HOME/.config/jwm/keys
meaning the last file extracted will overwrite the first one.  In the case the
base name of the file will have -redit with a number appended. The number starts
at 0 and increased until there is no conflict. 

On restore:
The file 001-keys from the archive will be copied
to $HOME/.config/jwm/keys

The file 002-keys from the archive will be copied
to $HOME/.config/jwm/keys-redit0

If there is an addition file with the name keys in the same path it will become
$HOME/.config/jwm/keys-redit1  # note the number incremented

All references to the files in the config files will be updated

################################################################################
