checklinks - create/update links


checklinks [ options ]


Create or update links based on a file


-m, --msglevel=level

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

-p, --parameter parameter=value

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.

-q, --quiet

Shortcut for --msglevel=1

-r, --remove

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

absolute (soft links only)

The link exists and points to the right file, however it is an absolute link

fixed (soft links only)

The link pointed to the wrong file and has been corrected

updated (hard links only)

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

exists (soft links only)

The source already exists, but is not a symlink

no dest (hard links only)

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:

the symlink type

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.

the source

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

the target

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 ;)


  # 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


The exit value is the number of files with grave errors (a status of "exists" or "no dest").