b4fd9e19c2
Update version number and update documentation * Support git-crypt (#168) * Support specifying a command after `yadm enter` * Expose GIT_WORK_TREE during `yadm enter` (#160) * Support GNUPGHOME environment variable (#134) * Assert private dirs, only when worktree = $HOME (#171)
936 lines
26 KiB
Groff
936 lines
26 KiB
Groff
." vim: set spell so=8:
|
|
.TH yadm 1 "17 December 2019" "2.3.0"
|
|
|
|
.SH NAME
|
|
|
|
yadm \- Yet Another Dotfiles Manager
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.B yadm
|
|
.I command
|
|
.RI [ options ]
|
|
|
|
.B yadm
|
|
.I git-command-or-alias
|
|
.RI [ options ]
|
|
|
|
.B yadm
|
|
init
|
|
.RB [ -f ]
|
|
.RB [ -w
|
|
.IR dir ]
|
|
|
|
.B yadm
|
|
.RI clone " url
|
|
.RB [ -f ]
|
|
.RB [ -w
|
|
.IR dir ]
|
|
.RB [ -b
|
|
.IR branch ]
|
|
.RB [ --bootstrap ]
|
|
.RB [ --no-bootstrap ]
|
|
|
|
.B yadm
|
|
.RI config " name
|
|
.RI [ value ]
|
|
|
|
.B yadm
|
|
config
|
|
.RB [ -e ]
|
|
|
|
.B yadm
|
|
list
|
|
.RB [ -a ]
|
|
|
|
.BR yadm " bootstrap
|
|
|
|
.BR yadm " encrypt
|
|
|
|
.BR yadm " decrypt
|
|
.RB [ -l ]
|
|
|
|
.BR yadm " alt
|
|
|
|
.BR yadm " perms
|
|
|
|
.BR yadm " enter [ command ]
|
|
|
|
.BR yadm " git-crypt [ options ]
|
|
|
|
.BR yadm " upgrade
|
|
|
|
.BR yadm " introspect
|
|
.I category
|
|
|
|
.SH DESCRIPTION
|
|
|
|
yadm is a tool for managing a collection of files across multiple computers,
|
|
using a shared Git repository.
|
|
In addition, yadm provides a feature to select alternate versions of files for
|
|
particular systems.
|
|
Lastly, yadm supplies the ability to manage a subset of secure files, which are
|
|
encrypted before they are included in the repository.
|
|
|
|
.SH COMMANDS
|
|
|
|
.TP
|
|
.IR git-command " or " git-alias
|
|
Any command not internally handled by yadm is passed through to
|
|
.BR git (1).
|
|
Git commands or aliases are invoked with the yadm managed repository.
|
|
The working directory for Git commands will be the configured
|
|
.IR work-tree " (usually
|
|
.IR $HOME ).
|
|
|
|
Dotfiles are managed by using standard
|
|
.B git
|
|
commands;
|
|
.IR add ,
|
|
.IR commit ,
|
|
.IR push ,
|
|
.IR pull ,
|
|
etc.
|
|
|
|
.RI The " config
|
|
command is not passed directly through.
|
|
Instead use the
|
|
.I gitconfig
|
|
command (see below).
|
|
.TP
|
|
.B alt
|
|
Create symbolic links and process templates for any managed files matching the
|
|
naming rules described in the ALTERNATES and TEMPLATES sections. It is usually
|
|
unnecessary to run this command, as yadm automatically processes alternates by
|
|
default. This automatic behavior can be disabled by setting the configuration
|
|
.I yadm.auto-alt
|
|
to "false".
|
|
.TP
|
|
.B bootstrap
|
|
Execute
|
|
.I $HOME/.config/yadm/bootstrap
|
|
if it exists.
|
|
.TP
|
|
.BI clone " url
|
|
Clone a remote repository for tracking dotfiles.
|
|
After the contents of the remote repository have been fetched, a "merge" of
|
|
.I origin/master
|
|
is attempted.
|
|
If there are conflicting files already present in the
|
|
.IR work-tree ,
|
|
this merge will fail and instead a "reset" of
|
|
.I origin/master
|
|
will be done, followed by a "stash". This "stash" operation will preserve the
|
|
original data.
|
|
|
|
You can review the stashed conflicts by running the command
|
|
|
|
.RS
|
|
.RS
|
|
yadm stash show -p
|
|
.RE
|
|
|
|
from within your
|
|
.I $HOME
|
|
directory. If you want to restore the stashed data, you can run
|
|
|
|
.RS
|
|
yadm stash apply
|
|
.RE
|
|
or
|
|
.RS
|
|
yadm stash pop
|
|
.RE
|
|
|
|
The repository is stored in
|
|
.IR $HOME/.config/yadm/repo.git .
|
|
By default,
|
|
.I $HOME
|
|
will be used as the
|
|
.IR work-tree ,
|
|
but this can be overridden with the
|
|
.BR -w " option.
|
|
yadm can be forced to overwrite an existing repository by providing the
|
|
.BR -f " option.
|
|
If you want to use a branch other than
|
|
.IR origin/master ,
|
|
you can specify it using the
|
|
.BR -b " option.
|
|
By default yadm will ask the user if the bootstrap program should be run (if it
|
|
exists). The options
|
|
.BR --bootstrap " or " --no-bootstrap
|
|
will either force the bootstrap to be run, or prevent it from being run,
|
|
without prompting the user.
|
|
.RE
|
|
.TP
|
|
.B config
|
|
This command manages configurations for yadm.
|
|
This command works exactly they way
|
|
.BR git-config (1)
|
|
does.
|
|
See the CONFIGURATION section for more details.
|
|
.TP
|
|
.B decrypt
|
|
Decrypt all files stored in
|
|
.IR $HOME/.config/yadm/files.gpg .
|
|
Files decrypted will be relative to the configured
|
|
.IR work-tree " (usually
|
|
.IR $HOME ).
|
|
Using the
|
|
.B -l
|
|
option will list the files stored without extracting them.
|
|
.TP
|
|
.B encrypt
|
|
Encrypt all files matching the patterns found in
|
|
.IR $HOME/.config/yadm/encrypt .
|
|
See the ENCRYPTION section for more details.
|
|
.TP
|
|
.B enter
|
|
Run a sub-shell with all Git variables set. Exit the sub-shell the same way you
|
|
leave your normal shell (usually with the "exit" command). This sub-shell can
|
|
be used to easily interact with your yadm repository using "git" commands. This
|
|
could be useful if you are using a tool which uses Git directly, such as tig,
|
|
vim-fugitive, git-cola, etc.
|
|
|
|
Optionally, you can provide a command after "enter", and instead of invoking
|
|
your shell, that command will be run with all of the Git variables exposed to
|
|
the command's environment.
|
|
|
|
Emacs Tramp and Magit can manage files by using this configuration:
|
|
|
|
.RS
|
|
(add-to-list 'tramp-methods
|
|
'("yadm"
|
|
(tramp-login-program "yadm")
|
|
(tramp-login-args (("enter")))
|
|
(tramp-login-env (("SHELL") ("/bin/sh")))
|
|
(tramp-remote-shell "/bin/sh")
|
|
(tramp-remote-shell-args ("-c"))))
|
|
.RE
|
|
|
|
.RS
|
|
With this config, use (magit-status "/yadm::"). If you find issue with Emacs 27 and zsh,
|
|
trying running (setenv "SHELL" "/bin/bash").
|
|
.RE
|
|
.TP
|
|
.BI git-crypt " options
|
|
If git-crypt is installed, this command allows you to pass options directly to
|
|
git-crypt, with the environment configured to use the yadm repository.
|
|
|
|
git-crypt enables transparent encryption and decryption of files in a git repository.
|
|
You can read
|
|
https://github.com/AGWA/git-crypt
|
|
for details.
|
|
.TP
|
|
.B gitconfig
|
|
Pass options to the
|
|
.B git config
|
|
command. Since yadm already uses the
|
|
.I config
|
|
command to manage its own configurations,
|
|
this command is provided as a way to change configurations of the repository
|
|
managed by yadm.
|
|
One useful case might be to configure the repository so untracked files are
|
|
shown in status commands. yadm initially configures its repository so that
|
|
untracked files are not shown.
|
|
If you wish use the default Git behavior (to show untracked files and
|
|
directories), you can remove this configuration.
|
|
|
|
.RS
|
|
.RS
|
|
yadm gitconfig --unset status.showUntrackedFiles
|
|
.RE
|
|
.RE
|
|
.TP
|
|
.B help
|
|
Print a summary of yadm commands.
|
|
.TP
|
|
.B init
|
|
Initialize a new, empty repository for tracking dotfiles.
|
|
The repository is stored in
|
|
.IR $HOME/.config/yadm/repo.git .
|
|
By default,
|
|
.I $HOME
|
|
will be used as the
|
|
.IR work-tree ,
|
|
but this can be overridden with the
|
|
.BR -w " option.
|
|
yadm can be forced to overwrite an existing repository by providing the
|
|
.BR -f " option.
|
|
.TP
|
|
.B list
|
|
Print a list of files managed by yadm.
|
|
.RB The " -a
|
|
option will cause all managed files to be listed.
|
|
Otherwise, the list will only include files from the current directory or below.
|
|
.TP
|
|
.BI introspect " category
|
|
Report internal yadm data. Supported categories are
|
|
.IR commands ,
|
|
.IR configs ,
|
|
.IR repo,
|
|
and
|
|
.IR switches .
|
|
The purpose of introspection is to support command line completion.
|
|
.TP
|
|
.B perms
|
|
Update permissions as described in the PERMISSIONS section.
|
|
It is usually unnecessary to run this command, as yadm automatically processes
|
|
permissions by default. This automatic behavior can be disabled by setting the
|
|
configuration
|
|
.I yadm.auto-perms
|
|
to "false".
|
|
.TP
|
|
.B upgrade
|
|
Version 2 of yadm uses a different directory for storing your configurations.
|
|
When you start to use version 2 for the first time, you may see warnings about
|
|
moving your data to this new directory.
|
|
The easiest way to accomplish this is by running "yadm upgrade".
|
|
This command will start by moving your yadm repo to the new path.
|
|
Next it will move any configuration data to the new path.
|
|
If the configurations are tracked within your yadm repo, this command will
|
|
"stage" the renaming of those files in the repo's index.
|
|
Upgrading will also re-initialize all submodules you have added (otherwise they
|
|
will be broken when the repo moves).
|
|
After running "yadm upgrade", you should run "yadm status" to review changes
|
|
which have been staged, and commit them to your repository.
|
|
|
|
You can read
|
|
https://yadm.io/docs/upgrade_from_1
|
|
for more information.
|
|
.TP
|
|
.B version
|
|
Print the version of yadm.
|
|
|
|
.SH COMPATIBILITY
|
|
|
|
Beginning with version 2.0.0, yadm introduced a couple major changes which may
|
|
require you to adjust your configurations.
|
|
See the
|
|
.B 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,
|
|
.IR 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.
|
|
|
|
.SH 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 specified by these
|
|
options must be fully qualified. If you always want to override one or more of
|
|
these paths, it may be useful to create an alias for the yadm command.
|
|
For example, the following alias could be used to override the repository
|
|
directory.
|
|
|
|
.RS
|
|
alias yadm='yadm --yadm-repo /alternate/path/to/repo'
|
|
.RE
|
|
|
|
The following is the full list of universal options.
|
|
Each option should be followed by a fully qualified path.
|
|
.TP
|
|
.B -Y,--yadm-dir
|
|
Override the yadm directory.
|
|
yadm stores its data relative to this directory.
|
|
.TP
|
|
.B --yadm-repo
|
|
Override the location of the yadm repository.
|
|
.TP
|
|
.B --yadm-config
|
|
Override the location of the yadm configuration file.
|
|
.TP
|
|
.B --yadm-encrypt
|
|
Override the location of the yadm encryption configuration.
|
|
.TP
|
|
.B --yadm-archive
|
|
Override the location of the yadm encrypted files archive.
|
|
.TP
|
|
.B --yadm-bootstrap
|
|
Override the location of the yadm bootstrap program.
|
|
|
|
.SH CONFIGURATION
|
|
|
|
yadm uses a configuration file named
|
|
.IR $HOME/.config/yadm/config .
|
|
This file uses the same format as
|
|
.BR git-config (1).
|
|
Also, you can control the contents of the configuration file
|
|
via the
|
|
.B yadm config
|
|
command (which works exactly like
|
|
.BR git-config ).
|
|
For example, to disable alternates you can run the command:
|
|
|
|
.RS
|
|
yadm config yadm.auto-alt false
|
|
.RE
|
|
|
|
The following is the full list of supported configurations:
|
|
.TP
|
|
.B yadm.alt-copy
|
|
If set to "true", alternate files will be copies instead of symbolic links.
|
|
This might be desirable, because some systems may not properly support
|
|
symlinks.
|
|
|
|
NOTE: The deprecated
|
|
.I yadm.cygwin-copy
|
|
option used by older versions of yadm has been replaced by
|
|
.IR yadm.alt-copy .
|
|
The old option will be removed in the next version of yadm.
|
|
.TP
|
|
.B yadm.auto-alt
|
|
Disable the automatic linking described in the section ALTERNATES. If disabled,
|
|
you may still run "yadm alt" manually to create the alternate links. This
|
|
feature is enabled by default.
|
|
.TP
|
|
.B yadm.auto-exclude
|
|
Disable the automatic exclusion of patterns defined in
|
|
.IR $HOME/.config/yadm/encrypt .
|
|
This feature is enabled by default.
|
|
.TP
|
|
.B yadm.auto-perms
|
|
Disable the automatic permission changes described in the section PERMISSIONS.
|
|
If disabled, you may still run
|
|
.B yadm perms
|
|
manually to update permissions.
|
|
This feature is enabled by default.
|
|
.TP
|
|
.B yadm.auto-private-dirs
|
|
Disable the automatic creating of private directories described in the section PERMISSIONS.
|
|
.TP
|
|
.B yadm.git-program
|
|
Specify an alternate program to use instead of "git".
|
|
By default, the first "git" found in $PATH is used.
|
|
.TP
|
|
.B yadm.gpg-perms
|
|
Disable the permission changes to
|
|
.IR $HOME/.gnupg/* .
|
|
This feature is enabled by default.
|
|
.TP
|
|
.B yadm.gpg-program
|
|
Specify an alternate program to use instead of "gpg".
|
|
By default, the first "gpg" found in $PATH is used.
|
|
.TP
|
|
.B yadm.gpg-recipient
|
|
Asymmetrically encrypt files with a gpg public/private key pair.
|
|
Provide a "key ID" to specify which public key to encrypt with.
|
|
The key must exist in your public keyrings.
|
|
If left blank or not provided, symmetric encryption is used instead.
|
|
If set to "ASK", gpg will interactively ask for recipients.
|
|
See the ENCRYPTION section for more details.
|
|
This feature is disabled by default.
|
|
.TP
|
|
.B yadm.ssh-perms
|
|
Disable the permission changes to
|
|
.IR $HOME/.ssh/* .
|
|
This feature is enabled by default.
|
|
|
|
.RE
|
|
The following four "local" configurations are not stored in the
|
|
.IR $HOME/.config/yadm/config,
|
|
they are stored in the local repository.
|
|
|
|
.TP
|
|
.B local.class
|
|
Specify a class for the purpose of symlinking alternate files.
|
|
By default, no class will be matched.
|
|
.TP
|
|
.B local.hostname
|
|
Override the hostname for the purpose of symlinking alternate files.
|
|
.TP
|
|
.B local.os
|
|
Override the OS for the purpose of symlinking alternate files.
|
|
.TP
|
|
.B local.user
|
|
Override the user for the purpose of symlinking alternate files.
|
|
|
|
.SH ALTERNATES
|
|
|
|
When managing a set of files across different systems, it can be useful to have
|
|
an automated way of choosing an alternate version of a file for a different
|
|
operating system, host, user, etc.
|
|
|
|
yadm will automatically create a symbolic link to the appropriate version of a
|
|
file, when a valid suffix is appended to the filename. The suffix contains
|
|
the conditions that must be met for that file to be used.
|
|
|
|
The suffix begins with "##", followed by any number of conditions separated by
|
|
commas.
|
|
|
|
##<condition>[,<condition>,...]
|
|
|
|
Each condition is an attribute/value pair, separated by a period. Some
|
|
conditions do not require a "value", and in that case, the period and value can
|
|
be omitted. Most attributes can be abbreviated as a single letter.
|
|
|
|
<attribute>[.<value>]
|
|
|
|
These are the supported attributes, in the order of the weighted precedence:
|
|
|
|
.TP
|
|
.BR template , " t
|
|
Valid when the value matches a supported template processor.
|
|
See the TEMPLATES section for more details.
|
|
.TP
|
|
.BR user , " u
|
|
Valid if the value matches the current user.
|
|
Current user is calculated by running
|
|
.BR "id -u -n" .
|
|
.TP
|
|
.BR distro , " d
|
|
Valid if the value matches the distro.
|
|
Distro is calculated by running
|
|
.B "lsb_release -si"
|
|
or by inspecting the ID from
|
|
.BR "/etc/os-release" .
|
|
.TP
|
|
.BR os , " o
|
|
Valid if the value matches the OS.
|
|
OS is calculated by running
|
|
.BR "uname -s" .
|
|
.TP
|
|
.BR class , " c
|
|
Valid if the value matches the
|
|
.B local.class
|
|
configuration.
|
|
Class must be manually set using
|
|
.BR "yadm config local.class <class>" .
|
|
See the CONFIGURATION section for more details about setting
|
|
.BR local.class .
|
|
.TP
|
|
.BR hostname , " h
|
|
Valid if the value matches the short hostname.
|
|
Hostname is calculated by running
|
|
.BR "uname -n" ,
|
|
and trimming off any domain.
|
|
.TP
|
|
.B default
|
|
Valid when no other alternate is valid.
|
|
.LP
|
|
|
|
.BR NOTE :
|
|
The OS for "Windows Subsystem for Linux" is reported as "WSL", even
|
|
though uname identifies as "Linux".
|
|
|
|
You may use any number of conditions, in any order.
|
|
An alternate will only be used if ALL conditions are valid.
|
|
For all files managed by yadm's repository or listed in
|
|
.IR $HOME/.config/yadm/encrypt ,
|
|
if they match this naming convention,
|
|
symbolic links will be created for the most appropriate version.
|
|
|
|
The "most appropriate" version is determined by calculating a score for each
|
|
version of a file. A template is always scored higher than any symlink
|
|
condition. The number of conditions is the next largest factor in scoring.
|
|
Files with more conditions will always be favored. Any invalid condition will
|
|
disqualify that file completely.
|
|
|
|
If you don't care to have all versions of alternates stored in the same
|
|
directory as the generated symlink, you can place them in the
|
|
.I $HOME/.config/yadm/alt
|
|
directory. The generated symlink or processed template will be created using
|
|
the same relative path.
|
|
|
|
Alternate linking may best be demonstrated by example. Assume the following
|
|
files are managed by yadm's repository:
|
|
|
|
- $HOME/path/example.txt##default
|
|
- $HOME/path/example.txt##class.Work
|
|
- $HOME/path/example.txt##os.Darwin
|
|
- $HOME/path/example.txt##os.Darwin,hostname.host1
|
|
- $HOME/path/example.txt##os.Darwin,hostname.host2
|
|
- $HOME/path/example.txt##os.Linux
|
|
- $HOME/path/example.txt##os.Linux,hostname.host1
|
|
- $HOME/path/example.txt##os.Linux,hostname.host2
|
|
|
|
If running on a Macbook named "host2",
|
|
yadm will create a symbolic link which looks like this:
|
|
|
|
.IR $HOME/path/example.txt " -> " $HOME/path/example.txt##os.Darwin,hostname.host2
|
|
|
|
However, on another Mackbook named "host3", yadm will create a symbolic link
|
|
which looks like this:
|
|
|
|
.IR $HOME/path/example.txt " -> " $HOME/path/example.txt##os.Darwin
|
|
|
|
Since the hostname doesn't match any of the managed files, the more generic version is chosen.
|
|
|
|
If running on a Linux server named "host4", the link will be:
|
|
|
|
.IR $HOME/path/example.txt " -> " $HOME/path/example.txt##os.Linux
|
|
|
|
If running on a Solaris server, the link will use the default version:
|
|
|
|
.IR $HOME/path/example.txt " -> " $HOME/path/example.txt##default
|
|
|
|
If running on a system, with class set to "Work", the link will be:
|
|
|
|
.IR $HOME/path/example.txt " -> " $HOME/path/example.txt##class.Work
|
|
|
|
If no "##default" version exists and no files have valid conditions, then no
|
|
link will be created.
|
|
|
|
Links are also created for directories named this way, as long as they have at
|
|
least one yadm managed file within them.
|
|
|
|
yadm will automatically create these links by default. This can be disabled
|
|
using the
|
|
.I yadm.auto-alt
|
|
configuration.
|
|
Even if disabled, links can be manually created by running
|
|
.BR "yadm alt" .
|
|
|
|
Class is a special value which is stored locally on each host (inside the local
|
|
repository). To use alternate symlinks using class, you must set the value of
|
|
class using the configuration
|
|
.BR local.class .
|
|
This is set like any other yadm configuration with the
|
|
.B yadm config
|
|
command. The following sets the class to be "Work".
|
|
|
|
yadm config local.class Work
|
|
|
|
Similarly, the values of os, hostname, and user can be manually overridden
|
|
using the configuration options
|
|
.BR local.os ,
|
|
.BR local.hostname ,
|
|
and
|
|
.BR local.user .
|
|
|
|
.SH TEMPLATES
|
|
|
|
If a template condition is defined in an alternate file's "##" suffix, and the
|
|
necessary dependencies for the template are available, then the file will be
|
|
processed to create or overwrite files.
|
|
|
|
Supported template processors:
|
|
.TP
|
|
.B default
|
|
This is yadm's built-in template processor. This processor is very basic, with
|
|
a Jinja-like syntax. The advantage of this processor is that it only depends
|
|
upon
|
|
.BR awk ,
|
|
which is available on most *nix systems. To use this processor,
|
|
specify the value of "default" or just leave the value off (e.g. "##template").
|
|
.TP
|
|
.B j2cli
|
|
To use the j2cli Jinja template processor, specify the value of "j2" or
|
|
"j2cli".
|
|
.TP
|
|
.B envtpl
|
|
To use the envtpl Jinja template processor, specify the value of "j2" or "envtpl".
|
|
.LP
|
|
|
|
.BR NOTE :
|
|
Specifying "j2" as the processor will attempt to use j2cli or envtpl, whichever
|
|
is available.
|
|
|
|
If the template processor specified is available, templates will be processed
|
|
to create or overwrite files.
|
|
|
|
During processing, the following variables are available in the template:
|
|
|
|
Default Jinja Description
|
|
------------- ------------- --------------------------
|
|
yadm.class YADM_CLASS Locally defined yadm class
|
|
yadm.distro YADM_DISTRO lsb_release -si
|
|
yadm.hostname YADM_HOSTNAME uname -n (without domain)
|
|
yadm.os YADM_OS uname -s
|
|
yadm.user YADM_USER id -u -n
|
|
yadm.source YADM_SOURCE Template filename
|
|
|
|
.BR NOTE :
|
|
The OS for "Windows Subsystem for Linux" is reported as "WSL", even
|
|
though uname identifies as "Linux".
|
|
|
|
.BR NOTE :
|
|
If lsb_release is not available, DISTRO will be the ID specified in
|
|
/etc/os-release.
|
|
|
|
Examples:
|
|
|
|
.I whatever##template
|
|
with the following content
|
|
|
|
{% if yadm.user == 'harvey' %}
|
|
config={{yadm.class}}-{{yadm.os}}
|
|
{% else %}
|
|
config=dev-whatever
|
|
{% endif %}
|
|
|
|
would output a file named
|
|
.I whatever
|
|
with the following content if the user is "harvey":
|
|
|
|
config=work-Linux
|
|
|
|
and the following otherwise:
|
|
|
|
config=dev-whatever
|
|
|
|
An equivalent Jinja template named
|
|
.I whatever##template.j2
|
|
would look like:
|
|
|
|
{% if YADM_USER == 'harvey' -%}
|
|
config={{YADM_CLASS}}-{{YADM_OS}}
|
|
{% else -%}
|
|
config=dev-whatever
|
|
{% endif -%}
|
|
|
|
.SH ENCRYPTION
|
|
|
|
It can be useful to manage confidential files, like SSH or GPG keys, across
|
|
multiple systems. However, doing so would put plain text data 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
|
|
.BR gpg (1)
|
|
command is available.
|
|
|
|
To use this feature, a list of patterns must be created and saved as
|
|
.IR $HOME/.config/yadm/encrypt .
|
|
This list of patterns should be relative to the configured
|
|
.IR work-tree " (usually
|
|
.IR $HOME ).
|
|
For example:
|
|
|
|
.RS
|
|
.ssh/*.key
|
|
.gnupg/*.gpg
|
|
.RE
|
|
|
|
Standard filename expansions (*, ?, [) are supported.
|
|
If you have Bash version 4, you may use "**" to match all subdirectories.
|
|
Other shell expansions like brace and tilde are not supported.
|
|
Spaces in paths are supported, and should not be quoted.
|
|
If a directory is specified, its contents will be included, but not recursively.
|
|
Paths beginning with a "!" will be excluded.
|
|
|
|
The
|
|
.B 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
|
|
.IR $HOME/.config/yadm/files.gpg .
|
|
The patterns and files.gpg should be added to the yadm repository so they are
|
|
available across multiple systems.
|
|
|
|
To decrypt these files later, or on another system run
|
|
.B yadm decrypt
|
|
and provide the correct password.
|
|
After files are decrypted, permissions are automatically updated as described
|
|
in the PERMISSIONS section.
|
|
|
|
Symmetric encryption is used by default, but asymmetric encryption may be
|
|
enabled using the
|
|
.I yadm.gpg-recipient
|
|
configuration.
|
|
|
|
.BR NOTE :
|
|
It is recommended that you use a private repository when keeping confidential
|
|
files, even though they are encrypted.
|
|
|
|
Patterns found in
|
|
.I $HOME/.config/yadm/encrypt
|
|
are automatically added to the repository's
|
|
.I info/exclude
|
|
file every time
|
|
.B yadm encrypt
|
|
is run.
|
|
This is to prevent accidentally committing sensitive data to the repository.
|
|
This can be disabled using the
|
|
.I yadm.auto-exclude
|
|
configuration.
|
|
|
|
.B Using 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 repo by running
|
|
.BR "yadm git-crypt" .
|
|
git-crypt enables transparent encryption and decryption of files in a git repository.
|
|
You can read
|
|
https://github.com/AGWA/git-crypt
|
|
for details.
|
|
.LP
|
|
|
|
.SH PERMISSIONS
|
|
|
|
When files are checked out of a Git repository, their initial permissions are
|
|
dependent upon the user's umask. Because of this, yadm will automatically
|
|
update the permissions of some file paths. The "group" and "others" permissions
|
|
will be removed from the following files:
|
|
|
|
.RI - " $HOME/.config/yadm/files.gpg
|
|
|
|
- All files matching patterns in
|
|
.I $HOME/.config/yadm/encrypt
|
|
|
|
- The SSH directory and files,
|
|
.I .ssh/*
|
|
|
|
- The GPG directory and files,
|
|
.I .gnupg/*
|
|
|
|
yadm will automatically update permissions by default. This can be disabled
|
|
using the
|
|
.I yadm.auto-perms
|
|
configuration. Even if disabled, permissions can be manually updated by running
|
|
.BR "yadm perms" .
|
|
The
|
|
.I .ssh
|
|
directory processing can be disabled using the
|
|
.I yadm.ssh-perms
|
|
configuration. The
|
|
.I .gnupg
|
|
directory processing can be disabled using the
|
|
.I yadm.gpg-perms
|
|
configuration.
|
|
|
|
When cloning a repo which includes data in a
|
|
.IR .ssh " or " .gnupg
|
|
directory, if those directories do not exist at the time of cloning, yadm will
|
|
create the directories with mask 0700 prior to merging the fetched data into
|
|
the work-tree.
|
|
|
|
When running a Git command and
|
|
.IR .ssh " or " .gnupg
|
|
directories do not exist, yadm will create those directories with mask 0700
|
|
prior to running the Git command. This can be disabled using the
|
|
.I yadm.auto-private-dirs
|
|
configuration.
|
|
|
|
.SH HOOKS
|
|
|
|
For every command yadm supports, a program can be provided to run before or
|
|
after that command. These are referred to as "hooks". yadm looks for hooks in
|
|
the directory
|
|
.IR $HOME/.config/yadm/hooks .
|
|
Each hook is named using a prefix of
|
|
.I pre_
|
|
or
|
|
.IR post_ ,
|
|
followed by the command which should trigger the hook. For
|
|
example, to create a hook which is run after every
|
|
.I yadm pull
|
|
command, create a hook named
|
|
.IR post_pull.
|
|
Hooks must have the executable file permission set.
|
|
|
|
If a
|
|
.I pre_
|
|
hook is defined, and the hook terminates with a non-zero exit status, yadm will
|
|
refuse to run the yadm command. For example, if a
|
|
.I pre_commit
|
|
hook is defined, but that command ends with a non-zero exit status, the
|
|
.I yadm commit
|
|
will never be run. This allows one to "short-circuit" any operation using a
|
|
.I pre_
|
|
hook.
|
|
|
|
Hooks have the following environment variables available to them at runtime:
|
|
.TP
|
|
.B YADM_HOOK_COMMAND
|
|
The command which triggered the hook
|
|
.TP
|
|
.B YADM_HOOK_EXIT
|
|
The exit status of the yadm command
|
|
.TP
|
|
.B YADM_HOOK_FULL_COMMAND
|
|
The yadm command with all command line arguments
|
|
.TP
|
|
.B YADM_HOOK_REPO
|
|
The path to the yadm repository
|
|
.TP
|
|
.B YADM_HOOK_WORK
|
|
The path to the work-tree
|
|
|
|
.SH FILES
|
|
|
|
All of yadm's configurations are relative to the "yadm directory".
|
|
yadm uses the "XDG Base Directory Specification" to determine this directory.
|
|
If the environment variable
|
|
.B $XDG_CONFIG_HOME
|
|
is defined as a fully qualified path, this directory will be
|
|
.IR "$XDG_CONFIG_HOME/yadm" .
|
|
Otherwise it will be
|
|
.IR "$HOME/.config/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.
|
|
.TP
|
|
.I $HOME/.config/yadm
|
|
The yadm directory. By default, all data yadm stores is relative to this
|
|
directory.
|
|
.TP
|
|
.I $YADM_DIR/config
|
|
Configuration file for yadm.
|
|
.TP
|
|
.I $YADM_DIR/alt
|
|
This is a directory to keep "alternate files" without having them side-by-side
|
|
with the resulting symlink or processed template. Alternate files placed in
|
|
this directory will be created relative to $HOME instead.
|
|
.TP
|
|
.I $YADM_DIR/repo.git
|
|
Git repository used by yadm.
|
|
.TP
|
|
.I $YADM_DIR/encrypt
|
|
List of globs used for encrypt/decrypt
|
|
.TP
|
|
.I $YADM_DIR/files.gpg
|
|
All files encrypted with
|
|
.B yadm encrypt
|
|
are stored in this file.
|
|
|
|
.SH EXAMPLES
|
|
|
|
.TP
|
|
.B yadm init
|
|
Create an empty repo for managing files
|
|
.TP
|
|
.B yadm add .bash_profile ; yadm commit
|
|
Add
|
|
.I .bash_profile
|
|
to the Git index and create a new commit
|
|
.TP
|
|
.B yadm remote add origin <url>
|
|
Add a remote origin to an existing repository
|
|
.TP
|
|
.B yadm push -u origin master
|
|
Initial push of master to origin
|
|
.TP
|
|
.B echo ".ssh/*.key" >> $HOME/.config/yadm/encrypt
|
|
Add a new pattern to the list of encrypted files
|
|
.TP
|
|
.B yadm encrypt ; yadm add ~/.config/yadm/files.gpg ; yadm commit
|
|
Commit a new set of encrypted files
|
|
|
|
.SH REPORTING BUGS
|
|
|
|
Report issues or create pull requests at GitHub:
|
|
|
|
https://github.com/TheLocehiliosan/yadm/issues
|
|
|
|
.SH AUTHOR
|
|
|
|
Tim Byrne <sultan@locehilios.com>
|
|
|
|
.SH SEE ALSO
|
|
|
|
.BR git (1),
|
|
.BR gpg (1)
|
|
|
|
https://yadm.io/
|