Debian Codegraph @

texmf-dist/doc/man/man1/tlmgr.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "TLMGR 1"
61 .TH TLMGR 1 2025-05-13 "perl v5.42.0" "User Contributed Perl Documentation"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 tlmgr \- the native TeX Live Manager
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 tlmgr [\fIoption\fR...] \fIaction\fR [\fIoption\fR...] [\fIoperand\fR...]
71 .SH DESCRIPTION
72 .IX Header "DESCRIPTION"
73 \&\fBtlmgr\fR manages an existing TeX Live installation, both packages and
74 configuration options. For information on initially downloading and
75 installing TeX Live, see <https://tug.org/texlive/acquire.html>.
76 .PP
77 The most up\-to\-date version of this documentation (updated nightly from
78 the development sources) is available at
79 <https://tug.org/texlive/tlmgr.html>, along with procedures for updating
80 \&\f(CW\*(C`tlmgr\*(C'\fR itself and information about test versions.
81 .PP
82 TeX Live is organized into a few top\-level \fIschemes\fR, each of which is
83 specified as a different set of \fIcollections\fR and \fIpackages\fR, where a
84 collection is a set of packages, and a package is what contains actual
85 files. Schemes typically contain a mix of collections and packages, but
86 each package is included in exactly one collection, no more and no less.
87 A TeX Live installation can be customized and managed at any level.
88 .PP
89 See <https://tug.org/texlive/doc> for all the TeX Live documentation
90 available.
91 .SH EXAMPLES
92 .IX Header "EXAMPLES"
93 After successfully installing TeX Live, here are a few common operations
94 with \f(CW\*(C`tlmgr\*(C'\fR:
95 .ie n .IP """tlmgr option repository ctan""" 4
96 .el .IP "\f(CWtlmgr option repository ctan\fR" 4
97 .IX Item "tlmgr option repository ctan"
98 .PD 0
99 .ie n .IP """tlmgr option repository https://mirror.ctan.org/systems/texlive/tlnet""" 4
100 .el .IP "\f(CWtlmgr option repository https://mirror.ctan.org/systems/texlive/tlnet\fR" 4
101 .IX Item "tlmgr option repository https://mirror.ctan.org/systems/texlive/tlnet"
102 .PD
103 Tell \f(CW\*(C`tlmgr\*(C'\fR to use a nearby CTAN mirror for future updates; useful if
104 you installed TeX Live from the DVD image and want to have continuing
105 updates. The two commands are equivalent; \f(CW\*(C`ctan\*(C'\fR is just an alias for
106 the given url.
107 .Sp
108 Caveat: \f(CW\*(C`mirror.ctan.org\*(C'\fR resolves to many different hosts, and they
109 are not perfectly synchronized; we recommend updating only daily (at
110 most), and not more often. You can choose a particular mirror if
111 problems; the list of all CTAN mirrors with the status of each is at
112 <https://ctan.org/mirrors/mirmon>.
113 .ie n .IP """tlmgr update \-\-list""" 4
114 .el .IP "\f(CWtlmgr update \-\-list\fR" 4
115 .IX Item "tlmgr update --list"
116 Report what would be updated without actually updating anything.
117 .ie n .IP """tlmgr update \-\-all""" 4
118 .el .IP "\f(CWtlmgr update \-\-all\fR" 4
119 .IX Item "tlmgr update --all"
120 Make your local TeX installation correspond to what is in the package
121 repository (typically useful when updating from CTAN).
122 .ie n .IP """tlmgr info"" \fIwhat\fR" 4
123 .el .IP "\f(CWtlmgr info\fR \fIwhat\fR" 4
124 .IX Item "tlmgr info what"
125 Display detailed information about a package \fIwhat\fR, such as the installation
126 status and description, of searches for \fIwhat\fR in all packages.
127 .ie n .IP """tlmgr bug"" \fIwhat\fR" 4
128 .el .IP "\f(CWtlmgr bug\fR \fIwhat\fR" 4
129 .IX Item "tlmgr bug what"
130 Display available bug\-reporting information for \fIwhat\fR, a package or
131 file name.
132 .PP
133 For all the capabilities and details of \f(CW\*(C`tlmgr\*(C'\fR, please read the
134 following voluminous information.
135 .SH OPTIONS
136 .IX Header "OPTIONS"
137 The following options to \f(CW\*(C`tlmgr\*(C'\fR are global options, not specific to
138 any action. All options, whether global or action\-specific, can be
139 given anywhere on the command line, and in any order. The first
140 non\-option argument will be the main action. In all cases,
141 \&\f(CW\*(C`\-\-\*(C'\fR\fIoption\fR and \f(CW\*(C`\-\*(C'\fR\fIoption\fR are equivalent, and an \f(CW\*(C`=\*(C'\fR is optional
142 between an option name and its value.
143 .IP "\fB\-\-repository\fR \fIurl|path\fR" 4
144 .IX Item "--repository url|path"
145 Specify the package repository from which packages should be installed
146 or updated, either a local directory or network location, as below. This
147 overridesthe default package repository found in the installation\*(Aqs TeX
148 Live Package Database (a.k.a. the TLPDB, which is given entirely in the
149 file \f(CW\*(C`tlpkg/texlive.tlpdb\*(C'\fR).
150 .Sp
151 This \f(CW\*(C`\-\-repository\*(C'\fR option changes the location only for the current
152 run; to make a permanent change, use \f(CW\*(C`option repository\*(C'\fR (see the
153 "option" action).
154 .Sp
155 As an example, you can choose a particular CTAN mirror with something
156 like this:
157 .Sp
158 .Vb 1
159 \& \-repository http://ctan.example.org/its/ctan/dir/systems/texlive/tlnet
160 .Ve
161 .Sp
162 Of course a real hostname and its particular top\-level CTAN directory
163 have to be specified. The list of CTAN mirrors is available at
164 <https://ctan.org/mirrors/mirmon>.
165 .Sp
166 Here\*(Aqs an example of using a local directory:
167 .Sp
168 .Vb 1
169 \& \-repository /local/TL/repository
170 .Ve
171 .Sp
172 For backward compatibility and convenience, \f(CW\*(C`\-\-location\*(C'\fR and \f(CW\*(C`\-\-repo\*(C'\fR
173 are accepted as aliases for this option.
174 .Sp
175 Locations can be specified as any of the following:
176 .RS 4
177 .ie n .IP """/some/local/dir""" 4
178 .el .IP \f(CW/some/local/dir\fR 4
179 .IX Item "/some/local/dir"
180 .PD 0
181 .ie n .IP """file:/some/local/dir""" 4
182 .el .IP \f(CWfile:/some/local/dir\fR 4
183 .IX Item "file:/some/local/dir"
184 .PD
185 Equivalent ways of specifying a local directory.
186 .ie n .IP """ctan""" 4
187 .el .IP \f(CWctan\fR 4
188 .IX Item "ctan"
189 .PD 0
190 .ie n .IP """https://mirror.ctan.org/systems/texlive/tlnet""" 4
191 .el .IP \f(CWhttps://mirror.ctan.org/systems/texlive/tlnet\fR 4
192 .IX Item "https://mirror.ctan.org/systems/texlive/tlnet"
193 .PD
194 Pick a CTAN mirror automatically, trying for one that is both nearby and
195 up\-to\-date. The chosen mirror is used for the entire download. The bare
196 \&\f(CW\*(C`ctan\*(C'\fR is merely an alias for the full url. (See <https://ctan.org> for
197 more about CTAN and its mirrors.)
198 .ie n .IP """http://server/path/to/tlnet""" 4
199 .el .IP \f(CWhttp://server/path/to/tlnet\fR 4
200 .IX Item "http://server/path/to/tlnet"
201 Standard HTTP. If the (default) LWP method is used, persistent
202 connections are supported. TL can also use \f(CW\*(C`curl\*(C'\fR or \f(CW\*(C`wget\*(C'\fR to do the
203 downloads, or an arbitrary user\-specified program, as described in the
204 \&\f(CW\*(C`tlmgr\*(C'\fR documentation
205 (<https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT\-VARIABLES>).
206 .ie n .IP """https://server/path/to/tlnet""" 4
207 .el .IP \f(CWhttps://server/path/to/tlnet\fR 4
208 .IX Item "https://server/path/to/tlnet"
209 Again, if the (default) LWP method is used, this supports persistent
210 connections. Unfortunately, some versions of \f(CW\*(C`wget\*(C'\fR and \f(CW\*(C`curl\*(C'\fR do not
211 support https, and even when \f(CW\*(C`wget\*(C'\fR supports https, certificates may be
212 rejected even when the certificate is fine, due to a lack of local
213 certificate roots. The simplest workaround for this problem is to use
214 http or ftp.
215 .ie n .IP """ftp://server/path/to/tlnet""" 4
216 .el .IP \f(CWftp://server/path/to/tlnet\fR 4
217 .IX Item "ftp://server/path/to/tlnet"
218 If the (default) LWP method is used, persistent connections are
219 supported.
220 .ie n .IP """user@machine:/path/to/tlnet""" 4
221 .el .IP \f(CWuser@machine:/path/to/tlnet\fR 4
222 .IX Item "user@machine:/path/to/tlnet"
223 .PD 0
224 .ie n .IP """scp://user@machine/path/to/tlnet""" 4
225 .el .IP \f(CWscp://user@machine/path/to/tlnet\fR 4
226 .IX Item "scp://user@machine/path/to/tlnet"
227 .ie n .IP """ssh://user@machine/path/to/tlnet""" 4
228 .el .IP \f(CWssh://user@machine/path/to/tlnet\fR 4
229 .IX Item "ssh://user@machine/path/to/tlnet"
230 .PD
231 These forms are equivalent; they all use \f(CW\*(C`scp\*(C'\fR to transfer files. Using
232 \&\f(CW\*(C`ssh\-agent\*(C'\fR is recommended. (Info:
233 <https://en.wikipedia.org/wiki/OpenSSH>,
234 <https://en.wikipedia.org/wiki/Ssh\-agent>.)
235 .RE
236 .RS 4
237 .Sp
238 If the repository is on the network, trailing \f(CW\*(C`/\*(C'\fR characters and/or
239 trailing \f(CW\*(C`/tlpkg\*(C'\fR and/or \f(CW\*(C`/archive\*(C'\fR components are ignored.
240 .RE
241 .IP "\fB\-\-gui\fR [\fIaction\fR]" 4
242 .IX Item "--gui [action]"
243 Two notable GUI front\-ends for \f(CW\*(C`tlmgr\*(C'\fR, \f(CW\*(C`tlshell\*(C'\fR and \f(CW\*(C`tlcockpit\*(C'\fR,
244 are started up as separate programs; see their own documentation.
245 .Sp
246 \&\f(CW\*(C`tlmgr\*(C'\fR itself has a graphical interface as well as the command line
247 interface. You can give the option to invoke it, \f(CW\*(C`\-\-gui\*(C'\fR, together with
248 an action to be brought directly into the respective screen of the GUI.
249 For example, running
250 .Sp
251 .Vb 1
252 \& tlmgr \-\-gui update
253 .Ve
254 .Sp
255 starts you directly at the update screen. If no action is given, the
256 GUI will be started at the main screen. See "GUI FOR TLMGR".
257 .Sp
258 However, the native GUI requires Perl/TK, which is no longer included in
259 TeX Live\*(Aqs Perl distribution for Windows. You may find \f(CW\*(C`tlshell\*(C'\fR or
260 \&\f(CW\*(C`tlcockpit\*(C'\fR easier to work with.
261 .IP "\fB\-\-gui\-lang\fR \fIllcode\fR" 4
262 .IX Item "--gui-lang llcode"
263 By default, the GUI tries to deduce your language from the environment
264 (on Windows via the registry, on Unix via \f(CW\*(C`LC_MESSAGES\*(C'\fR). If that fails
265 you can select a different language by giving this option with a
266 language code (based on ISO 639\-1). Currently supported (but not
267 necessarily completely translated) are: English\ (en,\ default),
268 Czech\ (cs), German\ (de), French\ (fr), Italian\ (it),
269 Japanese\ (ja), Dutch\ (nl), Polish\ (pl), Brazilian\ Portuguese\ (pt_BR), Russian\ (ru), Slovak\ (sk), Slovenian\ (sl), Serbian\ (sr), Ukrainian\ (uk), Vietnamese\ (vi), simplified\ Chinese\ (zh_CN), and traditional\ Chinese\ (zh_TW).
270 .Sp
271 tlshell shares its message catalog with tlmgr.
272 .IP "\fB\-\-command\-logfile\fR \fIfile\fR" 4
273 .IX Item "--command-logfile file"
274 \&\f(CW\*(C`tlmgr\*(C'\fR logs the output of all programs invoked (mktexlr, mtxrun, fmtutil,
275 updmap) to a separate log file, by default
276 \&\f(CW\*(C`TEXMFSYSVAR/web2c/tlmgr\-commands.log\*(C'\fR. This option allows you to specify a
277 different file for the log.
278 .IP \fB\-\-debug\-translation\fR 4
279 .IX Item "--debug-translation"
280 In GUI mode, this switch tells \f(CW\*(C`tlmgr\*(C'\fR to report any untranslated (or
281 missing) messages to standard error. This can help translators to see
282 what remains to be done.
283 .IP \fB\-\-machine\-readable\fR 4
284 .IX Item "--machine-readable"
285 Instead of the normal output intended for human consumption, write (to
286 standard output) a fixed format more suitable for machine parsing. See
287 the "MACHINE\-READABLE OUTPUT" section below.
288 .IP \fB\-\-no\-execute\-actions\fR 4
289 .IX Item "--no-execute-actions"
290 Suppress the execution of the execute actions as defined in the tlpsrc
291 files. Unless you are going to do the postprocessing yourself (as, for
292 example, \f(CW\*(C`install\-tl\*(C'\fR does), this shouldn\*(Aqt be specified. Otherwise,
293 format files and the filename database will become stale, among other
294 problems.
295 .IP "\fB\-\-package\-logfile\fR \fIfile\fR" 4
296 .IX Item "--package-logfile file"
297 \&\f(CW\*(C`tlmgr\*(C'\fR logs all package actions (install, remove, update, failed
298 updates, failed restores) to a separate log file, by default
299 \&\f(CW\*(C`TEXMFSYSVAR/web2c/tlmgr.log\*(C'\fR. This option allows you to specify a
300 different file for the log.
301 .IP \fB\-\-pause\fR 4
302 .IX Item "--pause"
303 This option makes \f(CW\*(C`tlmgr\*(C'\fR wait for user input before exiting. Useful on
304 Windows to avoid disappearing command windows.
305 .IP \fB\-\-persistent\-downloads\fR 4
306 .IX Item "--persistent-downloads"
307 .PD 0
308 .IP \fB\-\-no\-persistent\-downloads\fR 4
309 .IX Item "--no-persistent-downloads"
310 .PD
311 For network\-based installations, this option (on by default) makes
312 \&\f(CW\*(C`tlmgr\*(C'\fR try to set up a persistent connection (using the \f(CW\*(C`LWP\*(C'\fR Perl
313 module). The idea is to open and reuse only one connection per session
314 between your computer and the server, instead of initiating a new
315 download for each package.
316 .Sp
317 If this is not possible, \f(CW\*(C`tlmgr\*(C'\fR will fall back to using \f(CW\*(C`wget\*(C'\fR. To
318 disable these persistent connections, use \f(CW\*(C`\-\-no\-persistent\-downloads\*(C'\fR.
319 .IP \fB\-\-pin\-file\fR 4
320 .IX Item "--pin-file"
321 Change the pinning file location from \f(CW\*(C`TEXMFLOCAL/tlpkg/pinning.txt\*(C'\fR
322 (see "Pinning" below). Documented only for completeness, as this is
323 only useful in debugging.
324 .IP \fB\-\-usermode\fR 4
325 .IX Item "--usermode"
326 Activates user mode for this run of \f(CW\*(C`tlmgr\*(C'\fR; see "USER MODE" below.
327 .IP "\fB\-\-usertree\fR \fIdir\fR" 4
328 .IX Item "--usertree dir"
329 Uses \fIdir\fR for the tree in user mode; see "USER MODE" below.
330 .IP \fB\-\-verify\-repo=[none|main|all]\fR 4
331 .IX Item "--verify-repo=[none|main|all]"
332 Defines the level of verification done: If \f(CW\*(C`none\*(C'\fR is specified, no
333 verification whatsoever is done. If \f(CW\*(C`main\*(C'\fR is given and a working GnuPG
334 (\f(CW\*(C`gpg\*(C'\fR) binary is available, all repositories are checked, but only the
335 main repository is required to be signed. If \f(CW\*(C`all\*(C'\fR is given, then all
336 repositories need to be signed. See "CRYPTOGRAPHIC VERIFICATION" below
337 for details.
338 .PP
339 The standard options for TeX Live programs are also accepted:
340 \&\f(CW\*(C`\-\-help/\-h/\-?\*(C'\fR, \f(CW\*(C`\-\-version\*(C'\fR, \f(CW\*(C`\-q\*(C'\fR (no informational messages), \f(CW\*(C`\-v\*(C'\fR
341 (debugging messages, can be repeated). For the details about these, see
342 the \f(CW\*(C`TeXLive::TLUtils\*(C'\fR documentation.
343 .PP
344 The \f(CW\*(C`\-\-version\*(C'\fR option shows version information about the TeX Live
345 release and about the \f(CW\*(C`tlmgr\*(C'\fR script itself. If \f(CW\*(C`\-v\*(C'\fR is also given,
346 revision number for the loaded TeX Live Perl modules are shown, too.
347 .SH ACTIONS
348 .IX Header "ACTIONS"
349 .SS help
350 .IX Subsection "help"
351 Display this help information and exit (same as \f(CW\*(C`\-\-help\*(C'\fR, and on the
352 web at <https://tug.org/texlive/doc/tlmgr.html>). Sometimes the
353 \&\f(CW\*(C`perldoc\*(C'\fR and/or \f(CW\*(C`PAGER\*(C'\fR programs on the system have problems,
354 resulting in control characters being literally output. This can\*(Aqt
355 always be detected, but you can set the \f(CW\*(C`NOPERLDOC\*(C'\fR environment
356 variable and \f(CW\*(C`perldoc\*(C'\fR will not be used.
357 .SS version
358 .IX Subsection "version"
359 Gives version information (same as \f(CW\*(C`\-\-version\*(C'\fR).
360 .PP
361 If \f(CW\*(C`\-v\*(C'\fR has been given the revisions of the used modules are reported, too.
362 .SS backup
363 .IX Subsection "backup"
364 .IP "\fBbackup [\fR\f(BIoption\fR\fB...] \-\-all\fR" 4
365 .IX Item "backup [option...] --all"
366 .PD 0
367 .IP "\fBbackup [\fR\f(BIoption\fR\fB...] \fR\f(BIpkg\fR\fB...\fR" 4
368 .IX Item "backup [option...] pkg..."
369 .PD
370 If the \f(CW\*(C`\-\-clean\*(C'\fR option is not specified, this action makes a backup of
371 the given packages, or all packages given \f(CW\*(C`\-\-all\*(C'\fR. These backups are
372 saved to the value of the \f(CW\*(C`\-\-backupdir\*(C'\fR option, if that is an existing
373 and writable directory. If \f(CW\*(C`\-\-backupdir\*(C'\fR is not given, the \f(CW\*(C`backupdir\*(C'\fR
374 option setting in the TLPDB is used, if present. If both are missing, no
375 backups are made. (The installer sets \f(CW\*(C`backupdir\*(C'\fR to
376 \&\f(CW\*(C`.../tlpkg/backups\*(C'\fR, under the TL root installation directory, so it is
377 usually defined; see the "option" description for more information.)
378 .Sp
379 If the \f(CW\*(C`\-\-clean\*(C'\fR option is specified, backups are pruned (removed)
380 instead of saved. The optional integer value \fIN\fR may be specified to
381 set the number of backups that will be retained when cleaning. If \f(CW\*(C`N\*(C'\fR
382 is not given, the value of the \f(CW\*(C`autobackup\*(C'\fR option is used. If both are
383 missing, an error is issued. For more details of backup pruning, see
384 the \f(CW\*(C`option\*(C'\fR action.
385 .Sp
386 Options:
387 .RS 4
388 .IP "\fB\-\-backupdir\fR \fIdirectory\fR" 4
389 .IX Item "--backupdir directory"
390 Overrides the \f(CW\*(C`backupdir\*(C'\fR option setting in the TLPDB.
391 The \fIdirectory\fR argument is required and must specify an existing,
392 writable directory where backups are to be placed.
393 .IP \fB\-\-all\fR 4
394 .IX Item "--all"
395 If \f(CW\*(C`\-\-clean\*(C'\fR is not specified, make a backup of all packages in the TeX
396 Live installation; this will take quite a lot of space and time. If
397 \&\f(CW\*(C`\-\-clean\*(C'\fR is specified, all packages are pruned.
398 .IP \fB\-\-clean\fR[=\fIN\fR] 4
399 .IX Item "--clean[=N]"
400 Instead of making backups, prune the backup directory of old backups, as
401 explained above. The optional integer argument \fIN\fR overrides the
402 \&\f(CW\*(C`autobackup\*(C'\fR option set in the TLPDB. You must use \f(CW\*(C`\-\-all\*(C'\fR or a list
403 of packages together with this option, as desired.
404 .IP \fB\-\-dry\-run\fR 4
405 .IX Item "--dry-run"
406 Nothing is actually backed up or removed; instead, the actions to be
407 performed are written to the terminal.
408 .RE
409 .RS 4
410 .RE
411 .SS "bug [\fIsearch\-string\fP]"
412 .IX Subsection "bug [search-string]"
413 Searches for \fIsearch\-string\fR (prompted for, if not given) as a package
414 name and in package descriptions, as complete words, and in filenames,
415 as any substring, and outputs bug\-reporting and other information for
416 the package selected from the results.
417 .PP
418 The search is equivalent to \f(CW\*(C`tlmgr search \-\-word \-\-file\*(C'\fR \fIsearch\-string\fR.
419 Thus, \fIsearch\-string\fR is interpreted as a (Perl) regular expression.
420 .SS "candidates \fIpkg\fP"
421 .IX Subsection "candidates pkg"
422 Shows the available candidate repositories for package \fIpkg\fR.
423 See "MULTIPLE REPOSITORIES" below.
424 .SS "check [\fIoption\fP...] [depends|executes|files|runfiles|texmfdbs|all]"
425 .IX Subsection "check [option...] [depends|executes|files|runfiles|texmfdbs|all]"
426 Execute one (or all) check(s) of the consistency of the installation.
427 If no problems are found, there will be no output. (To get a view of
428 what is being done, run \f(CW\*(C`tlmgr \-v check\*(C'\fR.)
429 .IP \fBdepends\fR 4
430 .IX Item "depends"
431 Lists those packages which occur as dependencies in an installed collection,
432 but are themselves not installed, and those packages which are not
433 contained in any collection.
434 .Sp
435 If you call \f(CW\*(C`tlmgr check collections\*(C'\fR this test will be carried out
436 instead since former versions for \f(CW\*(C`tlmgr\*(C'\fR called it that way.
437 .IP \fBexecutes\fR 4
438 .IX Item "executes"
439 Check that the files referred to by \f(CW\*(C`execute\*(C'\fR directives in the TeX
440 Live Database are present.
441 .IP \fBfiles\fR 4
442 .IX Item "files"
443 Checks that all files listed in the local TLPDB (\f(CW\*(C`texlive.tlpdb\*(C'\fR) are
444 actually present, and lists those missing.
445 .IP \fBrunfiles\fR 4
446 .IX Item "runfiles"
447 List those filenames that are occurring more than one time in the
448 runfiles sections, except for known duplicates.
449 .IP \fBtexmfdbs\fR 4
450 .IX Item "texmfdbs"
451 Checks related to the \f(CW\*(C`ls\-R\*(C'\fR files. If you have defined new trees, or
452 changed the \f(CW\*(C`TEXMF\*(C'\fR or \f(CW\*(C`TEXMFDBS\*(C'\fR variables, it can\*(Aqt hurt to run
453 this. It checks that:
454 .RS 4
455 .ie n .IP "\- all items in ""TEXMFDBS"" have the ""!!"" prefix." 8
456 .el .IP "\- all items in \f(CWTEXMFDBS\fR have the \f(CW!!\fR prefix." 8
457 .IX Item "- all items in TEXMFDBS have the !! prefix."
458 .PD 0
459 .ie n .IP "\- all items in ""TEXMFBDS"" have an ""ls\-R"" file (if they exist at all)." 8
460 .el .IP "\- all items in \f(CWTEXMFBDS\fR have an \f(CWls\-R\fR file (if they exist at all)." 8
461 .IX Item "- all items in TEXMFBDS have an ls-R file (if they exist at all)."
462 .ie n .IP "\- all items in ""TEXMF"" with ""!!"" are listed in ""TEXMFDBS""." 8
463 .el .IP "\- all items in \f(CWTEXMF\fR with \f(CW!!\fR are listed in \f(CWTEXMFDBS\fR." 8
464 .IX Item "- all items in TEXMF with !! are listed in TEXMFDBS."
465 .ie n .IP "\- all items in ""TEXMF"" with an ""ls\-R"" file are listed in ""TEXMFDBS""." 8
466 .el .IP "\- all items in \f(CWTEXMF\fR with an \f(CWls\-R\fR file are listed in \f(CWTEXMFDBS\fR." 8
467 .IX Item "- all items in TEXMF with an ls-R file are listed in TEXMFDBS."
468 .PD
469 .RE
470 .RS 4
471 .RE
472 .PP
473 Options:
474 .IP \fB\-\-use\-svn\fR 4
475 .IX Item "--use-svn"
476 Use the output of \f(CW\*(C`svn status\*(C'\fR instead of listing the files; for
477 checking the TL development repository. (This is run nightly.)
478 .SS conf
479 .IX Subsection "conf"
480 .IP "\fBconf [texmf|tlmgr|updmap [\-\-conffile \fR\f(BIfile\fR\fB] [\-\-delete] [\fR\f(BIkey\fR\fB [\fR\f(BIvalue\fR\fB]]]\fR" 4
481 .IX Item "conf [texmf|tlmgr|updmap [--conffile file] [--delete] [key [value]]]"
482 .PD 0
483 .IP "\fBconf auxtrees [\-\-conffile \fR\f(BIfile\fR\fB] [show|add|remove] [\fR\f(BIvalue\fR\fB]\fR" 4
484 .IX Item "conf auxtrees [--conffile file] [show|add|remove] [value]"
485 .PD
486 With only \f(CW\*(C`conf\*(C'\fR, show general configuration information for TeX Live,
487 including active configuration files, path settings, and more. This is
488 like running \f(CW\*(C`texconfig conf\*(C'\fR, but works on all supported platforms.
489 .Sp
490 With one of \f(CW\*(C`conf texmf\*(C'\fR, \f(CW\*(C`conf tlmgr\*(C'\fR, or \f(CW\*(C`conf updmap\*(C'\fR, shows all
491 key/value pairs (i.e., all settings) as saved in \f(CW\*(C`ROOT/texmf.cnf\*(C'\fR, the
492 user\-specific \f(CW\*(C`tlmgr\*(C'\fR configuration file (see below), or the first
493 found (via \f(CW\*(C`kpsewhich\*(C'\fR) \f(CW\*(C`updmap.cfg\*(C'\fR file, respectively.
494 .Sp
495 If \fIkey\fR is given in addition, shows the value of only that \fIkey\fR in
496 the respective file. If option \fI\-\-delete\fR is also given, the value in
497 the given configuration file is entirely removed (not just commented
498 out).
499 .Sp
500 If \fIvalue\fR is given in addition, \fIkey\fR is set to \fIvalue\fR in the
501 respective file. \fINo error checking is done!\fR
502 .Sp
503 The \f(CW\*(C`PATH\*(C'\fR value shown by \f(CW\*(C`conf\*(C'\fR is as used by \f(CW\*(C`tlmgr\*(C'\fR. The
504 directory in which the \f(CW\*(C`tlmgr\*(C'\fR executable is found is automatically
505 prepended to the PATH value inherited from the environment.
506 .Sp
507 Here is a practical example of changing configuration values. If the
508 execution of (some or all) system commands via \f(CW\*(C`\ewrite18\*(C'\fR was left
509 enabled during installation, you can disable it afterwards:
510 .Sp
511 .Vb 1
512 \& tlmgr conf texmf shell_escape 0
513 .Ve
514 .Sp
515 The subcommand \f(CW\*(C`auxtrees\*(C'\fR allows adding and removing arbitrary
516 additional texmf trees, completely under user control. \f(CW\*(C`auxtrees show\*(C'\fR
517 shows the list of additional trees, \f(CW\*(C`auxtrees add\*(C'\fR \fItree\fR adds a tree
518 to the list, and \f(CW\*(C`auxtrees remove\*(C'\fR \fItree\fR removes a tree from the list
519 (if present). The trees should not contain an \f(CW\*(C`ls\-R\*(C'\fR file (or files
520 will not be found if the \f(CW\*(C`ls\-R\*(C'\fR becomes stale). This works by
521 manipulating the Kpathsea variable \f(CW\*(C`TEXMFAUXTREES\*(C'\fR, in (by default)
522 \&\f(CW\*(C`ROOT/texmf.cnf\*(C'\fR. Example:
523 .Sp
524 .Vb 2
525 \& tlmgr conf auxtrees add /quick/test/tree
526 \& tlmgr conf auxtrees remove /quick/test/tree
527 .Ve
528 .Sp
529 In all cases the configuration file can be explicitly specified via the
530 option \f(CW\*(C`\-\-conffile\*(C'\fR \fIfile\fR, e.g., if you don\*(Aqt want to change the
531 system\-wide configuration.
532 .Sp
533 Warning: The general facility for changing configuration values is here,
534 but tinkering with settings in this way is strongly discouraged. Again,
535 no error checking on either keys or values is done, so any sort of
536 breakage is possible.
537 .SS "dump\-tlpdb [\fIoption\fP...] [\-\-json]"
538 .IX Subsection "dump-tlpdb [option...] [--json]"
539 Dump complete local or remote TLPDB to standard output, as\-is. The
540 output is analogous to the \f(CW\*(C`\-\-machine\-readable\*(C'\fR output; see
541 "MACHINE\-READABLE OUTPUT" section.
542 .PP
543 Options:
544 .IP \fB\-\-local\fR 4
545 .IX Item "--local"
546 Dump the local TLPDB.
547 .IP \fB\-\-remote\fR 4
548 .IX Item "--remote"
549 Dump the remote TLPDB.
550 .IP \fB\-\-json\fR 4
551 .IX Item "--json"
552 Instead of dumping the actual content, the database is dumped as
553 JSON. For the format of JSON output see \f(CW\*(C`tlpkg/doc/json\-formats.txt\*(C'\fR,
554 format definition \f(CW\*(C`TLPDB\*(C'\fR.
555 .PP
556 Exactly one of \f(CW\*(C`\-\-local\*(C'\fR and \f(CW\*(C`\-\-remote\*(C'\fR must be given.
557 .PP
558 In either case, the first line of the output specifies the repository
559 location, in this format:
560 .PP
561 .Vb 1
562 \& "location\-url" "\et" location
563 .Ve
564 .PP
565 where \f(CW\*(C`location\-url\*(C'\fR is the literal field name, followed by a tab, and
566 \&\fIlocation\fR is the file or url to the repository.
567 .PP
568 Line endings may be either LF or CRLF depending on the current platform.
569 .SS generate
570 .IX Subsection "generate"
571 .IP "\fBgenerate [\fR\f(BIoption\fR\fB...] language\fR" 4
572 .IX Item "generate [option...] language"
573 .PD 0
574 .IP "\fBgenerate [\fR\f(BIoption\fR\fB...] language.dat\fR" 4
575 .IX Item "generate [option...] language.dat"
576 .IP "\fBgenerate [\fR\f(BIoption\fR\fB...] language.def\fR" 4
577 .IX Item "generate [option...] language.def"
578 .IP "\fBgenerate [\fR\f(BIoption\fR\fB...] language.dat.lua\fR" 4
579 .IX Item "generate [option...] language.dat.lua"
580 .PD
581 .PP
582 The \f(CW\*(C`generate\*(C'\fR action overwrites any manual changes made in the
583 respective files: it recreates them from scratch based on the
584 information of the installed packages, plus local adaptations.
585 The TeX Live installer and \f(CW\*(C`tlmgr\*(C'\fR routinely call \f(CW\*(C`generate\*(C'\fR for
586 all of these files.
587 .PP
588 For managing your own fonts, please read the \f(CW\*(C`updmap \-\-help\*(C'\fR
589 information and/or <https://tug.org/fonts/fontinstall.html>.
590 .PP
591 For managing your own formats, please read the \f(CW\*(C`fmtutil \-\-help\*(C'\fR
592 information.
593 .PP
594 In more detail: \f(CW\*(C`generate\*(C'\fR remakes any of the configuration files
595 \&\f(CW\*(C`language.dat\*(C'\fR, \f(CW\*(C`language.def\*(C'\fR, and \f(CW\*(C`language.dat.lua\*(C'\fR
596 from the information present in the local TLPDB, plus
597 locally\-maintained files.
598 .PP
599 The locally\-maintained files are \f(CW\*(C`language\-local.dat\*(C'\fR,
600 \&\f(CW\*(C`language\-local.def\*(C'\fR, or \f(CW\*(C`language\-local.dat.lua\*(C'\fR,
601 searched for in \f(CW\*(C`TEXMFLOCAL\*(C'\fR in the respective
602 directories. If local additions are present, the final file is made by
603 starting with the main file, omitting any entries that the local file
604 specifies to be disabled, and finally appending the local file.
605 .PP
606 (Historical note: The formerly supported \f(CW\*(C`updmap\-local.cfg\*(C'\fR and
607 \&\f(CW\*(C`fmtutil\-local.cnf\*(C'\fR are no longer read, since \f(CW\*(C`updmap\*(C'\fR and \f(CW\*(C`fmtutil\*(C'\fR
608 now reads and supports multiple configuration files. Thus,
609 local additions can and should be put into an \f(CW\*(C`updmap.cfg\*(C'\fR of \f(CW\*(C`fmtutil.cnf\*(C'\fR
610 file in \f(CW\*(C`TEXMFLOCAL\*(C'\fR. The \f(CW\*(C`generate updmap\*(C'\fR and \f(CW\*(C`generate fmtutil\*(C'\fR actions
611 no longer exist.)
612 .PP
613 Local files specify entries to be disabled with a comment line, namely
614 one of these:
615 .PP
616 .Vb 2
617 \& %!NAME
618 \& \-\-!NAME
619 .Ve
620 .PP
621 where \f(CW\*(C`language.dat\*(C'\fR and \f(CW\*(C`language.def\*(C'\fR use \f(CW\*(C`%\*(C'\fR,
622 and \f(CW\*(C`language.dat.lua\*(C'\fR use \f(CW\*(C`\-\-\*(C'\fR. In all cases, the \fIname\fR is
623 the respective format name or hyphenation pattern identifier.
624 Examples:
625 .PP
626 .Vb 2
627 \& %!german
628 \& \-\-!usenglishmax
629 .Ve
630 .PP
631 (Of course, you\*(Aqre not likely to actually want to disable those
632 particular items. They\*(Aqre just examples.)
633 .PP
634 After such a disabling line, the local file can include another entry
635 for the same item, if a different definition is desired. In general,
636 except for the special disabling lines, the local files follow the same
637 syntax as the master files.
638 .PP
639 The form \f(CW\*(C`generate language\*(C'\fR recreates all three files \f(CW\*(C`language.dat\*(C'\fR,
640 \&\f(CW\*(C`language.def\*(C'\fR, and \f(CW\*(C`language.dat.lua\*(C'\fR, while the forms with an
641 extension recreates only that given language file.
642 .PP
643 Options:
644 .IP "\fB\-\-dest\fR \fIoutput_file\fR" 4
645 .IX Item "--dest output_file"
646 specifies the output file (defaults to the respective location in
647 \&\f(CW\*(C`TEXMFSYSVAR\*(C'\fR). If \f(CW\*(C`\-\-dest\*(C'\fR is given to \f(CW\*(C`generate language\*(C'\fR, it
648 serves as a basename onto which \f(CW\*(C`.dat\*(C'\fR will be appended for the name of
649 the \f(CW\*(C`language.dat\*(C'\fR output file, \f(CW\*(C`.def\*(C'\fR will be appended to the value
650 for the name of the \f(CW\*(C`language.def\*(C'\fR output file, and \f(CW\*(C`.dat.lua\*(C'\fR to the
651 name of the \f(CW\*(C`language.dat.lua\*(C'\fR file. (This is just to avoid
652 overwriting; if you want a specific name for each output file, we
653 recommend invoking \f(CW\*(C`tlmgr\*(C'\fR twice.)
654 .IP "\fB\-\-localcfg\fR \fIlocal_conf_file\fR" 4
655 .IX Item "--localcfg local_conf_file"
656 specifies the (optional) local additions (defaults to the respective
657 location in \f(CW\*(C`TEXMFLOCAL\*(C'\fR).
658 .IP \fB\-\-rebuild\-sys\fR 4
659 .IX Item "--rebuild-sys"
660 tells \f(CW\*(C`tlmgr\*(C'\fR to run necessary programs after config files have been
661 regenerated. These are:
662 \&\f(CW\*(C`fmtutil\-sys \-\-all\*(C'\fR after \f(CW\*(C`generate fmtutil\*(C'\fR,
663 \&\f(CW\*(C`fmtutil\-sys \-\-byhyphen .../language.dat\*(C'\fR after \f(CW\*(C`generate language.dat\*(C'\fR,
664 and
665 \&\f(CW\*(C`fmtutil\-sys \-\-byhyphen .../language.def\*(C'\fR after \f(CW\*(C`generate language.def\*(C'\fR.
666 .Sp
667 These subsequent calls cause the newly\-generated files to actually take
668 effect. This is not done by default since those calls are lengthy
669 processes and one might want to made several related changes in
670 succession before invoking these programs.
671 .PP
672 The respective locations are as follows:
673 .PP
674 .Vb 3
675 \& tex/generic/config/language.dat (and language\-local.dat)
676 \& tex/generic/config/language.def (and language\-local.def)
677 \& tex/generic/config/language.dat.lua (and language\-local.dat.lua)
678 .Ve
679 .SS gui
680 .IX Subsection "gui"
681 Start the graphical user interface. See \fBGUI\fR below.
682 .SS info
683 .IX Subsection "info"
684 .IP "\fBinfo [\fR\f(BIoption\fR\fB...] \fR\f(BIpkg\fR\fB...\fR" 4
685 .IX Item "info [option...] pkg..."
686 .PD 0
687 .IP "\fBinfo [\fR\f(BIoption\fR\fB...] collections\fR" 4
688 .IX Item "info [option...] collections"
689 .IP "\fBinfo [\fR\f(BIoption\fR\fB...] schemes\fR" 4
690 .IX Item "info [option...] schemes"
691 .PD
692 With no argument, lists all packages available at the package
693 repository, prefixing those already installed with \f(CW\*(C`i\*(C'\fR.
694 .Sp
695 With the single word \f(CW\*(C`collections\*(C'\fR or \f(CW\*(C`schemes\*(C'\fR as the argument, lists
696 the request type instead of all packages.
697 .Sp
698 With any other arguments, display information about \fIpkg\fR: the name,
699 category, short and long description, sizes, installation status, and TeX Live
700 revision number. If \fIpkg\fR is not locally installed, searches in the
701 remote installation source.
702 .Sp
703 For normal packages (not collections or schemes), the sizes of the four
704 groups of files (run/src/doc/bin files) are shown separately. For
705 collections, the cumulative size is shown, including all
706 directly\-dependent packages (but not dependent collections). For
707 schemes, the cumulative size is also shown, including all
708 directly\-dependent collections and packages.
709 .Sp
710 If \fIpkg\fR is not found locally or remotely, the search action is used
711 and lists matching packages and files.
712 .Sp
713 It also displays information taken from the TeX Catalogue, namely the
714 package version, date, and license. Consider these, especially the
715 package version, as approximations only, due to timing skew of the
716 updates of the different pieces. By contrast, the \f(CW\*(C`revision\*(C'\fR value
717 comes directly from TL and is reliable.
718 .Sp
719 The former actions \f(CW\*(C`show\*(C'\fR and \f(CW\*(C`list\*(C'\fR are merged into this action,
720 but are still supported for backward compatibility.
721 .Sp
722 Options:
723 .RS 4
724 .IP \fB\-\-list\fR 4
725 .IX Item "--list"
726 If the option \f(CW\*(C`\-\-list\*(C'\fR is given with a package, the list of contained
727 files is also shown, including those for platform\-specific dependencies.
728 When given with schemes and collections, \f(CW\*(C`\-\-list\*(C'\fR outputs their
729 dependencies in a similar way.
730 .IP \fB\-\-only\-files\fR 4
731 .IX Item "--only-files"
732 If this option is given, only the files for a given package are listed,
733 no further information. If more than one package name is given, each
734 file list is preceded by the package name.
735 .IP \fB\-\-only\-installed\fR 4
736 .IX Item "--only-installed"
737 If this option is given, the installation source will not be used; only
738 locally installed packages, collections, or schemes are listed.
739 .IP \fB\-\-only\-remote\fR 4
740 .IX Item "--only-remote"
741 Only list packages from the remote repository. Useful when checking what
742 is available in a remote repository using
743 \&\f(CW\*(C`tlmgr \-\-repo ... \-\-only\-remote info\*(C'\fR. Note that
744 \&\f(CW\*(C`\-\-only\-installed\*(C'\fR and \f(CW\*(C`\-\-only\-remote\*(C'\fR cannot both be specified.
745 .ie n .IP "\fB\-\-data \fR\fB""item1,item2,...""\fR" 4
746 .el .IP "\fB\-\-data \fR\f(CBitem1,item2,...\fR" 4
747 .IX Item "--data item1,item2,..."
748 If the option \f(CW\*(C`\-\-data\*(C'\fR is given, its argument must be a comma or colon
749 separated list of field names from: \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`category\*(C'\fR, \f(CW\*(C`localrev\*(C'\fR,
750 \&\f(CW\*(C`remoterev\*(C'\fR, \f(CW\*(C`shortdesc\*(C'\fR, \f(CW\*(C`longdesc\*(C'\fR, \f(CW\*(C`installed\*(C'\fR, \f(CW\*(C`size\*(C'\fR,
751 \&\f(CW\*(C`relocatable\*(C'\fR, \f(CW\*(C`depends\*(C'\fR, \f(CW\*(C`cat\-version\*(C'\fR, \f(CW\*(C`cat\-date\*(C'\fR, \f(CW\*(C`cat\-license\*(C'\fR,
752 plus various \f(CW\*(C`cat\-contact\-*\*(C'\fR fields (see below).
753 .Sp
754 The \f(CW\*(C`cat\-*\*(C'\fR fields all come from the TeX Catalogue
755 (<https://ctan.org/pkg/catalogue>). For each, there are two more
756 variants with prefix \f(CW\*(C`l\*(C'\fR and \f(CW\*(C`r\*(C'\fR, e.g., \f(CW\*(C`lcat\-version\*(C'\fR and
757 \&\f(CW\*(C`rcat\-version\*(C'\fR, which indicate the local and remote information,
758 respectively. The variants without \f(CW\*(C`l\*(C'\fR and \f(CW\*(C`r\*(C'\fR show the most current
759 one, which is normally the remote value.
760 .Sp
761 The requested packages\*(Aq information is listed in CSV format, one package
762 per line, and the column information is given by the \f(CW\*(C`itemN\*(C'\fR. The
763 \&\f(CW\*(C`depends\*(C'\fR column contains the names of all the dependencies separated
764 by \f(CW\*(C`:\*(C'\fR characters.
765 .Sp
766 At this writing, the \f(CW\*(C`cat\-contact\-*\*(C'\fR fields include: \f(CW\*(C`home\*(C'\fR,
767 \&\f(CW\*(C`repository\*(C'\fR, \f(CW\*(C`support\*(C'\fR, \f(CW\*(C`bugs\*(C'\fR, \f(CW\*(C`announce\*(C'\fR, \f(CW\*(C`development\*(C'\fR. Each
768 may be empty or a url value. A brief description is on the CTAN upload
769 page for new packages: <https://ctan.org/upload>.
770 .IP \fB\-\-json\fR 4
771 .IX Item "--json"
772 If \f(CW\*(C`\-\-json\*(C'\fR is specified, the output is a JSON encoded array where each
773 array element is the JSON representation of a single \f(CW\*(C`TLPOBJ\*(C'\fR but with
774 additional information. For details see \f(CW\*(C`tlpkg/doc/json\-formats.txt\*(C'\fR,
775 format definition: \f(CW\*(C`TLPOBJINFO\*(C'\fR. If both \f(CW\*(C`\-\-json\*(C'\fR and \f(CW\*(C`\-\-data\*(C'\fR are
776 given, \f(CW\*(C`\-\-json\*(C'\fR takes precedence.
777 .RE
778 .RS 4
779 .RE
780 .SS init\-usertree
781 .IX Subsection "init-usertree"
782 Sets up a texmf tree for so\-called user mode management, either the
783 default user tree (\f(CW\*(C`TEXMFHOME\*(C'\fR), or one specified on the command line
784 with \f(CW\*(C`\-\-usertree\*(C'\fR. See "USER MODE" below.
785 .SS "install [\fIoption\fP...] \fIpkg\fP..."
786 .IX Subsection "install [option...] pkg..."
787 Install each \fIpkg\fR given on the command line, if it is not already
788 installed. It does not touch existing packages; see the \f(CW\*(C`update\*(C'\fR
789 action for how to get the latest version of a package.
790 .PP
791 By default this also installs all packages on which the given \fIpkg\fRs are
792 dependent. Options:
793 .IP \fB\-\-dry\-run\fR 4
794 .IX Item "--dry-run"
795 Nothing is actually installed; instead, the actions to be performed are
796 written to the terminal.
797 .IP \fB\-\-file\fR 4
798 .IX Item "--file"
799 Instead of fetching a package from the installation repository, use
800 the package files given on the command line. These files must
801 be standard TeX Live package files (with contained tlpobj file).
802 .IP \fB\-\-force\fR 4
803 .IX Item "--force"
804 If updates to \f(CW\*(C`tlmgr\*(C'\fR itself (or other parts of the basic
805 infrastructure) are present, \f(CW\*(C`tlmgr\*(C'\fR will bail out and not perform the
806 installation unless this option is given. Not recommended.
807 .IP \fB\-\-no\-depends\fR 4
808 .IX Item "--no-depends"
809 Do not install dependencies. (By default, installing a package ensures
810 that all dependencies of this package are fulfilled.)
811 .IP \fB\-\-no\-depends\-at\-all\fR 4
812 .IX Item "--no-depends-at-all"
813 Normally, when you install a package which ships binary files the
814 respective binary package will also be installed. That is, for a
815 package \f(CW\*(C`foo\*(C'\fR, the package \f(CW\*(C`foo.i386\-linux\*(C'\fR will also be installed on
816 an \f(CW\*(C`i386\-linux\*(C'\fR system. This option suppresses this behavior, and also
817 implies \f(CW\*(C`\-\-no\-depends\*(C'\fR. Don\*(Aqt use it unless you are sure of what you
818 are doing.
819 .IP \fB\-\-reinstall\fR 4
820 .IX Item "--reinstall"
821 Reinstall a package (including dependencies for collections) even if it
822 already seems to be installed (i.e, is present in the TLPDB). This is
823 useful to recover from accidental removal of files in the hierarchy.
824 .Sp
825 When re\-installing, only dependencies on normal packages are followed
826 (i.e., not those of category Scheme or Collection).
827 .IP \fB\-\-with\-doc\fR 4
828 .IX Item "--with-doc"
829 .PD 0
830 .IP \fB\-\-with\-src\fR 4
831 .IX Item "--with-src"
832 .PD
833 While not recommended, the \f(CW\*(C`install\-tl\*(C'\fR program provides an option to
834 omit installation of all documentation and/or source files. (By
835 default, everything is installed.) After such an installation, you may
836 find that you want the documentation or source files for a given package
837 after all. You can get them by using these options in conjunction with
838 \&\f(CW\*(C`\-\-reinstall\*(C'\fR, as in (using the \f(CW\*(C`fontspec\*(C'\fR package as the example):
839 .Sp
840 .Vb 1
841 \& tlmgr install \-\-reinstall \-\-with\-doc \-\-with\-src fontspec
842 .Ve
843 .PP
844 This action does not automatically add new symlinks in system
845 directories; you need to run \f(CW\*(C`tlmgr path add\*(C'\fR ("path") yourself if
846 you are using this feature and want new symlinks added.
847 .SS key
848 .IX Subsection "key"
849 .IP "\fBkey list\fR" 4
850 .IX Item "key list"
851 .PD 0
852 .IP "\fBkey add \fR\f(BIfile\fR" 4
853 .IX Item "key add file"
854 .IP "\fBkey remove \fR\f(BIkeyid\fR" 4
855 .IX Item "key remove keyid"
856 .PD
857 The action \f(CW\*(C`key\*(C'\fR allows listing, adding and removing additional GPG
858 keys to the set of trusted keys, that is, those that are used to verify
859 the TeX Live databases.
860 .Sp
861 With the \f(CW\*(C`list\*(C'\fR argument, \f(CW\*(C`key\*(C'\fR lists all keys.
862 .Sp
863 The \f(CW\*(C`add\*(C'\fR argument requires another argument, either a filename or
864 \&\f(CW\*(C`\-\*(C'\fR for stdin, from which the key is added. The key is added to the
865 local keyring \f(CW\*(C`GNUPGHOME/repository\-keys.gpg\*(C'\fR, which is normally
866 \&\f(CW\*(C`tlpkg/gpg/repository\-keys.gpg\*(C'\fR.
867 .Sp
868 The \f(CW\*(C`remove\*(C'\fR argument requires a key id and removes the requested id
869 from the local keyring.
870 .SS list
871 .IX Subsection "list"
872 Synonym for "info".
873 .SS option
874 .IX Subsection "option"
875 .IP "\fBoption [\-\-json] [show]\fR" 4
876 .IX Item "option [--json] [show]"
877 .PD 0
878 .IP "\fBoption [\-\-json] showall|help\fR" 4
879 .IX Item "option [--json] showall|help"
880 .IP "\fBoption \fR\f(BIkey\fR\fB [\fR\f(BIvalue\fR\fB]\fR" 4
881 .IX Item "option key [value]"
882 .PD
883 .PP
884 The first form, \f(CW\*(C`show\*(C'\fR, shows the global TeX Live settings currently
885 saved in the TLPDB with a short description and the \f(CW\*(C`key\*(C'\fR used for
886 changing it in parentheses.
887 .PP
888 The second form, \f(CW\*(C`showall\*(C'\fR, is similar, but also shows options which
889 can be defined but are not currently set to any value (\f(CW\*(C`help\*(C'\fR is a
890 synonym).
891 .PP
892 Both \f(CW\*(C`show...\*(C'\fR forms take an option \f(CW\*(C`\-\-json\*(C'\fR, which dumps the option
893 information in JSON format. In this case, both forms dump the same
894 data. For the format of the JSON output see
895 \&\f(CW\*(C`tlpkg/doc/json\-formats.txt\*(C'\fR, format definition \f(CW\*(C`TLOPTION\*(C'\fR.
896 .PP
897 In the third form, with \fIkey\fR, if \fIvalue\fR is not given, the setting
898 for \fIkey\fR is displayed. If \fIvalue\fR is present, \fIkey\fR is set to
899 \&\fIvalue\fR.
900 .PP
901 Possible values for \fIkey\fR are (run \f(CW\*(C`tlmgr option showall\*(C'\fR for
902 the definitive list):
903 .PP
904 .Vb 10
905 \& repository (default package repository),
906 \& formats (generate formats at installation or update time),
907 \& postcode (run postinst code blobs)
908 \& docfiles (install documentation files),
909 \& srcfiles (install source files),
910 \& backupdir (default directory for backups),
911 \& autobackup (number of backups to keep).
912 \& sys_bin (directory to which executables are linked by the path action)
913 \& sys_man (directory to which man pages are linked by the path action)
914 \& sys_info (directory to which Info files are linked by the path action)
915 \& desktop_integration (Windows\-only: create Start menu shortcuts)
916 \& fileassocs (Windows\-only: change file associations)
917 \& multiuser (Windows\-only: install for all users)
918 .Ve
919 .PP
920 One common use of \f(CW\*(C`option\*(C'\fR is to permanently change the installation to
921 get further updates from the Internet, after originally installing from
922 DVD. To do this, you can run
923 .PP
924 .Vb 1
925 \& tlmgr option repository https://mirror.ctan.org/systems/texlive/tlnet
926 .Ve
927 .PP
928 The \f(CW\*(C`install\-tl\*(C'\fR documentation has more information about the possible
929 values for \f(CW\*(C`repository\*(C'\fR. (For backward compatibility, \f(CW\*(C`location\*(C'\fR can
930 be used as a synonym for \f(CW\*(C`repository\*(C'\fR.)
931 .PP
932 If \f(CW\*(C`formats\*(C'\fR is set (this is the default), then formats are regenerated
933 when either the engine or the format files have changed. Disable this
934 only when you know how and want to regenerate formats yourself whenever
935 needed (which is often, in practice).
936 .PP
937 The \f(CW\*(C`postcode\*(C'\fR option controls execution of per\-package
938 postinstallation action code. It is set by default, and again disabling
939 is not likely to be of interest except to developers doing debugging.
940 .PP
941 The \f(CW\*(C`docfiles\*(C'\fR and \f(CW\*(C`srcfiles\*(C'\fR options control the installation of
942 their respective file groups (documentation, sources; grouping is
943 approximate) per package. By default both are enabled (1). Either or
944 both can be disabled (set to 0) if disk space is limited or for minimal
945 testing installations, etc. When disabled, the respective files are not
946 downloaded at all.
947 .PP
948 The options \f(CW\*(C`autobackup\*(C'\fR and \f(CW\*(C`backupdir\*(C'\fR determine the defaults for
949 the actions \f(CW\*(C`update\*(C'\fR, \f(CW\*(C`backup\*(C'\fR and \f(CW\*(C`restore\*(C'\fR. These three actions
950 need a directory in which to read or write the backups. If
951 \&\f(CW\*(C`\-\-backupdir\*(C'\fR is not specified on the command line, the \f(CW\*(C`backupdir\*(C'\fR
952 option value is used (if set). The TL installer sets \f(CW\*(C`backupdir\*(C'\fR to
953 \&\f(CW\*(C`.../tlpkg/backups\*(C'\fR, under the TL root installation directory.
954 .PP
955 The \f(CW\*(C`autobackup\*(C'\fR option (de)activates automatic generation of backups.
956 Its value is an integer. If the \f(CW\*(C`autobackup\*(C'\fR value is \f(CW\-1\fR, no
957 backups are removed. If \f(CW\*(C`autobackup\*(C'\fR is 0 or more, it specifies the
958 number of backups to keep. Thus, backups are disabled if the value is
959 0. In the \f(CW\*(C`\-\-clean\*(C'\fR mode of the \f(CW\*(C`backup\*(C'\fR action this option also
960 specifies the number to be kept. The default value is 1, so that
961 backups are made, but only one backup is kept.
962 .PP
963 To setup \f(CW\*(C`autobackup\*(C'\fR to \f(CW\-1\fR on the command line, use:
964 .PP
965 .Vb 1
966 \& tlmgr option \-\- autobackup \-1
967 .Ve
968 .PP
969 The \f(CW\*(C`\-\-\*(C'\fR avoids having the \f(CW\-1\fR treated as an option. (The \f(CW\*(C`\-\-\*(C'\fR
970 stops parsing for options at the point where it appears; this is a
971 general feature across most Unix programs.)
972 .PP
973 The \f(CW\*(C`sys_bin\*(C'\fR, \f(CW\*(C`sys_man\*(C'\fR, and \f(CW\*(C`sys_info\*(C'\fR options are used on Unix
974 systems to control the generation of links for executables, Info files
975 and man pages. See the \f(CW\*(C`path\*(C'\fR action for details.
976 .PP
977 The last three options affect behavior on Windows installations. If
978 \&\f(CW\*(C`desktop_integration\*(C'\fR is set, then some packages will install items in
979 a sub\-folder of the Start menu for \f(CW\*(C`tlmgr gui\*(C'\fR, documentation, etc. If
980 \&\f(CW\*(C`fileassocs\*(C'\fR is set, Windows file associations are made (see also the
981 \&\f(CW\*(C`postaction\*(C'\fR action). Finally, if \f(CW\*(C`multiuser\*(C'\fR is set, then changes
982 to the registry and the menus are done for all users on the system
983 instead of only the current user. All three options are on by default.
984 .SS paper
985 .IX Subsection "paper"
986 .IP "\fBpaper [a4|letter]\fR" 4
987 .IX Item "paper [a4|letter]"
988 .PD 0
989 .IP "\fB<[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [\fR\f(BIpapersize\fR\fB|\-\-list]\fR>" 4
990 .IX Item "<[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [papersize|--list]>"
991 .IP "\fBpaper \-\-json\fR" 4
992 .IX Item "paper --json"
993 .PD
994 .PP
995 With no arguments (\f(CW\*(C`tlmgr paper\*(C'\fR), shows the default paper size setting
996 for all known programs.
997 .PP
998 With one argument (e.g., \f(CW\*(C`tlmgr paper a4\*(C'\fR), sets the default for all
999 known programs to that paper size.
1000 .PP
1001 With a program given as the first argument and no paper size specified
1002 (e.g., \f(CW\*(C`tlmgr dvips paper\*(C'\fR), shows the default paper size for that
1003 program.
1004 .PP
1005 With a program given as the first argument and a paper size as the last
1006 argument (e.g., \f(CW\*(C`tlmgr dvips paper a4\*(C'\fR), set the default for that
1007 program to that paper size.
1008 .PP
1009 If either \f(CW\*(C`pdftex\*(C'\fR or \f(CW\*(C`context\*(C'\fR is one of the arguments, whether
1010 implicitly or explicitly, existing formats are rebuilt (i.e., \f(CW\*(C`fmtutil
1011 \&\-\-refresh\*(C'\fR is called), unless \f(CW\*(C`\-\-no\-execute\-actions\*(C'\fR is specified.
1012 .PP
1013 With a program given as the first argument and \f(CW\*(C`\-\-list\*(C'\fR given as the
1014 last argument (e.g., \f(CW\*(C`tlmgr dvips paper \-\-list\*(C'\fR), shows all valid paper
1015 sizes for that program. The first size shown is the default.
1016 .PP
1017 If \f(CW\*(C`\-\-json\*(C'\fR is specified without other options, the paper setup is
1018 dumped in JSON format. For the format of JSON output see
1019 \&\f(CW\*(C`tlpkg/doc/json\-formats.txt\*(C'\fR, format definition \f(CW\*(C`TLPAPER\*(C'\fR.
1020 .PP
1021 Incidentally, this syntax of having a specific program name before the
1022 \&\f(CW\*(C`paper\*(C'\fR keyword is unusual. It is inherited from the longstanding
1023 \&\f(CW\*(C`texconfig\*(C'\fR script, which supports other configuration settings for
1024 some programs, notably \f(CW\*(C`dvips\*(C'\fR. \f(CW\*(C`tlmgr\*(C'\fR does not support those extra
1025 settings.
1026 .SS path
1027 .IX Subsection "path"
1028 .IP "\fBpath [\-\-windowsmode=user|admin] add\fR" 4
1029 .IX Item "path [--windowsmode=user|admin] add"
1030 .PD 0
1031 .IP "\fBpath [\-\-windowsmode=user|admin] remove\fR" 4
1032 .IX Item "path [--windowsmode=user|admin] remove"
1033 .PD
1034 On Unix, adds or removes symlinks for executables, man pages, and info
1035 pages in the system directories specified by the respective options (see
1036 the "option" description above). Does not change any initialization
1037 files, either system or personal. Furthermore, any executables added or
1038 removed by future updates are not taken care of automatically; this
1039 command must be rerun as needed.
1040 .Sp
1041 On Windows, the registry part where the binary directory is added or
1042 removed is determined in the following way:
1043 .Sp
1044 If the user has admin rights, and the option \f(CW\*(C`\-\-windowsmode\*(C'\fR is not given,
1045 the setting \fIw32_multi_user\fR determines the location (i.e., if it is
1046 on then the system path, otherwise the user path is changed).
1047 .Sp
1048 If the user has admin rights, and the option \f(CW\*(C`\-\-windowsmode\*(C'\fR is given, this
1049 option determines the path to be adjusted.
1050 .Sp
1051 If the user does not have admin rights, and the option \f(CW\*(C`\-\-windowsmode\*(C'\fR
1052 is not given, and the setting \fIw32_multi_user\fR is off, the user path
1053 is changed, while if the setting \fIw32_multi_user\fR is on, a warning is
1054 issued that the caller does not have enough privileges.
1055 .Sp
1056 If the user does not have admin rights, and the option \f(CW\*(C`\-\-windowsmode\*(C'\fR
1057 is given, it must be \f(CW\*(C`user\*(C'\fR and the user path will be adjusted. If a
1058 user without admin rights uses the option \f(CW\*(C`\-\-windowsmode admin\*(C'\fR a warning
1059 is issued that the caller does not have enough privileges.
1060 .SS pinning
1061 .IX Subsection "pinning"
1062 The \f(CW\*(C`pinning\*(C'\fR action manages the pinning file, see "Pinning" below.
1063 .ie n .IP """pinning show""" 4
1064 .el .IP "\f(CWpinning show\fR" 4
1065 .IX Item "pinning show"
1066 Shows the current pinning data.
1067 .ie n .IP """pinning add"" \fIrepo\fR \fIpkgglob\fR..." 4
1068 .el .IP "\f(CWpinning add\fR \fIrepo\fR \fIpkgglob\fR..." 4
1069 .IX Item "pinning add repo pkgglob..."
1070 Pins the packages matching the \fIpkgglob\fR(s) to the repository
1071 \&\fIrepo\fR.
1072 .ie n .IP """pinning remove"" \fIrepo\fR \fIpkgglob\fR..." 4
1073 .el .IP "\f(CWpinning remove\fR \fIrepo\fR \fIpkgglob\fR..." 4
1074 .IX Item "pinning remove repo pkgglob..."
1075 Any packages recorded in the pinning file matching the <pkgglob>s for
1076 the given repository \fIrepo\fR are removed.
1077 .ie n .IP """pinning remove \fIrepo\fR \-\-all""" 4
1078 .el .IP "\f(CWpinning remove \fR\f(CIrepo\fR\f(CW \-\-all\fR" 4
1079 .IX Item "pinning remove repo --all"
1080 Remove all pinning data for repository \fIrepo\fR.
1081 .SS platform
1082 .IX Subsection "platform"
1083 .IP "\fBplatform list|add|remove \fR\f(BIplatform\fR\fB...\fR" 4
1084 .IX Item "platform list|add|remove platform..."
1085 .PD 0
1086 .IP "\fBplatform set \fR\f(BIplatform\fR" 4
1087 .IX Item "platform set platform"
1088 .IP "\fBplatform set auto\fR" 4
1089 .IX Item "platform set auto"
1090 .PD
1091 \&\f(CW\*(C`platform list\*(C'\fR lists the TeX Live names of all the platforms
1092 (a.k.a. architectures), (\f(CW\*(C`i386\-linux\*(C'\fR, ...) available at the package
1093 repository.
1094 .Sp
1095 \&\f(CW\*(C`platform add\*(C'\fR \fIplatform\fR... adds the executables for each given platform
1096 \&\fIplatform\fR to the installation from the repository.
1097 .Sp
1098 \&\f(CW\*(C`platform remove\*(C'\fR \fIplatform\fR... removes the executables for each given
1099 platform \fIplatform\fR from the installation, but keeps the currently
1100 running platform in any case.
1101 .Sp
1102 \&\f(CW\*(C`platform set\*(C'\fR \fIplatform\fR switches TeX Live to always use the given
1103 platform instead of auto detection.
1104 .Sp
1105 \&\f(CW\*(C`platform set auto\*(C'\fR switches TeX Live to auto detection mode for platform.
1106 .Sp
1107 Platform detection is needed to select the proper \f(CW\*(C`xz\*(C'\fR and
1108 \&\f(CW\*(C`wget\*(C'\fR binaries that are shipped with TeX Live.
1109 .Sp
1110 \&\f(CW\*(C`arch\*(C'\fR is a synonym for \f(CW\*(C`platform\*(C'\fR.
1111 .Sp
1112 Options:
1113 .RS 4
1114 .IP \fB\-\-dry\-run\fR 4
1115 .IX Item "--dry-run"
1116 Nothing is actually installed; instead, the actions to be performed are
1117 written to the terminal.
1118 .RE
1119 .RS 4
1120 .RE
1121 .SS postaction
1122 .IX Subsection "postaction"
1123 .IP "\fBpostaction [\fR\f(BIoption\fR\fB...] install [shortcut|fileassoc|script] [\fR\f(BIpkg\fR\fB...]\fR" 4
1124 .IX Item "postaction [option...] install [shortcut|fileassoc|script] [pkg...]"
1125 .PD 0
1126 .IP "\fBpostaction [\fR\f(BIoption\fR\fB...] remove [shortcut|fileassoc|script] [\fR\f(BIpkg\fR\fB...]\fR" 4
1127 .IX Item "postaction [option...] remove [shortcut|fileassoc|script] [pkg...]"
1128 .PD
1129 Carry out the postaction \f(CW\*(C`shortcut\*(C'\fR, \f(CW\*(C`fileassoc\*(C'\fR, or \f(CW\*(C`script\*(C'\fR given
1130 as the second required argument in install or remove mode (which is the
1131 first required argument), for either the packages given on the command
1132 line, or for all if \f(CW\*(C`\-\-all\*(C'\fR is given.
1133 .Sp
1134 Options:
1135 .RS 4
1136 .IP \fB\-\-windowsmode=[user|admin]\fR 4
1137 .IX Item "--windowsmode=[user|admin]"
1138 If the option \f(CW\*(C`\-\-windowsmode\*(C'\fR is given the value \f(CW\*(C`user\*(C'\fR, all actions will
1139 only be carried out in the user\-accessible parts of the
1140 registry/filesystem, while the value \f(CW\*(C`admin\*(C'\fR selects the system\-wide
1141 parts of the registry for the file associations. If you do not have
1142 enough permissions, using \f(CW\*(C`\-\-windowsmode=admin\*(C'\fR will not succeed.
1143 .IP \fB\-\-fileassocmode=[1|2]\fR 4
1144 .IX Item "--fileassocmode=[1|2]"
1145 \&\f(CW\*(C`\-\-fileassocmode\*(C'\fR specifies the action for file associations. If it is
1146 set to 1 (the default), only new associations are added; if it is set to
1147 2, all associations are set to the TeX Live programs. (See also
1148 \&\f(CW\*(C`option fileassocs\*(C'\fR.)
1149 .IP \fB\-\-all\fR 4
1150 .IX Item "--all"
1151 Carry out the postactions for all packages
1152 .RE
1153 .RS 4
1154 .RE
1155 .SS print\-platform
1156 .IX Subsection "print-platform"
1157 Print the TeX Live identifier for the detected platform
1158 (hardware/operating system) combination to standard output, and exit.
1159 \&\f(CW\*(C`\-\-print\-arch\*(C'\fR is a synonym.
1160 .SS print\-platform\-info
1161 .IX Subsection "print-platform-info"
1162 Print the TeX Live platform identifier, TL platform long name, and
1163 original output from guess.
1164 .SS "remove [\fIoption\fP...] \fIpkg\fP..."
1165 .IX Subsection "remove [option...] pkg..."
1166 Remove each \fIpkg\fR specified. Removing a collection removes all package
1167 dependencies (unless \f(CW\*(C`\-\-no\-depends\*(C'\fR is specified), but not any
1168 collection dependencies of that collection. However, when removing a
1169 package, dependencies are never removed. Options:
1170 .IP \fB\-\-all\fR 4
1171 .IX Item "--all"
1172 Uninstalls all of TeX Live, asking for confirmation unless \f(CW\*(C`\-\-force\*(C'\fR is
1173 also specified.
1174 .IP \fB\-\-backup\fR 4
1175 .IX Item "--backup"
1176 .PD 0
1177 .IP "\fB\-\-backupdir\fR \fIdirectory\fR" 4
1178 .IX Item "--backupdir directory"
1179 .PD
1180 These options behave just as with the update action (q.v.), except they apply to making
1181 backups of packages before they are removed. The default is to make
1182 such a backup, that is, to save a copy of packages before removal.
1183 .Sp
1184 The "restore" action explains how to restore from a backup.
1185 .IP \fB\-\-no\-depends\fR 4
1186 .IX Item "--no-depends"
1187 Do not remove dependent packages.
1188 .IP \fB\-\-no\-depends\-at\-all\fR 4
1189 .IX Item "--no-depends-at-all"
1190 See above under install (and beware).
1191 .IP \fB\-\-force\fR 4
1192 .IX Item "--force"
1193 By default, removal of a package or collection that is a dependency of
1194 another collection or scheme is not allowed. With this option, the
1195 package will be removed unconditionally. Use with care.
1196 .Sp
1197 A package that has been removed using the \f(CW\*(C`\-\-force\*(C'\fR option because it
1198 is still listed in an installed collection or scheme will not be
1199 updated, and will be mentioned as \f(CW\*(C`forcibly removed\*(C'\fR in the output of
1200 \&\f(CW\*(C`tlmgr update \-\-list\*(C'\fR.
1201 .IP \fB\-\-dry\-run\fR 4
1202 .IX Item "--dry-run"
1203 Nothing is actually removed; instead, the actions to be performed are
1204 written to the terminal.
1205 .PP
1206 Except with \f(CW\*(C`\-\-all\*(C'\fR, this \f(CW\*(C`remove\*(C'\fR action does not automatically
1207 remove symlinks to executables from system directories; you need to run
1208 \&\f(CW\*(C`tlmgr path remove\*(C'\fR ("path") yourself if you remove an individual
1209 package with a symlink in a system directory.
1210 .SS repository
1211 .IX Subsection "repository"
1212 .IP "\fBrepository list\fR" 4
1213 .IX Item "repository list"
1214 .PD 0
1215 .IP "\fBrepository list \fR\f(BIpath|url|tag\fR" 4
1216 .IX Item "repository list path|url|tag"
1217 .IP "\fBrepository add \fR\f(BIpath\fR\fB [\fR\f(BItag\fR\fB]\fR" 4
1218 .IX Item "repository add path [tag]"
1219 .IP "\fBrepository remove \fR\f(BIpath|tag\fR" 4
1220 .IX Item "repository remove path|tag"
1221 .IP "\fBrepository set \fR\f(BIpath\fR\fB[#\fR\f(BItag\fR\fB] [\fR\f(BIpath\fR\fB[#\fR\f(BItag\fR\fB] ...]\fR" 4
1222 .IX Item "repository set path[#tag] [path[#tag] ...]"
1223 .IP "\fBrepository status\fR" 4
1224 .IX Item "repository status"
1225 .PD
1226 This action manages the list of repositories. See MULTIPLE
1227 REPOSITORIES below for detailed explanations.
1228 .Sp
1229 The first form, \f(CW\*(C`repository list\*(C'\fR, lists all configured repositories
1230 and the respective tags if set. If a path, url, or tag is given after
1231 the \f(CW\*(C`list\*(C'\fR keyword, it is interpreted as the source from which to
1232 initialize a TL database and lists the contained packages. This can also
1233 be an otherwise\-unused repository, either local or remote. If the option
1234 \&\f(CW\*(C`\-\-with\-platforms\*(C'\fR is specified in addition, for each package the
1235 available platforms (if any) are also listed.
1236 .Sp
1237 The form \f(CW\*(C`repository add\*(C'\fR adds a repository (optionally attaching a
1238 tag) to the list of repositories, while \f(CW\*(C`repository remove\*(C'\fR removes a
1239 repository, either by full path/url, or by tag.
1240 .Sp
1241 The form \f(CW\*(C`repository set\*(C'\fR sets the list of available repositories to
1242 the items given on the command line, overwriting previous settings.
1243 .Sp
1244 The form \f(CW\*(C`repository status\*(C'\fR reports the verification status of the
1245 loaded repositories with the format of one repository per line
1246 with fields separated by a single space:
1247 .RS 4
1248 .IP "The tag (which can be the same as the url);" 4
1249 .IX Item "The tag (which can be the same as the url);"
1250 = the url;
1251 .Sp
1252 = iff machine\-readable output is specified, the verification code (a
1253 number);
1254 .Sp
1255 = a textual description of the verification status, as the last field
1256 extending to the end of line.
1257 .RE
1258 .RS 4
1259 .Sp
1260 That is, in normal (not machine\-readable) output, the third field
1261 (numeric verification status) is not present.
1262 .Sp
1263 In all cases, one of the repositories must be tagged as \f(CW\*(C`main\*(C'\fR;
1264 otherwise, all operations will fail!
1265 .RE
1266 .SS restore
1267 .IX Subsection "restore"
1268 .IP "\fBrestore [\fR\f(BIoption\fR\fB...] \fR\f(BIpkg\fR\fB [\fR\f(BIrev\fR\fB]\fR" 4
1269 .IX Item "restore [option...] pkg [rev]"
1270 .PD 0
1271 .IP "\fBrestore [\fR\f(BIoption\fR\fB...] \-\-all\fR" 4
1272 .IX Item "restore [option...] --all"
1273 .PD
1274 Restore a package from a previously\-made backup.
1275 .Sp
1276 If \f(CW\*(C`\-\-all\*(C'\fR is given, try to restore the latest revision of all
1277 package backups found in the backup directory.
1278 .Sp
1279 Otherwise, if neither \fIpkg\fR nor \fIrev\fR are given, list the available
1280 backup revisions for all packages. With \fIpkg\fR given but no \fIrev\fR,
1281 list all available backup revisions of \fIpkg\fR.
1282 .Sp
1283 When listing available packages, \f(CW\*(C`tlmgr\*(C'\fR shows the revision, and in
1284 parenthesis the creation time if available (in format yyyy\-mm\-dd hh:mm).
1285 .Sp
1286 If (and only if) both \fIpkg\fR and a valid revision number \fIrev\fR are
1287 specified, try to restore the package from the specified backup.
1288 .Sp
1289 Options:
1290 .RS 4
1291 .IP \fB\-\-all\fR 4
1292 .IX Item "--all"
1293 Try to restore the latest revision of all package backups found in the
1294 backup directory. Additional non\-option arguments (like \fIpkg\fR) are not
1295 allowed.
1296 .IP "\fB\-\-backupdir\fR \fIdirectory\fR" 4
1297 .IX Item "--backupdir directory"
1298 Specify the directory where the backups are to be found. If not given it
1299 will be taken from the configuration setting in the TLPDB.
1300 .IP \fB\-\-dry\-run\fR 4
1301 .IX Item "--dry-run"
1302 Nothing is actually restored; instead, the actions to be performed are
1303 written to the terminal.
1304 .IP \fB\-\-force\fR 4
1305 .IX Item "--force"
1306 Don\*(Aqt ask questions.
1307 .IP \fB\-\-json\fR 4
1308 .IX Item "--json"
1309 When listing backups, the option \f(CW\*(C`\-\-json\*(C'\fR writes JSON output. The
1310 format is an array of JSON objects (\f(CW\*(C`name\*(C'\fR, \f(CW\*(C`rev\*(C'\fR, \f(CW\*(C`date\*(C'\fR). For
1311 details see \f(CW\*(C`tlpkg/doc/json\-formats.txt\*(C'\fR, format definition:
1312 \&\f(CW\*(C`TLBACKUPS\*(C'\fR. If both \f(CW\*(C`\-\-json\*(C'\fR and \f(CW\*(C`\-\-data\*(C'\fR are given, \f(CW\*(C`\-\-json\*(C'\fR takes
1313 precedence.
1314 .RE
1315 .RS 4
1316 .RE
1317 .SS search
1318 .IX Subsection "search"
1319 .IP "\fBsearch [\fR\f(BIoption\fR\fB...] \fR\f(BIwhat\fR" 4
1320 .IX Item "search [option...] what"
1321 .PD 0
1322 .IP "\fBsearch [\fR\f(BIoption\fR\fB...] \-\-file \fR\f(BIwhat\fR" 4
1323 .IX Item "search [option...] --file what"
1324 .IP "\fBsearch [\fR\f(BIoption\fR\fB...] \-\-all \fR\f(BIwhat\fR" 4
1325 .IX Item "search [option...] --all what"
1326 .PD
1327 By default, search the names, short descriptions, and long descriptions
1328 of all locally installed packages for the argument \fIwhat\fR, interpreted
1329 as a (Perl) regular expression.
1330 .Sp
1331 Options:
1332 .RS 4
1333 .IP \fB\-\-file\fR 4
1334 .IX Item "--file"
1335 List all filenames containing \fIwhat\fR.
1336 .IP \fB\-\-all\fR 4
1337 .IX Item "--all"
1338 Search everything: package names, descriptions and filenames.
1339 .IP \fB\-\-global\fR 4
1340 .IX Item "--global"
1341 Search the TeX Live Database of the installation medium, instead of the
1342 local installation.
1343 .IP \fB\-\-word\fR 4
1344 .IX Item "--word"
1345 Restrict the search of package names and descriptions (but not
1346 filenames) to match only full words. For example, searching for
1347 \&\f(CW\*(C`table\*(C'\fR with this option will not output packages containing the word
1348 \&\f(CW\*(C`tables\*(C'\fR (unless they also contain the word \f(CW\*(C`table\*(C'\fR on its own).
1349 .IP \fB\-\-json\fR 4
1350 .IX Item "--json"
1351 Output search results as a JSON hash with two keys: \fBfiles\fR and
1352 \&\fBpackages\fR. For the format of the JSON output see
1353 \&\f(CW\*(C`tlpkg/doc/json\-formats.txt\*(C'\fR, format definition \f(CW\*(C`TLSEARCH\*(C'\fR.
1354 .RE
1355 .RS 4
1356 .RE
1357 .SS shell
1358 .IX Subsection "shell"
1359 Starts an interactive mode, where tlmgr prompts for commands. This can
1360 be used directly, or for scripting. The first line of output is
1361 \&\f(CW\*(C`protocol\*(C'\fR \fIn\fR, where \fIn\fR is an unsigned number identifying the
1362 protocol version (currently 1).
1363 .PP
1364 In general, tlmgr actions that can be given on the command line
1365 translate to commands in this shell mode. For example, you can say
1366 \&\f(CW\*(C`update \-\-list\*(C'\fR to see what would be updated. The TLPDB is loaded the
1367 first time it is needed (not at the beginning), and used for the rest of
1368 the session.
1369 .PP
1370 Besides these actions, a few commands are specific to shell mode:
1371 .IP protocol 4
1372 .IX Item "protocol"
1373 Print \f(CW\*(C`protocol \fR\f(CIn\fR\f(CW\*(C'\fR, the current protocol version.
1374 .IP help 4
1375 .IX Item "help"
1376 Print pointers to this documentation.
1377 .IP version 4
1378 .IX Item "version"
1379 Print tlmgr version information.
1380 .IP "quit, end, bye, byebye, EOF" 4
1381 .IX Item "quit, end, bye, byebye, EOF"
1382 Exit.
1383 .IP restart 4
1384 .IX Item "restart"
1385 Restart \f(CW\*(C`tlmgr shell\*(C'\fR with the original command line; most useful when
1386 developing \f(CW\*(C`tlmgr\*(C'\fR.
1387 .IP "load [local|remote]" 4
1388 .IX Item "load [local|remote]"
1389 Explicitly load the local or remote, respectively, TLPDB.
1390 .IP save 4
1391 .IX Item "save"
1392 Save the local TLPDB, presumably after other operations have changed it.
1393 .IP "get [\fIvar\fR] =item set [\fIvar\fR [\fIval\fR]]" 4
1394 .IX Item "get [var] =item set [var [val]]"
1395 Get the value of \fIvar\fR, or set it to \fIval\fR. Possible \fIvar\fR names:
1396 \&\f(CW\*(C`debug\-translation\*(C'\fR, \f(CW\*(C`machine\-readable\*(C'\fR, \f(CW\*(C`no\-execute\-actions\*(C'\fR,
1397 \&\f(CW\*(C`require\-verification\*(C'\fR, \f(CW\*(C`verify\-downloads\*(C'\fR, \f(CW\*(C`repository\*(C'\fR, and
1398 \&\f(CW\*(C`prompt\*(C'\fR. All except \f(CW\*(C`repository\*(C'\fR and \f(CW\*(C`prompt\*(C'\fR are booleans, taking
1399 values 0 and 1, and behave like the corresponding command line option.
1400 The \f(CW\*(C`repository\*(C'\fR variable takes a string, and sets the remote
1401 repository location. The \f(CW\*(C`prompt\*(C'\fR variable takes a string, and sets the
1402 current default prompt.
1403 .Sp
1404 If \fIvar\fR or then \fIval\fR is not specified, it is prompted for.
1405 .SS show
1406 .IX Subsection "show"
1407 Synonym for "info".
1408 .SS uninstall
1409 .IX Subsection "uninstall"
1410 Synonym for remove.
1411 .SS "update [\fIoption\fP...] [\fIpkg\fP...]"
1412 .IX Subsection "update [option...] [pkg...]"
1413 Updates the packages given as arguments to the latest version available
1414 at the installation source. Either \f(CW\*(C`\-\-all\*(C'\fR or at least one \fIpkg\fR name
1415 must be specified. Options:
1416 .IP \fB\-\-all\fR 4
1417 .IX Item "--all"
1418 Update all installed packages except for \f(CW\*(C`tlmgr\*(C'\fR itself. If updates to
1419 \&\f(CW\*(C`tlmgr\*(C'\fR itself are present, this gives an error, unless also the option
1420 \&\f(CW\*(C`\-\-force\*(C'\fR or \f(CW\*(C`\-\-self\*(C'\fR is given. (See below.)
1421 .Sp
1422 In addition to updating the installed packages, during the update of a
1423 collection the local installation is (by default) synchronized to the
1424 status of the collection on the server, for both additions and removals.
1425 .Sp
1426 This means that if a package has been removed on the server (and thus
1427 has also been removed from the respective collection), \f(CW\*(C`tlmgr\*(C'\fR will
1428 remove the package in the local installation. This is called
1429 \&\`\`auto\-remove\*(Aq\*(Aq and is announced as such when using the option
1430 \&\f(CW\*(C`\-\-list\*(C'\fR. This auto\-removal can be suppressed using the option
1431 \&\f(CW\*(C`\-\-no\-auto\-remove\*(C'\fR (not recommended, see option description).
1432 .Sp
1433 Analogously, if a package has been added to a collection on the server
1434 that is also installed locally, it will be added to the local
1435 installation. This is called \`\`auto\-install\*(Aq\*(Aq and is announced as such
1436 when using the option \f(CW\*(C`\-\-list\*(C'\fR. This auto\-installation can be
1437 suppressed using the option \f(CW\*(C`\-\-no\-auto\-install\*(C'\fR (also not recommended).
1438 .Sp
1439 An exception to the collection dependency checks (including the
1440 auto\-installation of packages just mentioned) are those that have been
1441 \&\`\`forcibly removed\*(Aq\*(Aq by you, that is, you called \f(CW\*(C`tlmgr remove \-\-force\*(C'\fR
1442 on them. (See the \f(CW\*(C`remove\*(C'\fR action documentation.) To reinstall any
1443 such forcibly removed packages use \f(CW\*(C`\-\-reinstall\-forcibly\-removed\*(C'\fR.
1444 .Sp
1445 To reiterate: automatic removals and additions are entirely determined
1446 by comparison of collections. Thus, if you manually install an
1447 individual package \f(CW\*(C`foo\*(C'\fR which is later removed from the server,
1448 \&\f(CW\*(C`tlmgr\*(C'\fR will not notice and will not remove it locally. (It has to be
1449 this way, without major rearchitecture work, because the tlpdb does not
1450 record the repository from which packages come from.)
1451 .Sp
1452 If you want to exclude some packages from the current update run (e.g.,
1453 due to a slow link), see the \f(CW\*(C`\-\-exclude\*(C'\fR option below.
1454 .IP \fB\-\-self\fR 4
1455 .IX Item "--self"
1456 Update \f(CW\*(C`tlmgr\*(C'\fR itself (that is, the infrastructure packages) if updates
1457 to it are present. On Windows this includes updates to the private Perl
1458 interpreter shipped inside TeX Live.
1459 .Sp
1460 If this option is given together with either \f(CW\*(C`\-\-all\*(C'\fR or a list of
1461 packages, then \f(CW\*(C`tlmgr\*(C'\fR will be updated first and, if this update
1462 succeeds, the new version will be restarted to complete the rest of the
1463 updates.
1464 .Sp
1465 In short:
1466 .Sp
1467 .Vb 4
1468 \& tlmgr update \-\-self # update infrastructure only
1469 \& tlmgr update \-\-self \-\-all # update infrastructure and all packages
1470 \& tlmgr update \-\-force \-\-all # update all packages but *not* infrastructure
1471 \& # ... this last at your own risk, not recommended!
1472 .Ve
1473 .IP \fB\-\-dry\-run\fR 4
1474 .IX Item "--dry-run"
1475 Nothing is actually installed; instead, the actions to be performed are
1476 written to the terminal. This is a more detailed report than \f(CW\*(C`\-\-list\*(C'\fR.
1477 .IP "\fB\-\-list\fR [\fIpkg\fR]" 4
1478 .IX Item "--list [pkg]"
1479 Concisely list the packages which would be updated, newly installed, or
1480 removed, without actually changing anything.
1481 If \f(CW\*(C`\-\-all\*(C'\fR is also given, all available updates are listed.
1482 If \f(CW\*(C`\-\-self\*(C'\fR is given, but not \f(CW\*(C`\-\-all\*(C'\fR, only updates to the
1483 critical packages (tlmgr, texlive infrastructure, perl on Windows, etc.)
1484 are listed.
1485 If neither \f(CW\*(C`\-\-all\*(C'\fR nor \f(CW\*(C`\-\-self\*(C'\fR is given, and in addition no \fIpkg\fR is
1486 given, then \f(CW\*(C`\-\-all\*(C'\fR is assumed (thus, \f(CW\*(C`tlmgr update \-\-list\*(C'\fR is the
1487 same as \f(CW\*(C`tlmgr update \-\-list \-\-all\*(C'\fR).
1488 If neither \f(CW\*(C`\-\-all\*(C'\fR nor \f(CW\*(C`\-\-self\*(C'\fR is given, but specific package names are
1489 given, those packages are checked for updates.
1490 .IP "\fB\-\-exclude\fR \fIpkg\fR" 4
1491 .IX Item "--exclude pkg"
1492 Exclude \fIpkg\fR from the update process. If this option is given more
1493 than once, its arguments accumulate.
1494 .Sp
1495 An argument \fIpkg\fR excludes both the package \fIpkg\fR itself and all
1496 its related platform\-specific packages \fIpkg.ARCH\fR. For example,
1497 .Sp
1498 .Vb 1
1499 \& tlmgr update \-\-all \-\-exclude a2ping
1500 .Ve
1501 .Sp
1502 will not update \f(CW\*(C`a2ping\*(C'\fR, \f(CW\*(C`a2ping.i386\-linux\*(C'\fR, or
1503 any other \f(CW\*(C`a2ping.\*(C'\fR\fIARCH\fR package.
1504 .Sp
1505 If this option specifies a package that would otherwise be a candidate
1506 for auto\-installation, auto\-removal, or reinstallation of a forcibly
1507 removed package, \f(CW\*(C`tlmgr\*(C'\fR quits with an error message. Excludes are not
1508 supported in these circumstances.
1509 .Sp
1510 This option can also be set permanently in the tlmgr config file with
1511 the key \f(CW\*(C`update\-exclude\*(C'\fR.
1512 .IP "\fB\-\-no\-auto\-remove\fR [\fIpkg\fR...]" 4
1513 .IX Item "--no-auto-remove [pkg...]"
1514 By default, \f(CW\*(C`tlmgr\*(C'\fR tries to remove packages in an existing collection
1515 which have disappeared on the server, as described above under \f(CW\*(C`\-\-all\*(C'\fR.
1516 This option prevents such removals, either for all packages (with
1517 \&\f(CW\*(C`\-\-all\*(C'\fR), or for just the given \fIpkg\fR names. This can lead to an
1518 inconsistent TeX installation, since packages are not infrequently
1519 renamed or replaced by their authors. Therefore this is not recommended.
1520 .IP "\fB\-\-no\-auto\-install\fR [\fIpkg\fR...]" 4
1521 .IX Item "--no-auto-install [pkg...]"
1522 Under normal circumstances \f(CW\*(C`tlmgr\*(C'\fR will install packages which are new
1523 on the server, as described above under \f(CW\*(C`\-\-all\*(C'\fR. This option prevents
1524 any such automatic installation, either for all packages (with
1525 \&\f(CW\*(C`\-\-all\*(C'\fR), or the given \fIpkg\fR names.
1526 .Sp
1527 Furthermore, after the \f(CW\*(C`tlmgr\*(C'\fR run using this has finished, the
1528 packages that would have been auto\-installed \fIwill be considered as
1529 forcibly removed\fR. So, if \f(CW\*(C`foobar\*(C'\fR is the only new package on the
1530 server, then
1531 .Sp
1532 .Vb 1
1533 \& tlmgr update \-\-all \-\-no\-auto\-install
1534 .Ve
1535 .Sp
1536 is equivalent to
1537 .Sp
1538 .Vb 2
1539 \& tlmgr update \-\-all
1540 \& tlmgr remove \-\-force foobar
1541 .Ve
1542 .Sp
1543 Again, since packages are sometimes renamed or replaced, using this
1544 option is not recommended.
1545 .IP \fB\-\-reinstall\-forcibly\-removed\fR 4
1546 .IX Item "--reinstall-forcibly-removed"
1547 Under normal circumstances \f(CW\*(C`tlmgr\*(C'\fR will not install packages that have
1548 been forcibly removed by the user; that is, removed with \f(CW\*(C`remove
1549 \&\-\-force\*(C'\fR, or whose installation was prohibited by \f(CW\*(C`\-\-no\-auto\-install\*(C'\fR
1550 during an earlier update.
1551 .Sp
1552 This option makes \f(CW\*(C`tlmgr\*(C'\fR ignore the forcible removals and re\-install
1553 all such packages. This can be used to completely synchronize an
1554 installation with the server\*(Aqs idea of what is available:
1555 .Sp
1556 .Vb 1
1557 \& tlmgr update \-\-reinstall\-forcibly\-removed \-\-all
1558 .Ve
1559 .IP \fB\-\-backup\fR 4
1560 .IX Item "--backup"
1561 .PD 0
1562 .IP "\fB\-\-backupdir\fR \fIdirectory\fR" 4
1563 .IX Item "--backupdir directory"
1564 .PD
1565 These two options control the creation of backups of packages \fIbefore\fR
1566 updating; that is, backing up packages as currently installed. If
1567 neither option is given, no backup will made. If \f(CW\*(C`\-\-backupdir\*(C'\fR is
1568 given and specifies a writable directory then a backup will be made in
1569 that location. If only \f(CW\*(C`\-\-backup\*(C'\fR is given, then a backup will be made
1570 to the directory previously set via the "option" action (see
1571 below). If both are given then a backup will be made to the specified
1572 \&\fIdirectory\fR.
1573 .Sp
1574 You can also set options via the "option" action to automatically make
1575 backups for all packages, and/or keep only a certain number of backups.
1576 .Sp
1577 \&\f(CW\*(C`tlmgr\*(C'\fR always makes a temporary backup when updating packages, in case
1578 of download or other failure during an update. In contrast, the purpose
1579 of this \f(CW\*(C`\-\-backup\*(C'\fR option is to save a persistent backup in case the
1580 actual \fIcontent\fR of the update causes problems, e.g., introduces an TeX
1581 incompatibility.
1582 .Sp
1583 The "restore" action explains how to restore from a backup.
1584 .IP \fB\-\-no\-depends\fR 4
1585 .IX Item "--no-depends"
1586 If you call for updating a package normally all depending packages
1587 will also be checked for updates and updated if necessary. This switch
1588 suppresses this behavior.
1589 .IP \fB\-\-no\-depends\-at\-all\fR 4
1590 .IX Item "--no-depends-at-all"
1591 See above under install (and beware).
1592 .IP \fB\-\-force\fR 4
1593 .IX Item "--force"
1594 Force update of normal packages, without updating \f(CW\*(C`tlmgr\*(C'\fR itself
1595 (unless the \f(CW\*(C`\-\-self\*(C'\fR option is also given). Not recommended.
1596 .Sp
1597 Also, \f(CW\*(C`update \-\-list\*(C'\fR is still performed regardless of this option.
1598 .PP
1599 If the package on the server is older than the package already installed
1600 (e.g., if the selected mirror is out of date), \f(CW\*(C`tlmgr\*(C'\fR does not
1601 downgrade. Also, packages for uninstalled platforms are not installed.
1602 .PP
1603 \&\f(CW\*(C`tlmgr\*(C'\fR saves one copy of the main \f(CW\*(C`texlive.tlpdb\*(C'\fR file used for an
1604 update with a suffix representing the repository url, as in
1605 \&\f(CW\*(C`tlpkg/texlive.tlpdb.main.\*(C'\fR\fIlong\-hash\-string\fR. Thus, even when many
1606 mirrors are used, only one main \f(CW\*(C`tlpdb\*(C'\fR backup is kept. For non\-main
1607 repositories, which do not generally have (m)any mirrors, no pruning of
1608 backups is done.
1609 .PP
1610 This action does not automatically add or remove new symlinks in system
1611 directories; you need to run \f(CW\*(C`tlmgr\*(C'\fR "path" yourself if you are using
1612 this feature and want new symlinks added.
1613 .SH "CONFIGURATION FILE FOR TLMGR"
1614 .IX Header "CONFIGURATION FILE FOR TLMGR"
1615 \&\f(CW\*(C`tlmgr\*(C'\fR reads two configuration files: one is system\-wide, in
1616 \&\f(CW\*(C`TEXMFSYSCONFIG/tlmgr/config\*(C'\fR, and the other is user\-specific, in
1617 \&\f(CW\*(C`TEXMFCONFIG/tlmgr/config\*(C'\fR. The user\-specific one is the default for
1618 the \f(CW\*(C`conf tlmgr\*(C'\fR action. (Run \f(CW\*(C`kpsewhich
1619 \&\-var\-value=TEXMFSYSCONFIG\*(C'\fR or \f(CW\*(C`... TEXMFCONFIG ...\*(C'\fR to see the actual
1620 directory names.)
1621 .PP
1622 A few defaults corresponding to command\-line options can be set in these
1623 configuration files. In addition, the system\-wide file can contain a
1624 directive to restrict the allowed actions.
1625 .PP
1626 In these config files, empty lines and lines starting with # are
1627 ignored. All other lines must look like:
1628 .PP
1629 .Vb 1
1630 \& key = value
1631 .Ve
1632 .PP
1633 where the spaces are optional but the \f(CW\*(C`=\*(C'\fR is required.
1634 .PP
1635 The allowed keys are:
1636 .ie n .IP """auto\-remove ="" 0 or 1 (default 1), same as command\-line option." 4
1637 .el .IP "\f(CWauto\-remove =\fR 0 or 1 (default 1), same as command\-line option." 4
1638 .IX Item "auto-remove = 0 or 1 (default 1), same as command-line option."
1639 .PD 0
1640 .ie n .IP """gui\-expertmode ="" 0 or 1 (default 1). This switches between the full GUI and a simplified GUI with only the most common settings." 4
1641 .el .IP "\f(CWgui\-expertmode =\fR 0 or 1 (default 1). This switches between the full GUI and a simplified GUI with only the most common settings." 4
1642 .IX Item "gui-expertmode = 0 or 1 (default 1). This switches between the full GUI and a simplified GUI with only the most common settings."
1643 .ie n .IP """gui\-lang ="" \fIllcode\fR, with a language code value as with the command\-line option." 4
1644 .el .IP "\f(CWgui\-lang =\fR \fIllcode\fR, with a language code value as with the command\-line option." 4
1645 .IX Item "gui-lang = llcode, with a language code value as with the command-line option."
1646 .ie n .IP """no\-checksums ="" 0 or 1 (default 0, see below)." 4
1647 .el .IP "\f(CWno\-checksums =\fR 0 or 1 (default 0, see below)." 4
1648 .IX Item "no-checksums = 0 or 1 (default 0, see below)."
1649 .ie n .IP """persistent\-downloads ="" 0 or 1 (default 1), same as command\-line option." 4
1650 .el .IP "\f(CWpersistent\-downloads =\fR 0 or 1 (default 1), same as command\-line option." 4
1651 .IX Item "persistent-downloads = 0 or 1 (default 1), same as command-line option."
1652 .ie n .IP """require\-verification ="" 0 or 1 (default 0), same as command\-line option." 4
1653 .el .IP "\f(CWrequire\-verification =\fR 0 or 1 (default 0), same as command\-line option." 4
1654 .IX Item "require-verification = 0 or 1 (default 0), same as command-line option."
1655 .ie n .IP """tkfontscale ="" \fIfloating\-point number\fR (default 1.0); scaling factor for fonts in the Tk\-based frontends." 4
1656 .el .IP "\f(CWtkfontscale =\fR \fIfloating\-point number\fR (default 1.0); scaling factor for fonts in the Tk\-based frontends." 4
1657 .IX Item "tkfontscale = floating-point number (default 1.0); scaling factor for fonts in the Tk-based frontends."
1658 .ie n .IP """update\-exclude ="" \fIcomma\-separated list of packages\fR (no spaces allowed). Same as the command line option ""\-\-exclude"" for the ""update"" action." 4
1659 .el .IP "\f(CWupdate\-exclude =\fR \fIcomma\-separated list of packages\fR (no spaces allowed). Same as the command line option \f(CW\-\-exclude\fR for the \f(CWupdate\fR action." 4
1660 .IX Item "update-exclude = comma-separated list of packages (no spaces allowed). Same as the command line option --exclude for the update action."
1661 .ie n .IP """verify\-downloads ="" 0 or 1 (default 1), same as command\-line option." 4
1662 .el .IP "\f(CWverify\-downloads =\fR 0 or 1 (default 1), same as command\-line option." 4
1663 .IX Item "verify-downloads = 0 or 1 (default 1), same as command-line option."
1664 .PD
1665 .PP
1666 The system\-wide config file can contain one additional key:
1667 .ie n .IP """allowed\-actions ="" \fIaction1\fR[,\fIaction2\fR,...] The value is a comma\-separated list (no spaces) of ""tlmgr"" actions which are allowed to be executed when ""tlmgr"" is invoked in system mode (that is, without ""\-\-usermode""). This allows distributors to include ""tlmgr"" in their packaging, but allow only a restricted set of actions that do not interfere with their distro package manager. For native TeX Live installations, it doesn\*(Aqt make sense to set this." 4
1668 .el .IP "\f(CWallowed\-actions =\fR \fIaction1\fR[,\fIaction2\fR,...] The value is a comma\-separated list (no spaces) of \f(CWtlmgr\fR actions which are allowed to be executed when \f(CWtlmgr\fR is invoked in system mode (that is, without \f(CW\-\-usermode\fR). This allows distributors to include \f(CWtlmgr\fR in their packaging, but allow only a restricted set of actions that do not interfere with their distro package manager. For native TeX Live installations, it doesn\*(Aqt make sense to set this." 4
1669 .IX Item "allowed-actions = action1[,action2,...] The value is a comma-separated list (no spaces) of tlmgr actions which are allowed to be executed when tlmgr is invoked in system mode (that is, without --usermode). This allows distributors to include tlmgr in their packaging, but allow only a restricted set of actions that do not interfere with their distro package manager. For native TeX Live installations, it doesn't make sense to set this."
1670 .PP
1671 Finally, the \f(CW\*(C`no\-checksums\*(C'\fR key needs more explanation. By default,
1672 package checksums computed and stored on the server (in the TLPDB) are
1673 compared to checksums computed locally after downloading.
1674 \&\f(CW\*(C`no\-checksums\*(C'\fR disables this process. The checksum algorithm is
1675 SHA\-512. Your system must have one of (looked for in this order) the
1676 Perl \f(CW\*(C`Digest::SHA\*(C'\fR module, the \f(CW\*(C`openssl\*(C'\fR program
1677 (<https://openssl.org>), the \f(CW\*(C`sha512sum\*(C'\fR program (from GNU Coreutils,
1678 <https://www.gnu.org/software/coreutils>), or finally the \f(CW\*(C`shasum\*(C'\fR
1679 program (just to support old Macs). If none of these are available, a
1680 warning is issued and \f(CW\*(C`tlmgr\*(C'\fR proceeds without checking checksums.
1681 \&\f(CW\*(C`no\-checksums\*(C'\fR avoids the warning. (Incidentally, other SHA
1682 implementations, such as the pure Perl and pure Lua modules, are much
1683 too slow to be usable in our context.)
1684 .SH "CRYPTOGRAPHIC VERIFICATION"
1685 .IX Header "CRYPTOGRAPHIC VERIFICATION"
1686 \&\f(CW\*(C`tlmgr\*(C'\fR and \f(CW\*(C`install\-tl\*(C'\fR perform cryptographic verification if
1687 possible. If verification is performed and successful, the programs
1688 report \f(CW\*(C`(verified)\*(C'\fR after loading the TLPDB; otherwise, they report
1689 \&\f(CW\*(C`(not verified)\*(C'\fR. But either way, by default the installation and/or
1690 updates proceed normally.
1691 .PP
1692 If a program named \f(CW\*(C`gpg\*(C'\fR is available (that is, found in \f(CW\*(C`PATH\*(C'\fR), by
1693 default cryptographic signatures will be checked: we require the main
1694 repository be signed, but not any additional repositories. If \f(CW\*(C`gpg\*(C'\fR is
1695 not available, by default signatures are not checked and no verification
1696 is carried out, but \f(CW\*(C`tlmgr\*(C'\fR still proceeds normally.
1697 .PP
1698 The behavior of the verification can be controlled by the command line
1699 and config file option \f(CW\*(C`verify\-repo\*(C'\fR which takes one of the following
1700 values: \f(CW\*(C`none\*(C'\fR, \f(CW\*(C`main\*(C'\fR, or \f(CW\*(C`all\*(C'\fR. With \f(CW\*(C`none\*(C'\fR, no verification
1701 whatsoever is attempted. With \f(CW\*(C`main\*(C'\fR (the default) verification is
1702 required only for the main repository, and only if \f(CW\*(C`gpg\*(C'\fR is available;
1703 though attempted for all, missing signatures of subsidiary repositories
1704 will not result in an error. Finally, in the case of \f(CW\*(C`all\*(C'\fR, \f(CW\*(C`gpg\*(C'\fR
1705 must be available and all repositories need to be signed.
1706 .PP
1707 In all cases, if a signature is checked and fails to verify, an error
1708 is raised.
1709 .PP
1710 Cryptographic verification requires checksum checking (described just
1711 above) to succeed, and a working GnuPG (\f(CW\*(C`gpg\*(C'\fR) program (see below for
1712 search method). Then, unless cryptographic verification has been
1713 disabled, a signature file (\f(CW\*(C`texlive.tlpdb.*.asc\*(C'\fR) of the checksum file
1714 is downloaded and the signature verified. The signature is created by
1715 the TeX Live Distribution GPG key 0x0D5E5D9106BAB6BC, which in turn is
1716 signed by Karl Berry\*(Aqs key 0x0716748A30D155AD and
1717 Norbert Preining\*(Aqs key 0x6CACA448860CDC13. All
1718 of these keys are obtainable from the standard key servers.
1719 .PP
1720 Additional trusted keys can be added using the \f(CW\*(C`key\*(C'\fR action.
1721 .SS "Configuration of GnuPG invocation"
1722 .IX Subsection "Configuration of GnuPG invocation"
1723 The executable used for GnuPG is searched as follows: If the environment
1724 variable \f(CW\*(C`TL_GNUPG\*(C'\fR is set, it is tested and used; otherwise \f(CW\*(C`gpg\*(C'\fR is
1725 checked; finally \f(CW\*(C`gpg2\*(C'\fR is checked.
1726 .PP
1727 Further adaptation of the \f(CW\*(C`gpg\*(C'\fR invocation can be made using the two
1728 environment variables \f(CW\*(C`TL_GNUPGHOME\*(C'\fR, which is passed to \f(CW\*(C`gpg\*(C'\fR as the
1729 value for \f(CW\*(C`\-\-homedir\*(C'\fR, and \f(CW\*(C`TL_GNUPGARGS\*(C'\fR, which replaces the default
1730 options \f(CW\*(C`\-\-no\-secmem\-warning \-\-no\-permission\-warning\*(C'\fR.
1731 .SH "USER MODE"
1732 .IX Header "USER MODE"
1733 \&\f(CW\*(C`tlmgr\*(C'\fR provides a restricted way, called \`\`user mode\*(Aq\*(Aq, to manage
1734 arbitrary texmf trees in the same way as the main installation. For
1735 example, this allows people without write permissions on the
1736 installation location to update/install packages into a tree of their
1737 own.
1738 .PP
1739 \&\f(CW\*(C`tlmgr\*(C'\fR is switched into user mode with the command line option
1740 \&\f(CW\*(C`\-\-usermode\*(C'\fR. It does not switch automatically, nor is there any
1741 configuration file setting for it. Thus, this option has to be
1742 explicitly given every time user mode is to be activated.
1743 .PP
1744 This mode of \f(CW\*(C`tlmgr\*(C'\fR works on a user tree, by default the value of the
1745 \&\f(CW\*(C`TEXMFHOME\*(C'\fR variable. This can be overridden with the command line
1746 option \f(CW\*(C`\-\-usertree\*(C'\fR. In the following when we speak of the user tree
1747 we mean either \f(CW\*(C`TEXMFHOME\*(C'\fR or the one given on the command line.
1748 .PP
1749 Not all actions are allowed in user mode; \f(CW\*(C`tlmgr\*(C'\fR will warn you and not
1750 carry out any problematic actions. Currently not supported (and
1751 probably will never be) is the \f(CW\*(C`platform\*(C'\fR action. The \f(CW\*(C`gui\*(C'\fR action is
1752 currently not supported, but may be in a future release.
1753 .PP
1754 Some \f(CW\*(C`tlmgr\*(C'\fR actions don\*(Aqt need any write permissions and thus work the
1755 same in user mode and normal mode. Currently these are: \f(CW\*(C`check\*(C'\fR,
1756 \&\f(CW\*(C`help\*(C'\fR, \f(CW\*(C`list\*(C'\fR, \f(CW\*(C`print\-platform\*(C'\fR, \f(CW\*(C`print\-platform\-info\*(C'\fR, \f(CW\*(C`search\*(C'\fR,
1757 \&\f(CW\*(C`show\*(C'\fR, \f(CW\*(C`version\*(C'\fR.
1758 .PP
1759 On the other hand, most of the actions dealing with package management
1760 do need write permissions, and thus behave differently in user mode, as
1761 described below: \f(CW\*(C`install\*(C'\fR, \f(CW\*(C`update\*(C'\fR, \f(CW\*(C`remove\*(C'\fR, \f(CW\*(C`option\*(C'\fR, \f(CW\*(C`paper\*(C'\fR,
1762 \&\f(CW\*(C`generate\*(C'\fR, \f(CW\*(C`backup\*(C'\fR, \f(CW\*(C`restore\*(C'\fR, \f(CW\*(C`uninstall\*(C'\fR, \f(CW\*(C`symlinks\*(C'\fR.
1763 .PP
1764 Before using \f(CW\*(C`tlmgr\*(C'\fR in user mode, you have to set up the user tree
1765 with the \f(CW\*(C`init\-usertree\*(C'\fR action. This creates \fIusertree\fR\f(CW\*(C`/web2c\*(C'\fR and
1766 \&\fIusertree\fR\f(CW\*(C`/tlpkg/tlpobj\*(C'\fR, and a minimal
1767 \&\fIusertree\fR\f(CW\*(C`/tlpkg/texlive.tlpdb\*(C'\fR. At that point, you can tell
1768 \&\f(CW\*(C`tlmgr\*(C'\fR to do the (supported) actions by adding the \f(CW\*(C`\-\-usermode\*(C'\fR
1769 command line option.
1770 .PP
1771 In user mode the file \fIusertree\fR\f(CW\*(C`/tlpkg/texlive.tlpdb\*(C'\fR contains only
1772 the packages that have been installed into the user tree using \f(CW\*(C`tlmgr\*(C'\fR,
1773 plus additional options from the \`\`virtual\*(Aq\*(Aq package
1774 \&\f(CW\*(C`00texlive.installation\*(C'\fR (similar to the main installation\*(Aqs
1775 \&\f(CW\*(C`texlive.tlpdb\*(C'\fR).
1776 .PP
1777 All actions on packages in user mode can only be carried out on packages
1778 that are known as \f(CW\*(C`relocatable\*(C'\fR. This excludes all packages containing
1779 executables and a few other core packages. Of the 2500 or so packages
1780 currently in TeX Live the vast majority are relocatable and can be
1781 installed into a user tree.
1782 .PP
1783 Description of changes of actions in user mode:
1784 .SS "User mode install"
1785 .IX Subsection "User mode install"
1786 In user mode, the \f(CW\*(C`install\*(C'\fR action checks that the package and all
1787 dependencies are all either relocated or already installed in the system
1788 installation. If this is the case, it unpacks all containers to be
1789 installed into the user tree (to repeat, that\*(Aqs either \f(CW\*(C`TEXMFHOME\*(C'\fR or
1790 the value of \f(CW\*(C`\-\-usertree\*(C'\fR) and add the respective packages to the user
1791 tree\*(Aqs \f(CW\*(C`texlive.tlpdb\*(C'\fR (creating it if need be).
1792 .PP
1793 Currently installing a collection in user mode installs all dependent
1794 packages, but in contrast to normal mode, does \fInot\fR install dependent
1795 collections. For example, in normal mode \f(CW\*(C`tlmgr install
1796 collection\-context\*(C'\fR would install \f(CW\*(C`collection\-basic\*(C'\fR and other
1797 collections, while in user mode, \fIonly\fR the packages mentioned in
1798 \&\f(CW\*(C`collection\-context\*(C'\fR are installed.
1799 .PP
1800 If a package shipping map files is installed in user mode, a backup of
1801 the user\*(Aqs \f(CW\*(C`updmap.cfg\*(C'\fR in \f(CW\*(C`USERTREE/web2c/\*(C'\fR is made, and then this file
1802 regenerated from the list of installed packages.
1803 .SS "User mode backup, restore, remove, update"
1804 .IX Subsection "User mode backup, restore, remove, update"
1805 In user mode, these actions check that all packages to be acted on are
1806 installed in the user tree before proceeding; otherwise, they behave
1807 just as in normal mode.
1808 .SS "User mode generate, option, paper"
1809 .IX Subsection "User mode generate, option, paper"
1810 In user mode, these actions operate only on the user tree\*(Aqs
1811 configuration files and/or \f(CW\*(C`texlive.tlpdb\*(C'\fR.
1812 .SS "User mode logs"
1813 .IX Subsection "User mode logs"
1814 In user mode, \f(CW\*(C`tlmgr.log\*(C'\fR and <tlmgr\-commands.log> are written in the
1815 \&\f(CW\*(C`TEXMFVAR/web2c/\*(C'\fR directlry instead of \f(CW\*(C`TEXMFSYSVAR/web2c/\*(C'\fR.
1816 .SH "MULTIPLE REPOSITORIES"
1817 .IX Header "MULTIPLE REPOSITORIES"
1818 The main TeX Live repository contains a vast array of packages.
1819 Nevertheless, additional local repositories can be useful to provide
1820 locally\-installed resources, such as proprietary fonts and house styles.
1821 Also, alternative package repositories distribute packages that cannot
1822 or should not be included in TeX Live, for whatever reason.
1823 .PP
1824 The simplest and most reliable method is to temporarily set the
1825 installation source to any repository (with the \f(CW\*(C`\-repository\*(C'\fR or
1826 \&\f(CW\*(C`option repository\*(C'\fR command line options), and perform your operations.
1827 .PP
1828 When you are using multiple repositories over a sustained length of
1829 time, however, explicitly switching between them becomes inconvenient.
1830 Thus, it\*(Aqs possible to tell \f(CW\*(C`tlmgr\*(C'\fR about additional repositories you
1831 want to use. The basic command is \f(CW\*(C`tlmgr repository add\*(C'\fR. The rest of
1832 this section explains further.
1833 .PP
1834 When using multiple repositories, one of them has to be set as the main
1835 repository, which distributes most of the installed packages. When you
1836 switch from a single repository installation to a multiple repository
1837 installation, the previous sole repository will be set as the main
1838 repository.
1839 .PP
1840 By default, even if multiple repositories are configured, packages are
1841 \&\fIstill\fR \fIonly\fR installed from the main repository. Thus, simply
1842 adding a second repository does not actually enable installation of
1843 anything from there. You also have to specify which packages should be
1844 taken from the new repository, by specifying so\-called \`\`pinning\*(Aq\*(Aq
1845 rules, described next.
1846 .SS Pinning
1847 .IX Subsection "Pinning"
1848 When a package \f(CW\*(C`foo\*(C'\fR is pinned to a repository, a package \f(CW\*(C`foo\*(C'\fR in any
1849 other repository, even if it has a higher revision number, will not be
1850 considered an installable candidate.
1851 .PP
1852 As mentioned above, by default everything is pinned to the main
1853 repository. Let\*(Aqs now go through an example of setting up a second
1854 repository and enabling updates of a package from it.
1855 .PP
1856 First, check that we have support for multiple repositories, and have
1857 only one enabled (as is the case by default):
1858 .PP
1859 .Vb 3
1860 \& $ tlmgr repository list
1861 \& List of repositories (with tags if set):
1862 \& /var/www/norbert/tlnet
1863 .Ve
1864 .PP
1865 Ok. Let\*(Aqs add the \f(CW\*(C`tlcontrib\*(C'\fR repository (this is a real
1866 repository hosted at <http://contrib.texlive.info>) with the tag \f(CW\*(C`tlcontrib\*(C'\fR:
1867 .PP
1868 .Vb 1
1869 \& $ tlmgr repository add http://contrib.texlive.info/current tlcontrib
1870 .Ve
1871 .PP
1872 Check the repository list again:
1873 .PP
1874 .Vb 4
1875 \& $ tlmgr repository list
1876 \& List of repositories (with tags if set):
1877 \& http://contrib.texlive.info/current (tlcontrib)
1878 \& /var/www/norbert/tlnet (main)
1879 .Ve
1880 .PP
1881 Now we specify a pinning entry to get the package \f(CW\*(C`classico\*(C'\fR from
1882 \&\f(CW\*(C`tlcontrib\*(C'\fR:
1883 .PP
1884 .Vb 1
1885 \& $ tlmgr pinning add tlcontrib classico
1886 .Ve
1887 .PP
1888 Check that we can find \f(CW\*(C`classico\*(C'\fR:
1889 .PP
1890 .Vb 5
1891 \& $ tlmgr show classico
1892 \& package: classico
1893 \& ...
1894 \& shortdesc: URW Classico fonts
1895 \& ...
1896 .Ve
1897 .PP
1898 \&\- install \f(CW\*(C`classico\*(C'\fR:
1899 .PP
1900 .Vb 4
1901 \& $ tlmgr install classico
1902 \& tlmgr: package repositories:
1903 \& ...
1904 \& [1/1, ??:??/??:??] install: classico @tlcontrib [737k]
1905 .Ve
1906 .PP
1907 In the output here you can see that the \f(CW\*(C`classico\*(C'\fR package has been
1908 installed from the \f(CW\*(C`tlcontrib\*(C'\fR repository (\f(CW@tlcontrib\fR).
1909 .PP
1910 Finally, \f(CW\*(C`tlmgr pinning\*(C'\fR also supports removing certain or all packages
1911 from a given repository:
1912 .PP
1913 .Vb 2
1914 \& $ tlmgr pinning remove tlcontrib classico # remove just classico
1915 \& $ tlmgr pinning remove tlcontrib \-\-all # take nothing from tlcontrib
1916 .Ve
1917 .PP
1918 A summary of \f(CW\*(C`tlmgr pinning\*(C'\fR actions is given above.
1919 .SH "GUI FOR TLMGR"
1920 .IX Header "GUI FOR TLMGR"
1921 The graphical user interface for \f(CW\*(C`tlmgr\*(C'\fR requires Perl/Tk
1922 <https://search.cpan.org/search?query=perl%2Ftk>. For Unix\-based
1923 systems Perl/Tk (as well as Perl of course) has to be installed
1924 outside of TL. <https://tug.org/texlive/distro.html#perltk> has a
1925 list of invocations for some distros. For Windows the necessary
1926 modules are no longer shipped within TeX Live, so you\*(Aqll have to have an
1927 external Perl available that includes them.
1928 .PP
1929 We are talking here about the GUI built into tlmgr itself, not about the
1930 other tlmgr GUIs, which are: tlshell (Tcl/Tk\-based), tlcockpit
1931 (Java\-based) and, only on Macs, TeX Live Utility. These are invoked as
1932 separate programs.
1933 .PP
1934 The GUI mode of tlmgr is started with the invocation \f(CW\*(C`tlmgr gui\*(C'\fR;
1935 assuming Tk is loadable, the graphical user interface will be shown.
1936 The main window contains a menu bar, the main display, and a status
1937 area where messages normally shown on the console are displayed.
1938 .PP
1939 Within the main display there are three main parts: the \f(CW\*(C`Display
1940 configuration\*(C'\fR area, the list of packages, and the action buttons.
1941 .PP
1942 Also, at the top right the currently loaded repository is shown; this
1943 also acts as a button and when clicked will try to load the default
1944 repository. To load a different repository, see the \f(CW\*(C`tlmgr\*(C'\fR menu item.
1945 .PP
1946 Finally, the status area at the bottom of the window gives additional
1947 information about what is going on.
1948 .SS "Main display"
1949 .IX Subsection "Main display"
1950 \fIDisplay configuration area\fR
1951 .IX Subsection "Display configuration area"
1952 .PP
1953 The first part of the main display allows you to specify (filter) which
1954 packages are shown. By default, all are shown. Changes here are
1955 reflected right away.
1956 .IP Status 4
1957 .IX Item "Status"
1958 Select whether to show all packages (the default), only those installed,
1959 only those \fInot\fR installed, or only those with update available.
1960 .IP Category 4
1961 .IX Item "Category"
1962 Select which categories are shown: packages, collections, and/or
1963 schemes. These are briefly explained in the "DESCRIPTION" section
1964 above.
1965 .IP Match 4
1966 .IX Item "Match"
1967 Select packages matching for a specific pattern. By default, this
1968 searches both descriptions and filenames. You can also select a subset
1969 for searching.
1970 .IP Selection 4
1971 .IX Item "Selection"
1972 Select packages to those selected, those not selected, or all. Here,
1973 \&\`\`selected\*(Aq\*(Aq means that the checkbox in the beginning of the line of a
1974 package is ticked.
1975 .IP "Display configuration buttons" 4
1976 .IX Item "Display configuration buttons"
1977 To the right there are three buttons: select all packages, select none
1978 (a.k.a. deselect all), and reset all these filters to the defaults,
1979 i.e., show all available.
1980 .PP
1981 \fIPackage list area\fR
1982 .IX Subsection "Package list area"
1983 .PP
1984 The second are of the main display lists all installed packages. If a
1985 repository is loaded, those that are available but not installed are
1986 also listed.
1987 .PP
1988 Double clicking on a package line pops up an informational window with
1989 further details: the long description, included files, etc.
1990 .PP
1991 Each line of the package list consists of the following items:
1992 .IP "a checkbox" 4
1993 .IX Item "a checkbox"
1994 Used to select particular packages; some of the action buttons (see
1995 below) work only on the selected packages.
1996 .IP "package name" 4
1997 .IX Item "package name"
1998 The name (identifier) of the package as given in the database.
1999 .IP "local revision (and version)" 4
2000 .IX Item "local revision (and version)"
2001 If the package is installed the TeX Live revision number for the
2002 installed package will be shown. If there is a catalogue version given
2003 in the database for this package, it will be shown in parentheses.
2004 However, the catalogue version, unlike the TL revision, is not
2005 guaranteed to reflect what is actually installed.
2006 .IP "remote revision (and version)" 4
2007 .IX Item "remote revision (and version)"
2008 If a repository has been loaded the revision of the package in the
2009 repository (if present) is shown. As with the local column, if a
2010 catalogue version is provided it will be displayed. And also as with
2011 the local column, the catalogue version may be stale.
2012 .IP "short description" 4
2013 .IX Item "short description"
2014 The short description of the package.
2015 .PP
2016 \fIMain display action buttons\fR
2017 .IX Subsection "Main display action buttons"
2018 .PP
2019 Below the list of packages are several buttons:
2020 .IP "Update all installed" 4
2021 .IX Item "Update all installed"
2022 This calls \f(CW\*(C`tlmgr update \-\-all\*(C'\fR, i.e., tries to update all available
2023 packages. Below this button is a toggle to allow reinstallation of
2024 previously removed packages as part of this action.
2025 .Sp
2026 The other four buttons only work on the selected packages, i.e., those
2027 where the checkbox at the beginning of the package line is ticked.
2028 .IP Update 4
2029 .IX Item "Update"
2030 Update only the selected packages.
2031 .IP Install 4
2032 .IX Item "Install"
2033 Install the selected packages; acts like \f(CW\*(C`tlmgr install\*(C'\fR, i.e., also
2034 installs dependencies. Thus, installing a collection installs all its
2035 constituent packages.
2036 .IP Remove 4
2037 .IX Item "Remove"
2038 Removes the selected packages; acts like \f(CW\*(C`tlmgr remove\*(C'\fR, i.e., it will
2039 also remove dependencies of collections (but not dependencies of normal
2040 packages).
2041 .IP Backup 4
2042 .IX Item "Backup"
2043 Makes a backup of the selected packages; acts like \f(CW\*(C`tlmgr backup\*(C'\fR. This
2044 action needs the option \f(CW\*(C`backupdir\*(C'\fR set (see \f(CW\*(C`Options \-\*(C'\fR General>).
2045 .SS "Menu bar"
2046 .IX Subsection "Menu bar"
2047 The following entries can be found in the menu bar:
2048 .ie n .IP """tlmgr"" menu" 4
2049 .el .IP "\f(CWtlmgr\fR menu" 4
2050 .IX Item "tlmgr menu"
2051 The items here load various repositories: the default as specified in
2052 the TeX Live database, the default network repository, the repository
2053 specified on the command line (if any), and an arbitrarily
2054 manually\-entered one. Also has the so\-necessary \f(CW\*(C`quit\*(C'\fR operation.
2055 .ie n .IP """Options menu""" 4
2056 .el .IP "\f(CWOptions menu\fR" 4
2057 .IX Item "Options menu"
2058 Provides access to several groups of options: \f(CW\*(C`Paper\*(C'\fR (configuration of
2059 default paper sizes), \f(CW\*(C`Platforms\*(C'\fR (only on Unix, configuration of the
2060 supported/installed platforms), \f(CW\*(C`GUI Language\*(C'\fR (select language used in
2061 the GUI interface), and \f(CW\*(C`General\*(C'\fR (everything else).
2062 .Sp
2063 Several toggles are also here. The first is \f(CW\*(C`Expert options\*(C'\fR, which is
2064 set by default. If you turn this off, the next time you start the GUI a
2065 simplified screen will be shown that display only the most important
2066 functionality. This setting is saved in the configuration file of
2067 \&\f(CW\*(C`tlmgr\*(C'\fR; see "CONFIGURATION FILE FOR TLMGR" for details.
2068 .Sp
2069 The other toggles are all off by default: for debugging output, to
2070 disable the automatic installation of new packages, and to disable the
2071 automatic removal of packages deleted from the server. Playing with the
2072 choices of what is or isn\*(Aqt installed may lead to an inconsistent TeX Live
2073 installation; e.g., when a package is renamed.
2074 .ie n .IP """Actions menu""" 4
2075 .el .IP "\f(CWActions menu\fR" 4
2076 .IX Item "Actions menu"
2077 Provides access to several actions: update the filename database (aka
2078 \&\f(CW\*(C`ls\-R\*(C'\fR, \f(CW\*(C`mktexlsr\*(C'\fR, \f(CW\*(C`texhash\*(C'\fR), rebuild all formats (\f(CW\*(C`fmtutil\-sys
2079 \&\-\-all\*(C'\fR), update the font map database (\f(CW\*(C`updmap\-sys\*(C'\fR), restore from a backup
2080 of a package, and use of symbolic links in system directories (not on
2081 Windows).
2082 .Sp
2083 The final action is to remove the entire TeX Live installation (also not
2084 on Windows).
2085 .ie n .IP """Help menu""" 4
2086 .el .IP "\f(CWHelp menu\fR" 4
2087 .IX Item "Help menu"
2088 Provides access to the TeX Live manual (also on the web at
2089 <https://tug.org/texlive/doc.html>) and the usual \`\`About\*(Aq\*(Aq box.
2090 .SS "GUI options"
2091 .IX Subsection "GUI options"
2092 Some generic Perl/Tk options can be specified with \f(CW\*(C`tlmgr gui\*(C'\fR to
2093 control the display:
2094 .ie n .IP """\-background"" \fIcolor\fR" 4
2095 .el .IP "\f(CW\-background\fR \fIcolor\fR" 4
2096 .IX Item "-background color"
2097 Set background color.
2098 .ie n .IP """\-font """" \fIfontname\fR \fIfontsize\fR """"""" 4
2099 .el .IP "\f(CW\-font ""\fR \fIfontname\fR \fIfontsize\fR \f(CW""\fR" 4
2100 .IX Item "-font "" fontname fontsize """
2101 Set font, e.g., \f(CW\*(C`tlmgr gui \-font "helvetica 18"\*(C'\fR. The argument to
2102 \&\f(CW\*(C`\-font\*(C'\fR must be quoted, i.e., passed as a single string.
2103 .ie n .IP """\-foreground"" \fIcolor\fR" 4
2104 .el .IP "\f(CW\-foreground\fR \fIcolor\fR" 4
2105 .IX Item "-foreground color"
2106 Set foreground color.
2107 .ie n .IP """\-geometry"" \fIgeomspec\fR" 4
2108 .el .IP "\f(CW\-geometry\fR \fIgeomspec\fR" 4
2109 .IX Item "-geometry geomspec"
2110 Set the X geometry, e.g., \f(CW\*(C`tlmgr gui \-geometry 1024x512\-0+0\*(C'\fR creates
2111 the window of (approximately) the given size in the upper\-right corner
2112 of the display.
2113 .ie n .IP """\-xrm"" \fIxresource\fR" 4
2114 .el .IP "\f(CW\-xrm\fR \fIxresource\fR" 4
2115 .IX Item "-xrm xresource"
2116 Pass the arbitrary X resource string \fIxresource\fR.
2117 .PP
2118 A few other obscure options are recognized but not mentioned here. See
2119 the Perl/Tk documentation (<https://search.cpan.org/perldoc?Tk>) for the
2120 complete list, and any X documentation for general information.
2121 .SH "MACHINE\-READABLE OUTPUT"
2122 .IX Header "MACHINE-READABLE OUTPUT"
2123 With the \f(CW\*(C`\-\-machine\-readable\*(C'\fR option, \f(CW\*(C`tlmgr\*(C'\fR writes to stdout in the
2124 fixed line\-oriented format described here, and the usual informational
2125 messages for human consumption are written to stderr (normally they are
2126 written to stdout). The idea is that a program can get all the
2127 information it needs by reading stdout.
2128 .PP
2129 Currently this option only applies to the
2130 update,
2131 install, and
2132 "option" actions.
2133 .ie n .SS "Machine\-readable ""update"" and ""install"" output"
2134 .el .SS "Machine\-readable \f(CWupdate\fP and \f(CWinstall\fP output"
2135 .IX Subsection "Machine-readable update and install output"
2136 The output format is as follows:
2137 .PP
2138 .Vb 7
2139 \& fieldname "\et" value
2140 \& ...
2141 \& "end\-of\-header"
2142 \& pkgname status localrev serverrev size runtime esttot
2143 \& ...
2144 \& "end\-of\-updates"
2145 \& other output from post actions, not in machine readable form
2146 .Ve
2147 .PP
2148 The header section currently has two fields: \f(CW\*(C`location\-url\*(C'\fR (the
2149 repository source from which updates are being drawn), and
2150 \&\f(CW\*(C`total\-bytes\*(C'\fR (the total number of bytes to be downloaded).
2151 .PP
2152 The \fIlocalrev\fR and \fIserverrev\fR fields for each package are the
2153 revision numbers in the local installation and server repository,
2154 respectively. The \fIsize\fR field is the number of bytes to be
2155 downloaded, i.e., the size of the compressed tar file for a network
2156 installation, not the unpacked size. The runtime and esttot fields
2157 are only present for updated and auto\-install packages, and contain
2158 the currently passed time since start of installation/updates
2159 and the estimated total time.
2160 .PP
2161 Line endings may be either LF or CRLF depending on the current platform.
2162 .ie n .IP """location\-url"" \fIlocation\fR" 4
2163 .el .IP "\f(CWlocation\-url\fR \fIlocation\fR" 4
2164 .IX Item "location-url location"
2165 The \fIlocation\fR may be a url (including \f(CW\*(C`file:///foo/bar/...\*(C'\fR), or a
2166 directory name (\f(CW\*(C`/foo/bar\*(C'\fR). It is the package repository from which
2167 the new package information was drawn.
2168 .ie n .IP """total\-bytes"" \fIcount\fR" 4
2169 .el .IP "\f(CWtotal\-bytes\fR \fIcount\fR" 4
2170 .IX Item "total-bytes count"
2171 The \fIcount\fR is simply a decimal number, the sum of the sizes of all the
2172 packages that need updating or installing (which are listed subsequently).
2173 .PP
2174 Then comes a line with only the literal string \f(CW\*(C`end\-of\-header\*(C'\fR.
2175 .PP
2176 Each following line until a line with literal string \f(CW\*(C`end\-of\-updates\*(C'\fR
2177 reports on one package. The fields on
2178 each line are separated by a tab. Here are the fields.
2179 .IP \fIpkgname\fR 4
2180 .IX Item "pkgname"
2181 The TeX Live package identifier, with a possible platform suffix for
2182 executables. For instance, \f(CW\*(C`pdftex\*(C'\fR and \f(CW\*(C`pdftex.i386\-linux\*(C'\fR are given
2183 as two separate packages, one on each line.
2184 .IP \fIstatus\fR 4
2185 .IX Item "status"
2186 The status of the package update. One character, as follows:
2187 .RS 4
2188 .ie n .IP """d""" 8
2189 .el .IP \f(CWd\fR 8
2190 .IX Item "d"
2191 The package was removed on the server.
2192 .ie n .IP """f""" 8
2193 .el .IP \f(CWf\fR 8
2194 .IX Item "f"
2195 The package was removed in the local installation, even though a
2196 collection depended on it. (E.g., the user ran \f(CW\*(C`tlmgr remove
2197 \&\-\-force\*(C'\fR.)
2198 .ie n .IP """u""" 8
2199 .el .IP \f(CWu\fR 8
2200 .IX Item "u"
2201 Normal update is needed.
2202 .ie n .IP """r""" 8
2203 .el .IP \f(CWr\fR 8
2204 .IX Item "r"
2205 Reversed non\-update: the locally\-installed version is newer than the
2206 version on the server.
2207 .ie n .IP """a""" 8
2208 .el .IP \f(CWa\fR 8
2209 .IX Item "a"
2210 Automatically\-determined need for installation, the package is new on
2211 the server and is (most probably) part of an installed collection.
2212 .ie n .IP """i""" 8
2213 .el .IP \f(CWi\fR 8
2214 .IX Item "i"
2215 Package will be installed and isn\*(Aqt present in the local installation
2216 (action install).
2217 .ie n .IP """I""" 8
2218 .el .IP \f(CWI\fR 8
2219 .IX Item "I"
2220 Package is already present but will be reinstalled (action install).
2221 .RE
2222 .RS 4
2223 .RE
2224 .IP \fIlocalrev\fR 4
2225 .IX Item "localrev"
2226 The revision number of the installed package, or \f(CW\*(C`\-\*(C'\fR if it is not
2227 present locally.
2228 .IP \fIserverrev\fR 4
2229 .IX Item "serverrev"
2230 The revision number of the package on the server, or \f(CW\*(C`\-\*(C'\fR if it is not
2231 present on the server.
2232 .IP \fIsize\fR 4
2233 .IX Item "size"
2234 The size in bytes of the package on the server. The sum of all the
2235 package sizes is given in the \f(CW\*(C`total\-bytes\*(C'\fR header field mentioned above.
2236 .IP \fIruntime\fR 4
2237 .IX Item "runtime"
2238 The run time since start of installations or updates.
2239 .IP \fIesttot\fR 4
2240 .IX Item "esttot"
2241 The estimated total time.
2242 .ie n .SS "Machine\-readable ""option"" output"
2243 .el .SS "Machine\-readable \f(CWoption\fP output"
2244 .IX Subsection "Machine-readable option output"
2245 The output format is as follows:
2246 .PP
2247 .Vb 1
2248 \& key "\et" value
2249 .Ve
2250 .PP
2251 If a value is not saved in the database the string \f(CW\*(C`(not set)\*(C'\fR is shown.
2252 .PP
2253 If you are developing a program that uses this output, and find that
2254 changes would be helpful, do not hesitate to write the mailing list.
2255 .SH "ENVIRONMENT VARIABLES"
2256 .IX Header "ENVIRONMENT VARIABLES"
2257 \&\f(CW\*(C`tlmgr\*(C'\fR uses many of the standard TeX environment variables, as
2258 reported by, e.g., \f(CW\*(C`tlmgr conf\*(C'\fR ("conf").
2259 .PP
2260 In addition, for ease in scripting and debugging, \f(CW\*(C`tlmgr\*(C'\fR looks for the
2261 following environment variables. These are not of interest for normal
2262 user installations.
2263 .ie n .IP """TEXLIVE_COMPRESSOR""" 4
2264 .el .IP \f(CWTEXLIVE_COMPRESSOR\fR 4
2265 .IX Item "TEXLIVE_COMPRESSOR"
2266 This variable allows selecting a different compressor program for
2267 backups and intermediate rollback containers. The order of selection is:
2268 .RS 4
2269 .IP 1. 8
2270 If the environment variable \f(CW\*(C`TEXLIVE_COMPRESSOR\*(C'\fR is
2271 defined, use it; abort if it doesn\*(Aqt work. Possible values:
2272 \&\f(CW\*(C`lz4\*(C'\fR, \f(CW\*(C`gzip\*(C'\fR, \f(CW\*(C`xz\*(C'\fR. The necessary options are added internally.
2273 .IP 2. 8
2274 If lz4 is available (either from the system or TL) and working, use that.
2275 .IP 3. 8
2276 If gzip is available (from the system) and working, use that.
2277 .IP 4. 8
2278 If xz is available (either from the system or TL) and working, use that.
2279 .RE
2280 .RS 4
2281 .Sp
2282 lz4 and gzip are faster in creating tlmgr\*(Aqs local backups, hence they
2283 are preferred. The unconditional use of xz for the tlnet containers is
2284 unaffected, to minimize download sizes.
2285 .RE
2286 .ie n .IP """TEXLIVE_DOWNLOADER""" 4
2287 .el .IP \f(CWTEXLIVE_DOWNLOADER\fR 4
2288 .IX Item "TEXLIVE_DOWNLOADER"
2289 .PD 0
2290 .ie n .IP """TL_DOWNLOAD_PROGRAM""" 4
2291 .el .IP \f(CWTL_DOWNLOAD_PROGRAM\fR 4
2292 .IX Item "TL_DOWNLOAD_PROGRAM"
2293 .ie n .IP """TL_DOWNLOAD_ARGS""" 4
2294 .el .IP \f(CWTL_DOWNLOAD_ARGS\fR 4
2295 .IX Item "TL_DOWNLOAD_ARGS"
2296 .PD
2297 These options allow selecting different download programs then the ones
2298 automatically selected by the installer. The order of selection is:
2299 .RS 4
2300 .IP 1. 8
2301 If the environment variable \f(CW\*(C`TEXLIVE_DOWNLOADER\*(C'\fR is defined, use it;
2302 abort if the specified program doesn\*(Aqt work. Possible values: \f(CW\*(C`lwp\*(C'\fR,
2303 \&\f(CW\*(C`curl\*(C'\fR, \f(CW\*(C`wget\*(C'\fR. The necessary options are added internally.
2304 .IP 2. 8
2305 If the environment variable \f(CW\*(C`TL_DOWNLOAD_PROGRAM\*(C'\fR is
2306 defined (can be any value), use it together with
2307 \&\f(CW\*(C`TL_DOWNLOAD_ARGS\*(C'\fR; abort if it doesn\*(Aqt work.
2308 .IP 3. 8
2309 If LWP is available and working, use that (by far the most
2310 efficient method, as it supports persistent downloads).
2311 .IP 4. 8
2312 If curl is available (from the system) and working, use that.
2313 .IP 5. 8
2314 If wget is available (either from the system or TL) and working, use that.
2315 .RE
2316 .RS 4
2317 .Sp
2318 TL provides \f(CW\*(C`wget\*(C'\fR binaries for platforms where necessary, so some
2319 download method should always be available.
2320 .RE
2321 .ie n .IP """TEXLIVE_PREFER_OWN""" 4
2322 .el .IP \f(CWTEXLIVE_PREFER_OWN\fR 4
2323 .IX Item "TEXLIVE_PREFER_OWN"
2324 By default, compression and download programs provided by the system,
2325 i.e., found along \f(CW\*(C`PATH\*(C'\fR are preferred over those shipped with TeX
2326 Live.
2327 .Sp
2328 This can create problems with systems that are too old, and so can be
2329 overridden by setting the environment variable \f(CW\*(C`TEXLIVE_PREFER_OWN\*(C'\fR to
2330 1. In this case, executables shipped with TL will be preferred.
2331 .Sp
2332 Extra compression/download programs not provided by TL, such as gzip,
2333 lwp, and curl, are still checked for on the system and used if
2334 available, per the above. \f(CW\*(C`TEXLIVE_PREFER_OWN\*(C'\fR only applies when the
2335 program being checked for is shipped with TL, namely the lz4 and
2336 xz compressors and wget downloader.
2337 .Sp
2338 Exception: on Windows, the \f(CW\*(C`tar.exe\*(C'\fR shipped with TL is always used,
2339 regardless of any setting.
2340 .SH "AUTHORS AND COPYRIGHT"
2341 .IX Header "AUTHORS AND COPYRIGHT"
2342 This script and its documentation were written for the TeX Live
2343 distribution (<https://tug.org/texlive>) and both are licensed under the
2344 GNU General Public License Version 2 or later.
2345 .PP
2346 \&\f(CW$Id:\fR tlmgr.pl 75204 2025\-05\-13 21:48:24Z karl $