Add markdown version of man page
This commit is contained in:
Tim Byrne
parent
f1a75db991
commit
f58f974d50
1 changed files with 287 additions and 0 deletions
287
yadm.md
Normal file
287
yadm.md
Normal file
|
|
@ -0,0 +1,287 @@
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## NAME
|
||||||
|
yadm - Yet Another Dotfiles Manager
|
||||||
|
|
||||||
|
## SYNOPSIS
|
||||||
|
yadm command [options]
|
||||||
|
|
||||||
|
yadm git-command-or-alias [options]
|
||||||
|
|
||||||
|
yadm init [-f]
|
||||||
|
|
||||||
|
yadm clone url [-f] [-w directory]
|
||||||
|
|
||||||
|
yadm config name [value]
|
||||||
|
|
||||||
|
yadm config [-e]
|
||||||
|
|
||||||
|
yadm list [-a]
|
||||||
|
|
||||||
|
yadm encrypt
|
||||||
|
|
||||||
|
yadm decrypt
|
||||||
|
|
||||||
|
yadm alt
|
||||||
|
|
||||||
|
yadm perms
|
||||||
|
|
||||||
|
## DESCRIPTION
|
||||||
|
yadm is a tool for managing a collection of files across multiple com-
|
||||||
|
puters, using a shared Git repository. In addition, yadm provides a
|
||||||
|
feature to select alternate versions of files based on the operation
|
||||||
|
system or host name. Lastly, yadm supplies the ability to manage a
|
||||||
|
subset of secure files, which are encrypted before they are included in
|
||||||
|
the repository.
|
||||||
|
|
||||||
|
## COMMANDS
|
||||||
|
git-command or git-alias
|
||||||
|
Any command not internally handled by yadm is passed through to
|
||||||
|
git(1). Git commands or aliases are invoked with the yadm man-
|
||||||
|
aged repository. The working directory for git commands will be
|
||||||
|
the configured work-tree (usually $HOME).
|
||||||
|
|
||||||
|
Dotfiles are managed by using standard git commands; add, com-
|
||||||
|
mit, push, pull, etc.
|
||||||
|
|
||||||
|
The config command is not passed directly through. Instead use
|
||||||
|
the gitconfig command (see below).
|
||||||
|
|
||||||
|
alt Create symbolic links for any managed files matching the naming
|
||||||
|
rules describe in the ALTERNATES section. It is usually unnec-
|
||||||
|
essary to run this command, as yadm automatically processes
|
||||||
|
alternates by default. This automatic behavior can be disabled
|
||||||
|
by setting the configuration yadm.auto-alt to "false".
|
||||||
|
|
||||||
|
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
|
||||||
|
already present in the work-tree, this merge will fail and
|
||||||
|
instead a "reset" of 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:
|
||||||
|
|
||||||
|
yadm reset --hard origin/master
|
||||||
|
|
||||||
|
The repository is stored in $HOME/.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.
|
||||||
|
|
||||||
|
config This command manages configurations for yadm. This command
|
||||||
|
works exactly they way git-config(1) does. See the CONFIGURA-
|
||||||
|
TION section for more details.
|
||||||
|
|
||||||
|
decrypt
|
||||||
|
Decrypt all files stored in $HOME/.yadm/files.gpg. Files
|
||||||
|
decrypted will be relative to the configured work-tree (usually
|
||||||
|
$HOME).
|
||||||
|
|
||||||
|
encrypt
|
||||||
|
Encrypt all files matching the patterns found in
|
||||||
|
$HOME/.yadm/encrypt. See the ENCRYPTION section for more
|
||||||
|
details.
|
||||||
|
|
||||||
|
gitconfig
|
||||||
|
Pass options to the git config command. Since yadm already uses
|
||||||
|
the config command to manage its own configurations, this com-
|
||||||
|
mand is provided as a way to change configurations of the repos-
|
||||||
|
itory managed by yadm. One particularly useful case may be to
|
||||||
|
configure the repository so untracked files are hidden from sta-
|
||||||
|
tus commands:
|
||||||
|
|
||||||
|
yadm gitconfig status.showUntrackedFiles no
|
||||||
|
|
||||||
|
help Print a summary of yadm commands.
|
||||||
|
|
||||||
|
init Initialize a new, empty repository for tracking dotfiles. The
|
||||||
|
repository is stored in $HOME/.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.
|
||||||
|
|
||||||
|
list Print a list of files managed by yadm. The -a option will cause
|
||||||
|
all managed files to be listed. Otherwise, the list will only
|
||||||
|
include files from the current directory or below.
|
||||||
|
|
||||||
|
perms Update permissions as described in the PERMISSIONS section. It
|
||||||
|
is usually unnecessary to run this command, as yadm automati-
|
||||||
|
cally processes permissions by default. This automatic behavior
|
||||||
|
can be disabled by setting the configuration yadm.auto-perms to
|
||||||
|
"false".
|
||||||
|
|
||||||
|
version
|
||||||
|
Print the version of yadm.
|
||||||
|
|
||||||
|
## CONFIGURATION
|
||||||
|
yadm uses a configuration file named $HOME/.yadm/config. This file
|
||||||
|
uses the same format as git-config(1). Also, you can control the con-
|
||||||
|
tents of the configuration file via the yadm config command (which
|
||||||
|
works exactly like git-config). For example, to disable alternates you
|
||||||
|
can run the command:
|
||||||
|
|
||||||
|
yadm config yadm.auto-alt false
|
||||||
|
|
||||||
|
The following is the full list of supported configurations:
|
||||||
|
|
||||||
|
yadm.auto-alt
|
||||||
|
Disable the automatic linking described in the section ALTER-
|
||||||
|
NATES. If disabled, you may still run yadm alt manually to cre-
|
||||||
|
ate the alternate links. This feature is enabled by default.
|
||||||
|
|
||||||
|
yadm.auto-perms
|
||||||
|
Disable the automatic permission changes described in the sec-
|
||||||
|
tion PERMISSIONS. If disabled, you may still run yadm perms
|
||||||
|
manually to update permissions. This feature is enabled by
|
||||||
|
default.
|
||||||
|
|
||||||
|
yadm.ssh-perms
|
||||||
|
Disable the permission changes to $HOME/.ssh/*. This feature is
|
||||||
|
enabled by default.
|
||||||
|
|
||||||
|
## 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 or simply for a different host. 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. yadm can detect files with names ending with:
|
||||||
|
|
||||||
|
##SYSTEM or ##SYSTEM.HOSTNAME
|
||||||
|
|
||||||
|
If there are any files managed by yadm's repository which match this
|
||||||
|
naming convention, symbolic links will be created for the most appro-
|
||||||
|
priate version. This may best be demonstrated by example. Assume the
|
||||||
|
following files are managed by yadm's repository:
|
||||||
|
|
||||||
|
- $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", yadm will create a symbolic link
|
||||||
|
which looks like this:
|
||||||
|
|
||||||
|
$HOME/path/example.txt -> $HOME/path/example.txt##Darwin.host2
|
||||||
|
|
||||||
|
However, on another Mackbook named "host3", yadm will create a symbolic
|
||||||
|
link which looks like this:
|
||||||
|
|
||||||
|
$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:
|
||||||
|
|
||||||
|
$HOME/path/example.txt -> $HOME/path/example.txt##Linux
|
||||||
|
|
||||||
|
If running on a Solaris server, no link will be created because there
|
||||||
|
are no files managed for that SYSTEM.
|
||||||
|
|
||||||
|
SYSTEM is determined by running uname -s HOSTNAME by running host-
|
||||||
|
name -s. yadm will automatically create these links by default. This
|
||||||
|
can be disabled using the yadm.auto-alt configuration. Even if dis-
|
||||||
|
abled, links can be manually created by running yadm alt.
|
||||||
|
|
||||||
|
## ENCRYPTION
|
||||||
|
It can be useful to manage confidential files, like SSH keys, across
|
||||||
|
multiple systems. However, doing so would put plain text data into a
|
||||||
|
Git repository, which often resides on a public system. yadm imple-
|
||||||
|
ments 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 gpg(1) command is available.
|
||||||
|
|
||||||
|
To use this feature, a list of patterns must be created and saved as
|
||||||
|
$HOME/.yadm/encrypt. This list of patterns should be relative to the
|
||||||
|
configured work-tree (usually $HOME). For example:
|
||||||
|
|
||||||
|
.ssh/*.key
|
||||||
|
|
||||||
|
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/.yadm/files.gpg. The pat-
|
||||||
|
terns 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 yadm decrypt and
|
||||||
|
provide the correct password. After files are decrypted, permissions
|
||||||
|
are automatically updated as described in the PERMISSIONS section.
|
||||||
|
|
||||||
|
|
||||||
|
## PERMISSIONS
|
||||||
|
When files are checked out of a Git repository, their initial permis-
|
||||||
|
sions are dependent upon the user's umask. This can result in confiden-
|
||||||
|
tial files with lax permissions.
|
||||||
|
|
||||||
|
To prevent this, yadm will automatically update the permissions of con-
|
||||||
|
fidential files. The "group" and "others" permissions will be removed
|
||||||
|
from the following files:
|
||||||
|
|
||||||
|
- $HOME/.yadm/files.gpg
|
||||||
|
|
||||||
|
- All files matching patterns in $HOME/.yadm/encrypt
|
||||||
|
|
||||||
|
- The SSH directory and files, .ssh/*
|
||||||
|
|
||||||
|
yadm will automatically update permissions by default. This can be dis-
|
||||||
|
abled using the yadm.auto-perms configuration. Even if disabled, per-
|
||||||
|
missions can be manually updated by running yadm perms. The SSH direc-
|
||||||
|
tory processing can be disabled using the yadm.ssh-perms configuration.
|
||||||
|
|
||||||
|
## FILES
|
||||||
|
$HOME/.yadm/config
|
||||||
|
Configuration file for yadm.
|
||||||
|
|
||||||
|
$HOME/.yadm/repo.git
|
||||||
|
Git repository used by yadm.
|
||||||
|
|
||||||
|
$HOME/.yadm/encrypt
|
||||||
|
List of globs used for encrypt/decrypt
|
||||||
|
|
||||||
|
$HOME/.yadm/files.gpg
|
||||||
|
All files encrypted with yadm encrypt are stored in this file.
|
||||||
|
|
||||||
|
## EXAMPLES
|
||||||
|
yadm init
|
||||||
|
Create an empty repo for managing files
|
||||||
|
|
||||||
|
yadm add .bash_profile ; yadm commit
|
||||||
|
Add .bash_profile to the Git index and create a new commit
|
||||||
|
|
||||||
|
yadm remote add origin <url>
|
||||||
|
Add a remote origin to an existing repository
|
||||||
|
|
||||||
|
yadm push -u origin master
|
||||||
|
Initial push of master to origin
|
||||||
|
|
||||||
|
echo .ssh/*.key >> $HOME/.yadm/encrypt
|
||||||
|
Add a new pattern to the list of encrypted files
|
||||||
|
|
||||||
|
yadm encrypt ; yadm add ~/.yadm/files.gpg ; yadm commit
|
||||||
|
Commit a new set of encrypted files
|
||||||
|
|
||||||
|
## REPORTING BUGS
|
||||||
|
Report issues or create pull requests at GitHub:
|
||||||
|
|
||||||
|
https://github.com/TheLocehiliosan/yadm
|
||||||
|
|
||||||
|
## AUTHOR
|
||||||
|
Tim Byrne <sultan@locehilios.com>
|
||||||
|
|
||||||
|
## SEE ALSO
|
||||||
|
git(1), gpg(1)
|
||||||
|
|
||||||
|
Other management tools which inspired the creation of yadm:
|
||||||
|
|
||||||
|
homeshick <https://github.com/andsens/homeshick>
|
||||||
|
|
||||||
|
vcsh <https://github.com/RichiH/vcsh>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Loading…
Reference in a new issue