05ed83ea34
Update version number and update documentation * Improve portability of shebang line (#14) * Support for symlinked directories (#17) * Improve portability of tar parameters (#18) * Support alternate gpg program (#19) * Fallback to using `ls` if `/bin/ls` does not exist (#22)
515 lines
13 KiB
Groff
515 lines
13 KiB
Groff
." vim: set spell so=8:
|
|
.TH yadm 1 "8 September 2016" "1.05"
|
|
.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 directory ]
|
|
|
|
.B yadm
|
|
.RI clone " url
|
|
.RB [ -f ]
|
|
.RB [ -w
|
|
.IR directory ]
|
|
|
|
.B yadm
|
|
.RI config " name
|
|
.RI [ value ]
|
|
|
|
.B yadm
|
|
config
|
|
.RB [ -e ]
|
|
|
|
.B yadm
|
|
list
|
|
.RB [ -a ]
|
|
|
|
.BR yadm " encrypt
|
|
|
|
.BR yadm " decrypt
|
|
.RB [ -l ]
|
|
|
|
.BR yadm " alt
|
|
|
|
.BR yadm " perms
|
|
.SH DESCRIPTION
|
|
.B yadm
|
|
is a tool for managing a collection of files across multiple computers,
|
|
using a shared Git repository.
|
|
In addition,
|
|
.B yadm
|
|
provides a feature to select alternate versions of files
|
|
based on the operation system or host name.
|
|
Lastly,
|
|
.B 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
|
|
.B yadm
|
|
is passed through to
|
|
.BR git (1).
|
|
Git commands or aliases are invoked with the
|
|
.B 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 for any managed files matching the naming rules describe in the ALTERNATES section.
|
|
It is usually unnecessary to run this command, as
|
|
.B yadm
|
|
automatically processes alternates by default.
|
|
This automatic behavior can be disabled by setting the configuration
|
|
.I yadm.auto-alt
|
|
to "false".
|
|
.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.
|
|
It is up to the user to resolve these conflicts,
|
|
but if the desired action is to have the contents in the repository overwrite the existing files,
|
|
then a "hard reset" should accomplish that:
|
|
|
|
.RS
|
|
.RS
|
|
yadm reset --hard origin/master
|
|
.RE
|
|
.RE
|
|
.IP
|
|
The repository is stored in
|
|
.IR $HOME/.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.
|
|
.B yadm
|
|
can be forced to overwrite an existing repository by providing the
|
|
.BR -f " option.
|
|
.TP
|
|
.B config
|
|
This command manages configurations for
|
|
.BR 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/.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/.yadm/encrypt .
|
|
See the ENCRYPTION section for more details.
|
|
.TP
|
|
.B gitconfig
|
|
Pass options to the
|
|
.B git config
|
|
command. Since
|
|
.B 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
|
|
.BR yadm .
|
|
One useful case might be to configure the repository so untracked files are shown in status commands.
|
|
.B 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
|
|
.BR yadm " commands.
|
|
.TP
|
|
.B init
|
|
Initialize a new, empty repository for tracking dotfiles.
|
|
The repository is stored in
|
|
.IR $HOME/.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.
|
|
.B 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
|
|
.BR 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
|
|
.B perms
|
|
Update permissions as described in the PERMISSIONS section.
|
|
It is usually unnecessary to run this command, as
|
|
.B yadm
|
|
automatically processes permissions by default.
|
|
This automatic behavior can be disabled by setting the configuration
|
|
.I yadm.auto-perms
|
|
to "false".
|
|
.TP
|
|
.B version
|
|
Print the version of
|
|
.BR yadm .
|
|
.SH OPTIONS
|
|
|
|
.B 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
|
|
.B 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
|
|
.B yadm
|
|
directory.
|
|
.B yadm
|
|
stores its data relative to this directory.
|
|
.TP
|
|
.B --yadm-repo
|
|
Override the location of the
|
|
.B yadm
|
|
repository.
|
|
.TP
|
|
.B --yadm-config
|
|
Override the location of the
|
|
.B yadm
|
|
configuration file.
|
|
.TP
|
|
.B --yadm-encrypt
|
|
Override the location of the
|
|
.B yadm
|
|
encryption configuration.
|
|
.TP
|
|
.B --yadm-archive
|
|
Override the location of the
|
|
.B yadm
|
|
encrypted files archive.
|
|
.SH CONFIGURATION
|
|
.B yadm
|
|
uses a configuration file named
|
|
.IR $HOME/.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.auto-alt
|
|
Disable the automatic linking described in the section ALTERNATES.
|
|
If disabled, you may still run
|
|
.B yadm alt
|
|
manually to create the alternate links.
|
|
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.ssh-perms
|
|
Disable the permission changes to
|
|
.IR $HOME/.ssh/* .
|
|
This feature is enabled by default.
|
|
.TP
|
|
.B yadm.gpg-perms
|
|
Disable the permission changes to
|
|
.IR $HOME/.gnupg/* .
|
|
This feature is enabled by default.
|
|
.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.gpg-program
|
|
Specify an alternate program to use instead of "gpg".
|
|
By default, the first "gpg" found in $PATH is used.
|
|
.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
|
|
operation system, host, or user.
|
|
.B yadm
|
|
implements a feature which will automatically create a symbolic link to
|
|
the appropriate version of a file, as long as you follow a specific naming
|
|
convention.
|
|
.B yadm
|
|
can detect files with names ending in:
|
|
|
|
.RS
|
|
.BR ## " or " ##OS " or " ##OS.HOSTNAME " or " ##OS.HOSTNAME.USER
|
|
.RE
|
|
|
|
If there are any files managed by
|
|
.BR yadm \'s
|
|
repository which match this naming convention,
|
|
symbolic links will be created for the most appropriate version.
|
|
This may best be demonstrated by example. Assume the following files are managed by
|
|
.BR yadm \'s
|
|
repository:
|
|
|
|
- $HOME/path/example.txt##
|
|
- $HOME/path/example.txt##Darwin
|
|
- $HOME/path/example.txt##Darwin.host1
|
|
- $HOME/path/example.txt##Darwin.host2
|
|
- $HOME/path/example.txt##Linux
|
|
- $HOME/path/example.txt##Linux.host1
|
|
- $HOME/path/example.txt##Linux.host2
|
|
|
|
If running on a Macbook named "host2",
|
|
.B yadm
|
|
will create a symbolic link which looks like this:
|
|
|
|
.IR $HOME/path/example.txt " -> " $HOME/path/example.txt##Darwin.host2
|
|
|
|
However, on another Mackbook named "host3",
|
|
.B yadm
|
|
will create a symbolic link which looks like this:
|
|
|
|
.IR $HOME/path/example.txt " -> " $HOME/path/example.txt##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##Linux
|
|
|
|
If running on a Solaris server, the link use the default "##" version:
|
|
|
|
.IR $HOME/path/example.txt " -> " $HOME/path/example.txt##
|
|
|
|
If no "##" version exists and no files match the current OS/HOSTNAME/USER, then no link will be created.
|
|
|
|
Links are also created for directories named this way, as long as they have at least one
|
|
.B yadm
|
|
managed file within them.
|
|
|
|
OS is determined by running
|
|
.BR uname\ -s ,
|
|
HOSTNAME by running
|
|
.BR hostname\ -s ,
|
|
and USER by running
|
|
.BR id\ -u\ -n .
|
|
.B 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 .
|
|
.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.
|
|
.B yadm
|
|
implements a feature which 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/.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
|
|
|
|
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/.yadm/files.gpg .
|
|
The patterns and files.gpg should be added to the
|
|
.B yadm
|
|
repository so they are available across multiple systems.
|
|
|
|
To decrypt these files later, or on another system run
|
|
.BR 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.
|
|
.SH PERMISSIONS
|
|
When files are checked out of a Git repository, their initial permissions are
|
|
dependent upon the user's umask. This can result in confidential files with lax permissions.
|
|
|
|
To prevent this,
|
|
.B yadm
|
|
will automatically update the permissions of confidential files.
|
|
The "group" and "others" permissions will be removed from the following files:
|
|
|
|
.RI - " $HOME/.yadm/files.gpg
|
|
|
|
- All files matching patterns in
|
|
.I $HOME/.yadm/encrypt
|
|
|
|
- The SSH directory and files,
|
|
.I .ssh/*
|
|
|
|
- The GPG directory and files,
|
|
.I .gnupg/*
|
|
|
|
.B 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 SSH directory processing can be disabled using the
|
|
.I yadm.ssh-perms
|
|
configuration.
|
|
.SH FILES
|
|
The following are the default paths
|
|
.B yadm
|
|
uses for its own data.
|
|
These paths can be altered using universal options.
|
|
See the OPTIONS section for details.
|
|
.TP
|
|
.I $HOME/.yadm
|
|
The
|
|
.B yadm
|
|
directory. By default, all data
|
|
.B yadm
|
|
stores is relative to this directory.
|
|
.TP
|
|
.I $YADM_DIR/config
|
|
Configuration file for
|
|
.BR yadm .
|
|
.TP
|
|
.I $YADM_DIR/repo.git
|
|
Git repository used by
|
|
.BR 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/.yadm/encrypt
|
|
Add a new pattern to the list of encrypted files
|
|
.TP
|
|
.B yadm encrypt ; yadm add ~/.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://thelocehiliosan.github.io/yadm/
|