Bring man page up-to-date with new features

This commit is contained in:
Tim Byrne 2017-01-31 18:00:06 -06:00
parent 2a7203a67b
commit f2b2b64750
No known key found for this signature in database
GPG Key ID: 14DB4FC2465A4B12
2 changed files with 103 additions and 12 deletions

1
yadm
View File

@ -442,6 +442,7 @@ Commands:
yadm config <name> <value> - Configure a setting
yadm list [-a] - List tracked files
yadm alt - Create links for alternates
yadm bootstrap - Execute \$HOME/.yadm/bootstrap
yadm encrypt - Encrypt files
yadm decrypt [-l] - Decrypt files
yadm perms - Fix perms for private files

114
yadm.1
View File

@ -22,6 +22,8 @@ init
.RB [ -f ]
.RB [ -w
.IR directory ]
.RB [ --bootstrap ]
.RB [ --no-bootstrap ]
.B yadm
.RI config " name
@ -35,6 +37,8 @@ config
list
.RB [ -a ]
.BR yadm " bootstrap
.BR yadm " encrypt
.BR yadm " decrypt
@ -93,6 +97,11 @@ This automatic behavior can be disabled by setting the configuration
.I yadm.auto-alt
to "false".
.TP
.B bootstrap
Execute
.I $HOME/.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
@ -102,17 +111,28 @@ 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:
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 reset --hard origin/master
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
.IP
or
.RS
yadm stash pop
.RE
The repository is stored in
.IR $HOME/.yadm/repo.git .
By default,
@ -124,6 +144,14 @@ but this can be overridden with the
.B yadm
can be forced to overwrite an existing repository by providing the
.BR -f " option.
By default
.B 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
@ -250,6 +278,11 @@ encryption configuration.
Override the location of the
.B yadm
encrypted files archive.
.TP
.B --yadm-bootstrap
Override the location of the
.B yadm
bootstrap program.
.SH CONFIGURATION
.B yadm
uses a configuration file named
@ -309,6 +342,25 @@ By default, the first "gpg" found in $PATH is used.
.B yadm.git-program
Specify an alternate program to use instead of "git".
By default, the first "git" found in $PATH is used.
.RE
These last four "local" configurations are not stored in the
.IR $HOME/.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.os
Override the OS for the purpose of symlinking alternate files.
.TP
.B local.hostname
Override the HOSTNAME 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
@ -318,11 +370,16 @@ 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:
can detect files with names ending in any of the following:
.RS
.BR ## " or " ##OS " or " ##OS.HOSTNAME " or " ##OS.HOSTNAME.USER
.RE
##
##CLASS
##CLASS.OS
##CLASS.OS.HOSTNAME
##CLASS.OS.HOSTNAME.USER
##OS
##OS.HOSTNAME
##OS.HOSTNAME.USER
If there are any files managed by
.BR yadm \'s
@ -336,6 +393,7 @@ This may best be demonstrated by example. Assume the following files are managed
repository:
- $HOME/path/example.txt##
- $HOME/path/example.txt##Work
- $HOME/path/example.txt##Darwin
- $HOME/path/example.txt##Darwin.host1
- $HOME/path/example.txt##Darwin.host2
@ -365,16 +423,22 @@ 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.
If running on a system, with CLASS set to "Work", the link will be:
.IR $HOME/path/example.txt " -> " $HOME/path/example.txt##WORK
If no "##" version exists and no files match the current CLASS/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.
CLASS must be manually set using
.BR yadm\ config\ local.class\ <class> .
OS is determined by running
.BR uname\ -s ,
HOSTNAME by running
.BR hostname\ -s ,
.BR hostname ,
and USER by running
.BR id\ -u\ -n .
.B yadm
@ -383,6 +447,32 @@ will automatically create these links by default. This can be disabled using the
configuration.
Even if disabled, links can be manually created by running
.BR yadm\ alt .
It is possible to use "%" as a "wildcard" in place of CLASS, OS, HOSTNAME, or
USER. For example, The following file could be linked for any host when the
user is "harvey".
.IR $HOME/path/example.txt##%.%.harvey
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
.B 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 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