=head1 NAME

~/.config/caretaker/caretaker.conf - L<ct>(1) configuration

=head1 DESCRIPTION

Contains configuration parameters for L<ct>(1)

The file consists of multiple lines of the form I<parameter>=I<value>.

Normal zsh syntax is allowed, which means everything after '#' will be treated
as comment and that there must be no space between the parameter and the content.

With the exception of B<PKG_ROOT>, all parameters are optional as they have
reasonable (so I hope) defaults.

=head1 OPTIONS

The text in (braces) refers to the ct commandline option with which the config
setting may be overridden (if present).
The text in [these braces] is the default value.

=head2 GENERAL OPTIONS

=over

=item B<PKG_ROOTS>=(I<name1> I<name2> I<...>)

The package roots to use, at least one must be set.
For the package root definitions, see below.

=item B<PKG_DIR>=I<path>   (--packagedir I<path>)   [$HOME/packages]

path for the local package tree

=item B<CL_OPTIONS>=(I<options>)   (--checklinks-options I<options>)   [-q]

Options to invoke L<checklinks>(1) with

=item B<MAGIC_ETC>=I<boolean>   (--magic-etc)   [1]

Automatically run checklinks on files (or, if present, dotfiles) in F<etc/>

=item B<COLOURS>=I<boolean>   (--colours)   [1]

Colorize the output (cyan for info messages, red for errors/warnings)

=item B<HOOK_ON_PUSH>=I<boolean>   (--hook-on-push)   [1]

Execute pre-update / post-update hooks when running C<< ct push >>.
If set to 0, you need to run ct refresh by hand to execute these hooks after
changing a package.

=item B<PROGRESS>=I<boolean>   (--progress)   [1]

Show a progress bar when performing tasks on all packages

=item B<SILENT>=I<boolean>   (--quiet)   [0]

Operate in silent mode. If B<1>, it also sets PROGRESS=0

=item B<AUTOUPDATE>=I<boolean>   (--auto-update)   [1]

If 1, automatically execute 'ct update' before 'ct push'
and 'ct update remote' before 'ct upgrade'

=item B<function pkg_hook_>I<hook> {I<content>}

Define the global hook I<hook>, its I<content> will be executed
together with caretaker's global hooks; the name of the package for which the hook is
being executed will be given as first parameter and is accessible throug B<$1>.
The hook is just a zsh function, so you can use any valid syntax you want,
including newlines.
See zsh(1) for more.

Valid I<hook> names are: post-add, pre-update, post-update, pre-remove.
Note that post-add automatically executes post-update.

Example: function pkg_hook_post-update {clear_line; echo "Hello from package $1!"}

=back

=head2 ROOT-SPECIFIC OPTIONS

Each package root is defined as a function, more precisely,
C<< function pkgroot_I<name> { I<content> } >>.
You need at least one package root, and it must be enabled by putting its
I<name> into B<PKG_ROOTS> (see above).

The I<content> consists of variables like above.

=over

=item B<PKG_PROTO>=I<protocol>

Protocol to use. May be anything understood by git, e.g. file, git, ssh, http,
etc. Note that by default only file and ssh are supported, for other protocols
you will have to write your own pkglist script

=item B<PKG_USER>=I<username>

If B<PKG_PROTO> supports authentication, sets the login username.  If
authentication is not required/supported, don't set this or leave it empty

=item B<PKG_HOST>=I<hostname>

Remote host to connect to.  Leave empty if you use the "file" protocol

=item B<PKG_PATH>=I<path>

Absolute path in which your repositories are stored. E.g.
"/home/derf/var/packages_root"

=item B<PKGLIST_PATH>=I<path>   [$PKG_PATH/pkglist]

Path to the script generating the package list.

=item B<PKGLIST_LOCAL>=I<boolean>   [0]

If true, execute the package list on the local machine. Otherwise (e.g. wit
the ssh protocol) it will be executed on the remote host.

=back

=head2 COLOURS

Colours are defined in the same way as options. They take an ANSI escape code
as argument.

=over

=item B<c_info>=I<colour> (C<$'\e[0;36m'>)

Colour for informational messages (default: cyan)

=item B<c_error>=I<colour> (C<$'\e[0;31m'>)

Colour for warning and error messages (default: red)

=back

=head1 EXAMPLE

    PKG_ROOTS=(aneurysm)

    function pkgroot_aneurysm {
        PKG_PROTO=ssh
        PKG_HOST=aneurysm
        PKG_PATH=/home/derf/var/packages_root
    }

    # This will not be used, but may be enabled by appending it to the
    # PKG_ROOTS array. In this case we use a custom list script which does not
    # require PKG_USER / PKG_HOST / PKG_PATH to be set.
    function pkgroot_github {
        PKG_PROTO=https
        PKGLIST_LOCAL=1
        PKGLIST_PATH=${HOME}/libexec/pkglist-github
    }

=head1 SEE ALSO

L<ct>(1), L<checklinks>(1)