=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.

=over

=item B<PKG_ROOTS>=(I<url1> I<url2> I<...>)   (--packageroot I<url>)

the package root paths, at least one must be set.
I<url> may either be of the form C<protocol://host/path> or C</path>,
the supported protocols are C<git> and C<ssh>.
Note that pushing is not possible when the C<git> protocol is used.

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

path to pkglist on the package root, to generate the package list.
In the default, $PKG_PATH means the path component of $PKG_ROOT.

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

If true, B<PKLIST_PATH> will always be executed on the local machine, regardless
of where the B<PKG_ROOT> lies. For possible uses of this setting, see
L<caretaker(7)/"THE PACKAGE LIST">

=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<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<GIT_USE_ORIGIN>=I<boolean>   [1]

By default, caretaker will simply issue a git push/pull, so that git will use the
repository's origin to determine where to push/pull.

If you regularly change your PKG_ROOT, are too lazy to properly configure your
git repos or whatever, set this to 0. Then, caretaker will always call git pull/push
with both the remote repo and the branch as arguments.

=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 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 SEE ALSO

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