From f2b2b64750f7c731cf865147b707f9cb328a06c1 Mon Sep 17 00:00:00 2001 From: Tim Byrne Date: Tue, 31 Jan 2017 18:00:06 -0600 Subject: [PATCH] Bring man page up-to-date with new features --- yadm | 1 + yadm.1 | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 103 insertions(+), 12 deletions(-) diff --git a/yadm b/yadm index f12ab4e..c8b287b 100755 --- a/yadm +++ b/yadm @@ -442,6 +442,7 @@ Commands: yadm config - 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 diff --git a/yadm.1 b/yadm.1 index c1723af..6226fbe 100644 --- a/yadm.1 +++ b/yadm.1 @@ -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\ . 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