path: root/README

                               ━━━━━━━━━
                                  LEO

                                Andinus
                               ━━━━━━━━━


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

1 Documentation
.. 1.1 Dispatch table
.. 1.2 Options
..... 1.2.1 encrypt/sign
..... 1.2.2 delete
..... 1.2.3 help
2 Example
3 History


Leo is my archival 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 Documentation
═══════════════

  I use this to quickly archive some of my files & copy them to another
  computer as a backup.


1.1 Dispatch table
──────────────────

  `%dispatch' has the pre-defined list. Learn the list directly from
  `leo.pl', it's self-explanatory. Or check the sub `HelpMessage', it
  explains what each command does.

  For example, `documents' will archive `$ENV{HOME}/documents' to
  `/tmp/archive/documents_$ymd.tar' where `$ymd' is current date in
  `YYYY-MM-DD' format.
  ┌────
  │ my %dispatch = (
  │     journal => sub {
  │         archive("$archive_dir/journal_$ymd.tar",
  │                 "-C", "$ENV{HOME}/documents",
  │                 "andinus.org.gpg", "archive.org.gpg");
  │     },
  │     ...
  │ );
  └────

  Currently I generate the dispatch table with a function & only special
  profiles are added manually like above. `journal' is a special profile
  because I don't want encryption on it.

  Other profiles are added by this function:
  ┌────
  │ # This adds the directories that have same path relative to $ENV{HOME}
  │ # as profile name.
  │ foreach my $profile (qw( emails music projects documents .ssh
  │                          .password-store)) {
  │     $dispatch{$profile} = sub {
  │         archive("$archive_dir/${profile}_$ymd.tar",
  │                 "-C", "$ENV{HOME}/$profile", ".");
  │     };
  │ }
  └────

  I alias paths like `.ssh' to make it convenient to type:

  ┌────
  │ # Aliases for inconvenient paths.
  │ $dispatch{ssh} = $dispatch{".ssh"};
  │ $dispatch{pass} = $dispatch{".password-store"};
  └────


1.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
  ━━━━━━━━━━━━━━━━━━━━━━


1.2.1 encrypt/sign
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

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

  *Note*: `gpg2' might compress the archives 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.


1.2.2 delete
╌╌╌╌╌╌╌╌╌╌╌╌

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


1.2.3 help
╌╌╌╌╌╌╌╌╌╌

  Running just `leo' will print help.


2 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
  └────


3 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.