Renamed pkg to caretaker

1 files changed, 256 insertions, 0 deletions

diff --git a/man/7/caretaker.pod b/man/7/caretaker.pod
new file mode 100644
index 0000000..bbef02d
--- /dev/null
+++ b/man/7/caretaker.pod
@@ -0,0 +1,256 @@
+=head1 NAME
+
+caretaker - distributed dotfile and script manager, package format
+
+=head1 INTRO
+
+(if you prefer technical infos over historical blah-blah, skip this section)
+
+Actually, caretaker is just a pimped dotfile manager, which just happens to support
+a sort of packages, version control, automatic sym- and hardlinking, and which
+can also handle scripts and binaries. Oh, and it can cause serious brain damage.
+
+It evolved from two hg repos for ~/bin and ~/etc and some management scripts,
+and now it can handle as many git repos as you want, which may contain
+basically anything you can think of - you can even store movies in them.
+(Of course that would be completely braindead, but hey -
+you could, if you wanted to)
+
+=head1 THE BASICS
+
+caretaker requires two directories in your home directory. B<~/bin> contains
+symlinks to the executables shipped with your packages, and $PKG_DIR
+(B<~/packages> by default) contains the
+packages themselves. B<~/bin> may also contain normal executables; caretaker will
+not overwrite existing files.
+
+=head1 THE PACKAGE DIRECTORY
+
+$PKG_DIR is the core of all this stuff. Its main use is storing the packages.
+There is one directory for each installed package, as created by B<git clone>.
+$PKG_DIR holds two special files: B<.list> and B<.list-remote>. For
+an explanation about these files, see L</"THE PACKAGE LIST"> below.
+It also contains a special directory, F<.collected> - see L</"COLLECTED PACKAGE FILES">.
+
+=head2 NOTE
+
+All directories in $PKG_DIR must be valid git repositories which are not in the
+state of 'initial commit'. Dotfiles (directories starting with a .) are exempt
+from this, they will be ignored by caretaker.
+
+=head1 THE PACKAGE ROOT
+
+The packages_root, in caretaker referred to as $PKG_ROOT, is structured just like
+the packages directory $PKG_DIR, except that it neither contains .list nor
+.list-remote. The packages root is the central point where caretaker fetches
+packages from and pushes packages to.
+
+The package root should contain the pkglist script shipped in include/.
+If it doesn't, PKGLIST_PATH in .caretaker.conf must be set to the appropiate
+location on the package root host.
+
+=head1 THE PACKAGE LIST
+
+The package list lives in the files B<.list> and B<.list-remote> mentioned
+above. It's used to decide whether a package needs to be pulled / pushed.
+Also, the 'caretaker add' completion relies on .list-remote, and back in the days when
+caretaker supported more than one DVCS, it was used to determine which DVCS to use
+for which package.
+
+It consists of one line per package, each line containing three items separated
+by a single whitespace. The first item is the package name, the second one the
+repository type (DVCS), the third the current revision. Example:
+
+  caretaker git 82d716d01dee0329af7df5e67b55558fe3ff1466
+
+The package list is generated by the script set in the config var $PKGLIST_PATH,
+by default F<include/pkglist>.  Depending on $PKGLIST_LOCAL and $PKG_ROOT, it
+is either executed on the local host or on the remote host containing the package
+root.  The script is always called with $PKG_PATH as the first argument.
+Its output must only contain valid pkglist lines (see the example above).
+
+With $PKGLIST_LOCAL set to 1, there are some interesting possibilities.
+For instance, your pkglist script could contain a line like
+C<< curl -s http://example.org/cgi-bin/pkglist.cgi >> - so you can update your
+remote package list without having to use ssh.
+
+=head1 WHAT IS A PACKAGE?
+
+Anything tracked with git can be used as package. However, as the purpose of caretaker
+is not to do your version control, you probably want to have at least one of the
+files and directories described below in it.
+
+=head1 PACKAGE STRUCTURE
+
+Special (as in, mostly handled by caretaker) directories and files in a package.
+
+Note that all files and directories mentioned here are optional.
+
+=over
+
+=item bin/
+
+The place for executables to be in the user's PATH.
+caretaker will automatically create symlinks in F<~/bin> pointing to the files
+in the package's F<bin/>. Also, if a file in F<bin/> contains valid POD,
+a manual will be generated out of it (see L</"COLLECTED PACKAGE FILES">)
+
+=item etc/
+
+Configuration files, not treated specially though
+
+=item hooks/
+
+Package hooks, see L</"HOOKS">
+
+=item include/
+
+Scripts used by the package that don't belong into B<bin/>. Not treated specially
+
+=item man/
+
+Manual files in POD format, separated by section (like man/7/caretaker.pod).
+To be prepared for possible future support of other manual formats, it is
+recommended to postfix each file with .pod
+
+=item provides/
+
+Files for inclusion into other packages. See L</"PROVIDES">
+
+=item description
+
+Package description for B<ct info>
+
+=item links
+
+Sym- and hardlink descriptions. See checklinks(1)
+
+=item Makefile
+
+If a Makefile is available, C<make> will be executed every time the package
+is updated (ct add/push/pull/refresh)
+
+=item prereqs
+
+The package's prerequisites, mainly dependencies. See L</"PREREQUISITES">
+
+=item priority
+
+Package priority as an integer between 1 and 6.
+Packages with a priority above 3 require user confirmation to be removed
+
+=back
+
+=head1 PREREQUISITES
+
+The prerequisites are stored in a package in the file F<prereqs>.
+It as an ordinary shell script which is sourced by caretaker's global post-update
+hook; so it will be sourced after pulling, pushing or refreshing a package.
+
+Note that the file will be sourced in function scope. It is recommended to
+introduce parameters and options local to the prereqs script with
+C<< typeset >> and C<< setopt localoptions >>, respectively.
+
+It's main use is to check for dependencies. To help with this, the following
+functions are available:
+
+=over
+
+=item B<is_installed> I<package>
+
+Returns true if I<package> is installed, otherwise false
+
+=item B<perlmodule> I<perlmodule>
+
+Returns true if I<perlmodule> can be used by perl, otherwise false
+
+=item B<executable> I<commendname>
+
+Returns true if I<commandname> was found in the users PATH, otherwise false
+
+=item B<offer_install> I<package>
+
+Mark I<package> for installation
+
+=item B<depend> I<expression> | B<depend package> I<package>
+
+Execute expression and automatically warn if it fails.
+In case of B<depend package>, automatically mark B<package> for installation
+if it isn't installed.
+If a B<depend> fails, caretaker will inform the user about it and wait for confirmation
+
+=item B<recommend> I<...>, B<suggest> I<...>
+
+Take the same arguments as B<depend>, but are of lower priority.
+recommend only causes "info" messages, and suggest does not interrupt caretaker
+to make sure it's read by the user
+
+=back
+
+Additionally, the string parameters B<warn> and B<info> can be used to store
+messages.
+
+After executing the prereqs script, caretaker will print the content of
+these parameters and wait for confirmation.
+It will also offer to install packages marked by B<depend package> or
+B<recommend package>.
+
+=head1 PROVIDES
+
+The F<provides> directory contains subdirectories with the names of the package
+for which stuff is provided. Every time a package with a provides directory is
+added, updated or removed, for each of the directories in F<provides/>, the
+respective package's post-update hook is exectued. It is the responsibility
+of that hook to do something useful with the data in F<provides/>.
+
+=head1 HOOKS
+
+Hooks are little zsh snippets residing in $PKG_DIR/hooks
+which are sourced from within caretaker whenever needed.
+
+Currently, the following hooks exist:
+
+=over
+
+=item post-add
+
+Sourced after a package was installed (e.g. with ct add/ct install)
+
+=item post-update
+
+Sourced after a package was updated (ct pull).
+It is also sourced when adding a package (after post-add) and
+when calling ct refresh.
+
+=item pre-remove
+
+Sourced before a package is removed (ct remove)
+
+=back
+
+=head1 COLLECTED PACKAGE FILES
+
+These files reside in F<$PKG_DIR/.collected> (subject to change).
+
+The directory is somewhat similar to F<~/bin> - it is automatically populated
+by caretaker. However, this one does not contain symlinks.
+
+Currently, it only contains the directory F<man/>, which holds the "compiled"
+manual pages from the packages (extracted from F<bin/> and F<man/>).
+This way, you can put F<.../.collected/man> into you MANPATH to access manuals
+provided by packages.
+
+=head1 GIT
+
+B<caretaker> uses git(1) as backend for storing and syncing package information.
+It is not recommended to use branches other than "master".
+While they should work if GIT_USE_ORIGIN is set to 1 (the default), they will
+most likely confuse caretaker.
+
+=head1 AUTHOR
+
+Daniel Friesel E<lt>derf@derf.homelinux.orgE<gt>
+
+=head1 SEE ALSO
+
+checklinks(1), ct(1)