path: root/README

                               ━━━━━━━━━
                                  LEO

                                Andinus
                               ━━━━━━━━━


Table of Contents
─────────────────

1 Demo
2 Documentation
.. 2.1 Profile
.. 2.2 Options
..... 2.2.1 encrypt/sign
..... 2.2.2 delete
..... 2.2.3 help
.. 2.3 Configuration
3 Example
4 History


Leo is a simple backup program. It creates tar(1) files from a
pre-defined list. It can encrypt/sign files with gpg2(1).

• Web-site: [https://andinus.nand.sh/leo]
• Source: [https://git.tilde.institute/andinus/leo]
• Source (mirror): [https://github.com/andinus/leo]


1 Demo
══════

  It's very easy to setup `leo', I made a demo video to show this. I
  already have Perl environment setup for this.

  *Note*: It's even more easy now, you don't have to create profiles
  anymore.

  • Leo 2020-08-31: [https://asciinema.org/a/F97hVfgXDcd9g5IlST1t27ps3]

  You can also download the [cast file] directly & play it with
  `asciinema'.


[cast file] https://andinus.nand.sh/static/leo/2020-08-31_leo-demo.cast


2 Documentation
═══════════════

  I use this to quickly backup some of my files. It works on profiles,
  profiles are simple lists of files which get backed up.


2.1 Profile
───────────

  Profile is a simple hash table (`%profile') which contains the list of
  profiles. The profiles are mapped to a list of file paths relative to
  `$HOME' which are to be backed up.

  You can run `help' to see all the profiles along with the paths.

  Creating profiles is not required anymore, you can pass it
  file/directory name. Not all kinds of path can be passed. For example,
  `leo documents/test.txt' is not okay but `cd documents' & then `leo
  test.txt' is okay.


2.2 Options
───────────

  Some options can also be passed through environment variables. That
  allows for configuration in shell rc file & the user can run leo
  directly without looking at options.

  ━━━━━━━━━━━━━━━━━━━━━━━━
   encrypt  `LEO_ENCRYPT'
   sign     `LEO_SIGN'
   delete   `LEO_DELETE'
  ━━━━━━━━━━━━━━━━━━━━━━━━


2.2.1 encrypt/sign
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

  `encrypt_sign' handles `gpg2' related functions. It passes `--yes' by
  default.

  *Note*: `gpg2' might compress the backups depending on your config.
   Default is to enable compression, if you don't want this then add `-z
   0' to `@options'. `-z' specifies the compression level & 0 means no
   compression.

  *Note*: My journal is encrypted so to prevent re-encryption `encrypt'
   option is not passed to gpg2. This only affects journal profile. So
   `leo --encrypt journal pass' will still encrypt pass.


2.2.2 delete
╌╌╌╌╌╌╌╌╌╌╌╌

  Removes the tar file after running gpg2(1). This means that either
  `encrypt' or `sign' option must be passed.


2.2.3 help
╌╌╌╌╌╌╌╌╌╌

  Running just `leo' will print help.


2.3 Configuration
─────────────────

  There is an example config file under `share/config.pl', move it to
  config directory & rename to `leo.pl'.

  ┌────
  │ cp share/config.pl $HOME/.config/leo.pl # Copy the config.
  │ chmod -w $HOME/.config/leo.pl # Make it read-only.
  └────

  *Warning*: Leo will evaluate the configuration file, which means an
  attacker can use it to run malicious code.

  *Note*: They could always add malicious code to `.profile' & do harm.
  Just thought I should put the warning.

  To edit the config run `chmod +w' on it but please make it read-only
  again after editing.


3 Example
═════════

  ┌────
  │ # This will encrypt, sign & also delete the tar file for documents,
  │ # journal, pass & ssh profile.
  │ leo --encrypt --sign --delete documents journal pass ssh
  │
  │ # This will do the same. You can add these environment variables to
  │ # your shell rc & then just run ``leo documents journal ssh pass'' to
  │ # do the same.
  │ LEO_ENCRYPT=1 LEO_SIGN=1 LEO_DELETE=1 leo documents journal ssh pass
  │
  │ # Backup this specific file.
  │ cd $HOME/documents; leo --encrypt --sign andinus.org.gpg
  └────


4 History
═════════

  This was Leo's initial description:

        Leo is a program to run my personal scripts. You might not
        find them useful, these were previously shell scripts that
        I rewrote in Perl.

  I had created a sync function initially & was going to expand it. Then
  I decided to remove those sync functions because it was too complex, I
  replaced then with simple `sh' scripts.

  I added a simple `archive' function later & decided to turn Leo into
  that function. So, it's not a meta-program anymore. I was thinking of
  creating something that does all the things for me but that'll be too
  complex.

  Later on the same day I removed dispatch table & switched to using
  simple hash of lists to store backup paths mapped to profiles. And
  also changed the word "archive" to "backup" everywhere.