checklinks - create/update links
checklinks [ options ]
Create or update links based on a file
Set the level threshold to show status messages.
0 show everything 1 filter "ok" and "absolute" messages 2 filter everything but "EXISTS" and "no dst" >2 no messages
While reading the links file, replace $parameter with value.
When used in conjuction with ct(1), $package will be set to the current
package's absolute path,
$etc will be set to $package/etc (e.g. ~/packages/caretaker/etc) and $pkgdir
will point to the package root (e.g. ~/packages). Also, for each of these
parameters, r_param (e.g. $r_etc) is the corresponding relative path as
seen from $HOME.
Shortcut for --msglevel=1
Remove all link sources (hardlinks: only if their destination exists)
Typical checklinks output might look like this:
ok .zshrc -> packages/zsh/etc/rc ok .zprofile -> packages/zsh/etc/profile absolute .zlogin -> packages/zsh/etc/login created .zlogout -> packages/zsh/etc/logout ok .zshenv -> packages/zsh/etc/env
The first item is the status, the second the link source (as in, the link), the third the link target.
The following status messages are possible:
The link exists and points to the right file
The link exists and points to the right file, however it is an absolute link
The link pointed to the wrong file and has been corrected
The source existed, but was not identical to the target. It has been deleted and replaced with a link to the target
The link did not exist and has been created
The source already exists, but is not a symlink
The link destination does not exist and therefore cannot be hardlinked to
The symlink definitions are read from the file .links or links in the current working directory. Each line contains, separated by spaces:
This may either be 'soft' or 'hard' (symlink / hardlink) or 'auto'.
If the type is auto, the following fields may be omitted. Instead, the notes in "AUTO SYMLINKS" apply.
path of the source, i.e. the link. Relative to $HOME
In symlink mode, the source will only be updated if it either does not exist or already is a symlink. This should prevent accidental data loss. Note that in hardlink mode, the source will always be deleted unless it is already the correct hardlink
path of the target, i.e. the link's destination. This is relative to the source. See path_resolution(7)
Lines beginning with an invalid symlink type will be ignored. I recommend using a # to introduce comments, though, and not simply write something into the file just because that is (technically) also ok ;)
Example:
# checklinks --parameter etc=packages/zsh soft .zshrc $etc/rc soft .zprofile $etc/profile soft .zlogin $etc/login soft .zlogout $etc/logout soft .zshenv $etc/env
If the link type is 'auto', checklinks will attempt to guess which files are meant to be symlinked where. However, be aware that this feature is highly experimental and may be changed or removed in the future. So far it will only create absolute links. Also, do not mix 'auto' with other link types.
Automatic symlinking works this way: checklinks takes all files in either etc/, or (if that doesn't exist) the current directory. All files in there will be symlinked as a dotfile from your home. If the directory only contains normal files, their corresponding symlink will have a . as prefix; if dotfiles are present, only these will be symlinked to (without adding another . as prefix, of course). This way, it is possibly to have various files in a directory, but only symlink those which are dotfiles.
Example:
remnant ~/p/zsh > ls -A etc completions functions hosts .zlogout .zshenv completions.zwc functions.zwc startx .zprofile .zshrc remnant ~/p/zsh > cat links auto remnant ~/p/zsh > checklinks ok .zshenv -> /home/derf/packages/zsh/etc/.zshenv ok .zlogout -> /home/derf/packages/zsh/etc/.zlogout ok .zshrc -> /home/derf/packages/zsh/etc/.zshrc ok .zprofile -> /home/derf/packages/zsh/etc/.zprofile
The exit value is the number of files with grave errors (a status of "exists" or "no dest").