Update version number and update documentation

* Support encryption with OpenSSL (#138)
* Support "include" directive in built-in template processor (#255)
* Support extensions for alternate files and templates (#257)
* Improve support for default branches (#231, #232)
* Add --version and --help as yadm internal commands (#267)
* Improve support for XDG base directory specification
* Use XDG_DATA_HOME used for encrypted data and repository (#208)
* Default repo is now ~/.local/share/yadm/repo.git
* Default encrypted archive is now ~/.local/share/yadm/archive
* Improve shell completions (#238, #274, #275)
* Remove support for YADM_COMPATIBILITY=1 (#242)
* Remove deprecated option cygwin-copy
* Fix template mode inheritance on FreeBSD (#243, #246)
* Fix hook execution under MinGW (#150)
* Improve compatibility with Oil shell (#210)

CHANGES

@@ -1,3 +1,20 @@
+3.0.0
+  * Support encryption with OpenSSL (#138)
+  * Support "include" directive in built-in template processor (#255)
+  * Support extensions for alternate files and templates (#257)
+  * Improve support for default branches (#231, #232)
+  * Add --version and --help as yadm internal commands (#267)
+  * Improve support for XDG base directory specification
+  * Use XDG_DATA_HOME used for encrypted data and repository (#208)
+  * Default repo is now ~/.local/share/yadm/repo.git
+  * Default encrypted archive is now ~/.local/share/yadm/archive
+  * Improve shell completions (#238, #274, #275)
+  * Remove support for YADM_COMPATIBILITY=1 (#242)
+  * Remove deprecated option cygwin-copy
+  * Fix template mode inheritance on FreeBSD (#243, #246)
+  * Fix hook execution under MinGW (#150)
+  * Improve compatibility with Oil shell (#210)
+
 2.5.0
   * Support for transcrypt (#197)
   * Support ESH templates (#220)
@@ -6,6 +23,7 @@
   * Fix alt processing when worktree is `/` (#198)
   * Assert config directory if missing (#226, #227)
   * Documentation improvements (#229)
+
 2.4.0
   * Support multiple keys in `yadm.gpg-recipient` (#139)
   * Ensure all templates are written atomically (#142)
@@ -15,6 +33,7 @@
   * Improve identification of WSL (#196)
   * Fix troff warnings emitted by man page (#195)
   * Write encrypt-based exclusions during decrypt
+
 2.3.0
   * Support git-crypt (#168)
   * Support specifying a command after `yadm enter`

CONTRIBUTORS

@@ -2,8 +2,10 @@ CONTRIBUTORS
 
 Tim Byrne
 Martin Zuther
+Erik Flodin
 Jan Schulz
 Jonathan Daigle
+Luis López
 Tin Lai
 Espen Henriksen
 Cameron Eagans
@@ -11,6 +13,7 @@ Klas Mellbourn
 Ross Smith II
 Tomas Cernaj
 jonasc
+Chad Wade Day, Jr
 Sébastien Gross
 David Mandelberg
 Daniel Gray
@@ -25,7 +28,10 @@ Daniel Wagenknecht
 Stig Palmquist
 Patrick Hof
 con-f-use
+Travis A. Everett
 Sheng Yang
+Adam Jimerson
+addshore
 Tim Condit
 Thomas Luzat
 Russ Allbery

README.md

@@ -56,8 +56,8 @@ The star count helps others discover yadm.
 [Git]: https://git-scm.com/
 [GnuPG]: https://gnupg.org/
 [OpenSSL]: https://www.openssl.org/
-[aur-badge]: https://img.shields.io/aur/version/yadm-git.svg
+[aur-badge]: https://img.shields.io/aur/version/yadm.svg
-[aur-link]: https://aur.archlinux.org/packages/yadm-git
+[aur-link]: https://aur.archlinux.org/packages/yadm
 [dev-pages-badge]: https://img.shields.io/github/workflow/status/TheLocehiliosan/yadm/Test%20Site/dev-pages?label=dev-pages
 [develop-badge]: https://img.shields.io/github/workflow/status/TheLocehiliosan/yadm/Tests/develop?label=develop
 [develop-commits]: https://github.com/TheLocehiliosan/yadm/commits/develop
@@ -72,7 +72,7 @@ The star count helps others discover yadm.
 [master-badge]: https://img.shields.io/github/workflow/status/TheLocehiliosan/yadm/Tests/master?label=master
 [master-commits]: https://github.com/TheLocehiliosan/yadm/commits/master
 [master-date]: https://img.shields.io/github/last-commit/TheLocehiliosan/yadm/master.svg?label=master
-[obs-badge]: https://img.shields.io/badge/OBS-v2.5.0-blue
+[obs-badge]: https://img.shields.io/badge/OBS-v3.0.0-blue
 [obs-link]: https://software.opensuse.org//download.html?project=home%3ATheLocehiliosan%3Ayadm&package=yadm
 [releases-badge]: https://img.shields.io/github/tag/TheLocehiliosan/yadm.svg?label=latest+release
 [releases-link]: https://github.com/TheLocehiliosan/yadm/releases

yadm

@@ -20,7 +20,7 @@ if [ -z "$BASH_VERSION" ]; then
   [ "$YADM_TEST" != 1 ] && exec bash "$0" "$@"
 fi
 
-VERSION=2.5.0
+VERSION=3.0.0
 
 YADM_WORK="$HOME"
 YADM_DIR=

yadm.1

@@ -1,5 +1,5 @@
 .\" vim: set spell so=8:
-.TH yadm 1 "9 August 2020" "2.5.0"
+.TH yadm 1 "30 December 2020" "3.0.0"
 
 .SH NAME
 

yadm.md

@@ -75,10 +75,11 @@
        clone url
               Clone a remote repository for tracking dotfiles.  After the con-
               tents  of  the remote repository have been fetched, a "merge" of
-              origin/master is attempted.   If  there  are  conflicting  files
+              the remote HEAD branch is attempted.  If there  are  conflicting
-              already  present  in  the  work-tree,  this  merge will fail and
+              files already present in the work-tree, this merge will fail and
-              instead a "reset" of origin/master will be done, followed  by  a
+              instead a "reset" of the remote HEAD branch will be  done,  fol-
-              "stash". This "stash" operation will preserve the original data.
+              lowed  by  a  "stash".  This "stash" operation will preserve the
+              original data.
 
               You can review the stashed conflicts by running the command
 
@@ -91,26 +92,26 @@
               or
                      yadm stash pop
 
-              The  repository  is  stored  in $HOME/.config/yadm/repo.git.  By
+              The  repository  is  stored in $HOME/.local/share/yadm/repo.git.
-              default, $HOME will be used as the work-tree, but  this  can  be
+              By default, $HOME will be used as the work-tree, but this can be
               overridden  with the -w option.  yadm can be forced to overwrite
               an existing repository by providing the -f option.  If you  want
-              to  use  a  branch  other than origin/master, you can specify it
+              to  use a branch other than the remote HEAD branch you can spec-
-              using the -b option.  By default yadm will ask the user  if  the
+              ify it using the -b option.  By default yadm will ask  the  user
-              bootstrap  program  should  be  run  (if it exists). The options
+              if  the  bootstrap  program  should  be  run (if it exists). The
-              --bootstrap or --no-bootstrap will either force the bootstrap to
+              options --bootstrap or  --no-bootstrap  will  either  force  the
-              be  run,  or  prevent  it  from being run, without prompting the
+              bootstrap  to  be  run,  or  prevent  it from being run, without
-              user.
+              prompting the user.
 
        config This command manages  configurations  for  yadm.   This  command
               works exactly the way git-config(1) does.  See the CONFIGURATION
               section for more details.
 
        decrypt
-              Decrypt all files stored in $HOME/.config/yadm/files.gpg.  Files
+              Decrypt all  files  stored  in  $HOME/.local/share/yadm/archive.
-              decrypted  will be relative to the configured work-tree (usually
+              Files  decrypted  will  be  relative to the configured work-tree
-              $HOME).  Using the -l option will list the files stored  without
+              (usually $HOME).  Using the -l option will list the files stored
-              extracting them.
+              without extracting them.
 
        encrypt
               Encrypt  all  files  matching  the patterns found in $HOME/.con-
@@ -138,9 +139,7 @@
                          (tramp-remote-shell "/bin/sh")
                          (tramp-remote-shell-args ("-c"))))
 
-              With  this  config,  use  (magit-status  "/yadm::"). If you find
+              With this config, use (magit-status "/yadm::").
-              issue with Emacs 27 and  zsh,  trying  running  (setenv  "SHELL"
-              "/bin/bash").
 
        git-crypt options
               If  git-crypt  is  installed,  this  command  allows you to pass
@@ -167,7 +166,7 @@
        help   Print a summary of yadm commands.
 
        init   Initialize  a  new, empty repository for tracking dotfiles.  The
-              repository  is  stored   in   $HOME/.config/yadm/repo.git.    By
+              repository is stored  in  $HOME/.local/share/yadm/repo.git.   By
               default,  $HOME  will  be used as the work-tree, but this can be
               overridden with the -w option.  yadm can be forced to  overwrite
               an existing repository by providing the -f option.
@@ -197,47 +196,26 @@
               https://github.com/elasticdog/transcrypt for details.
 
        upgrade
-              Version  2  of  yadm uses a different directory for storing your
+              Version  3  of yadm uses a different directory for storing data.
-              configurations.  When you start to use version 2 for  the  first
+              When you start to use version 3 for the first time, you may  see
-              time,  you  may  see warnings about moving your data to this new
+              warnings about moving your data to this new directory.  The eas-
-              directory.  The easiest way to accomplish  this  is  by  running
+              iest way to accomplish this is by running "yadm upgrade".   This
-              "yadm  upgrade".   This  command  will start by moving your yadm
+              command  will  start  by  moving your yadm repo to the new path.
-              repo to the new path.  Next it will move any configuration  data
+              Next it will move any archive data.  If the archive  is  tracked
-              to  the new path.  If the configurations are tracked within your
+              within your yadm repo, this command will "stage" the renaming of
-              yadm repo, this command will "stage" the renaming of those files
+              that file in the repo's index.  Upgrading will also  re-initial-
-              in the repo's index.  Upgrading will also re-initialize all sub-
+              ize all submodules you have added (otherwise they will be broken
-              modules you have added (otherwise they will be broken  when  the
+              when the repo moves).  After running "yadm upgrade", you  should
-              repo moves).  After running "yadm upgrade", you should run "yadm
+              run  "yadm status" to review changes which have been staged, and
-              status" to review changes which have  been  staged,  and  commit
+              commit them to your repository.
-              them to your repository.
 
-              You can read https://yadm.io/docs/upgrade_from_1 for more infor-
+              You can read https://yadm.io/docs/upgrade_from_2 for more infor-
               mation.
 
        version
               Print the version of yadm.
 
 
-## COMPATIBILITY
-       Beginning with version 2.0.0, yadm introduced a  couple  major  changes
-       which  may  require you to adjust your configurations.  See the upgrade
-       command for help making those adjustments.
-
-       First, yadm now uses the "XDG Base Directory Specification" to find its
-       configurations.  You  can  read https://yadm.io/docs/upgrade_from_1 for
-       more information.
-
-       Second, the naming conventions for alternate files have  been  changed.
-       You can read https://yadm.io/docs/alternates for more information.
-
-       If you want to retain the old functionality, you can set an environment
-       variable, YADM_COMPATIBILITY=1.  Doing so will  automatically  use  the
-       old  yadm  directory,  and process alternates the same as the pre-2.0.0
-       version. This compatibility mode is deprecated, and will be removed  in
-       future  versions.  This mode exists solely for transitioning to the new
-       paths and naming of alternates.
-
-
 ## OPTIONS
        yadm  supports a set of universal options that alter the paths it uses.
        The default paths are documented in the FILES section. Any path  speci-
@@ -252,8 +230,12 @@
        should be followed by a fully qualified path.
 
        -Y,--yadm-dir
-              Override the yadm directory.  yadm stores its data  relative  to
+              Override  the  yadm  directory.   yadm stores its configurations
-              this directory.
+              relative to this directory.
+
+       --yadm-data
+              Override the yadm data directory.  yadm stores its data relative
+              to this directory.
 
        --yadm-repo
               Override the location of the yadm repository.
@@ -287,10 +269,6 @@
               bolic links.  This might be desirable, because some systems  may
               not properly support symlinks.
 
-              NOTE:  The deprecated yadm.cygwin-copy option used by older ver-
-              sions of yadm has  been  replaced  by  yadm.alt-copy.   The  old
-              option will be removed in the next version of yadm.
-
        yadm.auto-alt
               Disable  the  automatic  linking described in the section ALTER-
               NATES. If disabled, you may still run  "yadm  alt"  manually  to
@@ -310,6 +288,12 @@
               Disable  the automatic creating of private directories described
               in the section PERMISSIONS.
 
+       yadm.cipher
+              Configure which encryption system is used by the encrypt/decrypt
+              commands.  Valid options are "gpg" and "openssl". The default is
+              "gpg".  Detailed information can be found in the section ENCRYP-
+              TION.
+
        yadm.git-program
               Specify  an  alternate  program  to  use  instead  of "git".  By
               default, the first "git" found in $PATH is used.
@@ -332,6 +316,21 @@
               ENCRYPTION section for more details.  This feature  is  disabled
               by default.
 
+       yadm.openssl-ciphername
+              Specify  which  cipher should be used by openssl.  "aes-256-cbc"
+              is used by default.
+
+       yadm.openssl-old
+              Newer versions of openssl  support  the  pbkdf2  key  derivation
+              function.  This is used by default. If this configuration is set
+              to "true", openssl operations will use options  compatible  with
+              older  versions  of openssl. If you change this option, you will
+              need to recreate your encrypted archive.
+
+       yadm.openssl-program
+              Specify an alternate program to use instead  of  "openssl".   By
+              default, the first "openssl" found in $PATH is used.
+
        yadm.ssh-perms
               Disable the permission changes to $HOME/.ssh/*.  This feature is
               enabled by default.
@@ -410,6 +409,12 @@
        default
               Valid when no other alternate is valid.
 
+       extension, e
+              A special "condition" that doesn't affect the selection process.
+              Its purpose is instead to allow the alternate file to end with a
+              certain  extension  to  e.g.  make editors highlight the content
+              properly.
+
 
        NOTE: The OS for "Windows Subsystem for Linux" is  reported  as  "WSL",
        even though uname identifies as "Linux".
@@ -550,10 +555,11 @@
 
        whatever##template with the following content
 
-         {% if yadm.user == 'harvey' %}
+         {% if yadm.user == "harvey" %}
          config={{yadm.class}}-{{yadm.os}}
          {% else %}
          config=dev-whatever
+         {% include "whatever.extra" %}
          {% endif %}
 
        would  output  a  file named whatever with the following content if the
@@ -561,9 +567,10 @@
 
          config=work-Linux
 
-       and the following otherwise:
+       and the following otherwise (if whatever.extra contains admin=false):
 
          config=dev-whatever
+         admin=false
 
        An equivalent Jinja template  named  whatever##template.j2  would  look
        like:
@@ -572,6 +579,7 @@
          config={{YADM_CLASS}}-{{YADM_OS}}
          {% else -%}
          config=dev-whatever
+         {% include 'whatever.extra' %}
          {% endif -%}
 
        An  equivalent  ESH  templated  named whatever##template.esh would look
@@ -581,6 +589,7 @@
          config=<%= $YADM_CLASS %>-<%= $YADM_OS %>
          <% else -%>
          config=dev-whatever
+         <%+ whatever.extra %>
          <% fi -%>
 
 
@@ -590,7 +599,9 @@
        into a Git repository, which often resides on a public system. yadm can
        make  it  easy  to  encrypt and decrypt a set of files so the encrypted
        version can be maintained in the Git  repository.   This  feature  will
-       only work if the gpg(1) command is available.
+       only work if a supported tool is available.  Both gpg(1) and openssl(1)
+       are supported.  gpg is used by default, but openssl can  be  configured
+       with the yadm.cypher configuration.
 
        To  use  this  feature, a list of patterns must be created and saved as
        $HOME/.config/yadm/encrypt.  This list of patterns should  be  relative
@@ -608,9 +619,9 @@
 
        The yadm encrypt command will find all files matching the patterns, and
        prompt  for  a  password.  Once  a password has confirmed, the matching
-       files will be encrypted and saved as $HOME/.config/yadm/files.gpg.  The
+       files will be encrypted and saved  as  $HOME/.local/share/yadm/archive.
-       patterns  and  files.gpg should be added to the yadm repository so they
+       The  "encrypt"  and "archive" files should be added to the yadm reposi-
-       are available across multiple systems.
+       tory so they are available across multiple systems.
 
        To decrypt these files later, or on another system run yadm decrypt and
        provide  the  correct password.  After files are decrypted, permissions
@@ -627,13 +638,17 @@
        This is to prevent accidentally committing sensitive data to the repos-
        itory.  This can be disabled using the yadm.auto-exclude configuration.
 
-       Using git-crypt
+       Using transcrypt or git-crypt
 
        A completely separate option for encrypting data is to install and  use
-       git-crypt.  Once installed, you can run git-crypt commands for the yadm
+       transcrypt  or  git-crypt.   Once installed, you can use these tools by
-       repo by running yadm git-crypt.  git-crypt enables transparent  encryp-
+       running yadm transcrypt or yadm git-crypt.  These tools enables  trans-
-       tion  and  decryption  of  files  in  a  git  repository.  You can read
+       parent  encryption and decryption of files in a git repository. See the
-       https://github.com/AGWA/git-crypt for details.
+       following web sites for more information:
+
+       - https://github.com/elasticdog/transcrypt
+
+       - https://github.com/AGWA/git-crypt
 
 
 
@@ -643,7 +658,7 @@
        automatically update the permissions of some file  paths.  The  "group"
        and "others" permissions will be removed from the following files:
 
-       - $HOME/.config/yadm/files.gpg
+       - $HOME/.local/share/yadm/archive
 
        - All files matching patterns in $HOME/.config/yadm/encrypt
 
@@ -712,13 +727,23 @@
        a fully qualified path, this directory will  be  $XDG_CONFIG_HOME/yadm.
        Otherwise it will be $HOME/.config/yadm.
 
+       Similarly, yadm's data files are relative to the "yadm data directory".
+       yadm uses the "XDG Base  Directory  Specification"  to  determine  this
+       directory.   If the environment variable $XDG_DATA_HOME is defined as a
+       fully qualified path, this directory will be $XDG_DATA_HOME/yadm.  Oth-
+       erwise it will be $HOME/.local/share/yadm.
+
        The  following  are the default paths yadm uses for its own data.  Most
        of these paths can be altered using universal options.  See the OPTIONS
        section for details.
 
        $HOME/.config/yadm
-              The yadm directory. By default, all data yadm stores is relative
+              The yadm directory. By default, all configs yadm stores is rela-
-              to this directory.
+              tive to this directory.
+
+       $HOME/.local/share/yadm
+              The yadm data directory. By default, all  data  yadm  stores  is
+              relative to this directory.
 
        $YADM_DIR/config
               Configuration file for yadm.
@@ -729,13 +754,13 @@
               plate.  Alternate files placed in this directory will be created
               relative to $HOME instead.
 
-       $YADM_DIR/repo.git
+       $YADM_DATA/repo.git
               Git repository used by yadm.
 
        $YADM_DIR/encrypt
               List of globs used for encrypt/decrypt
 
-       $YADM_DIR/files.gpg
+       $YADM_DATA/archive
               All files encrypted with yadm encrypt are stored in this file.
 
 
@@ -755,7 +780,7 @@
        echo .ssh/*.key >> $HOME/.config/yadm/encrypt
               Add a new pattern to the list of encrypted files
 
-       yadm encrypt ; yadm add ~/.config/yadm/files.gpg ; yadm commit
+       yadm encrypt ; yadm add ~/.local/share/yadm/archive ; yadm commit
               Commit a new set of encrypted files
 
 
@@ -770,7 +795,7 @@
 
 
 ## SEE ALSO
-       git(1), gpg(1)
+       git(1), gpg(1) openssl(1) transcrypt(1) git-crypt(1)
 
        https://yadm.io/
 

yadm.spec

@@ -1,7 +1,7 @@
 %{!?_pkgdocdir: %global _pkgdocdir %{_docdir}/%{name}-%{version}}
 Name: yadm
 Summary: Yet Another Dotfiles Manager
-Version: 2.5.0
+Version: 3.0.0
 Group: Development/Tools
 Release: 1%{?dist}
 URL: https://yadm.io