1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
|
=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 dotfile manager, which however happens to support
a sort of packages, version control, automatic sym- and hardlinking, and
can also handle scripts and binaries.
It evolved from two hg repos for ~/bin and ~/etc and some management scripts.
They served their purpose well, but at some point I decided that it'd be nice
to only have the dotfiles/scripts actually used on a host.
So I needed separate repositories for zsh configs, Xorg configs, etc.
Managing them would probably be a little more work than previously, so it was
time to write a script for that purpose, which is now called B<caretaker>.
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, if
you're up to that sort of weird VCS abuse ;-)
I myself use caretaker with repos containing various dotfiles and scripts
/ binaries.
=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 package root, in caretaker referred to as $PKG_ROOT, is structured just like
the package directory $PKG_DIR, except that it neither contains .list nor
.list-remote. It is the central point where caretaker fetches
packages from and pushes packages to.
It should contain the pkglist script shipped in examples/.
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 'ct 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 or four 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; in the remote list, the fourth
is the package root to which this package belongs. Example:
caretaker git 82d716d01dee0329af7df5e67b55558fe3ff1466 git://git.tabularazor.org/~derf
The package list is generated by the script set in the config var $PKGLIST_PATH,
by default F<examples/pkglist>. Depending on $PKGLIST_LOCAL and $PKG_ROOT, it
is either executed on the local host or (via ssh) 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. Unless your package contains a links file, all files in
this directory (or, if it contains dotfiles, only the dotfiles) will
automatically symlinked as dotfiles from your home using checklinks(1).
So, for example F<etc/vimrc> will be installed as F<~/.vimrc>.
If you do not want this behaviour, create an empty links file.
To disable it for all packages, set MAGIC_ETC=0.
=item hooks/
Package hooks, see L</"HOOKS">
=item man/
Manual files, separated by section (like man/7/caretaker.pod).
Files with valid POD will be processed with pod2man, all other files which do
not have a .pod suffix are assumed to be *roff source and directly put into
the manual directory (with a symlink).
See also L</"COLLECTED PACKAGE FILES">
=item provides/
Files for inclusion into other packages. See L</"PROVIDES">
=item description
Package description for B<ct info>
=item links
Manual sym- and hardlink definitions. 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 UNLISTED PACKAGES
It is possible to have local packages which do not exist in the package root,
as long as they have a working git origin. Note that they will always be
pulled/pushed when doing batch pull/push, though.
=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
=item B<force_depend package> I<package>
Like B<depend>, but installs the package without asking the user for
confirmation.
=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
=item post-update
Sourced after a package was updated.
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
=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 contains only the directory F<man/>, which holds the
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)
|