po: Update German man pages translation
[dpkg.git] / man / dselect.pod
blob8f8ce225e1db577edeafaa27c8db8b4914b489fc
1 # dselect manual page - dselect(1)
3 # Copyright © 1995 Juho Vuori <javuori@cc.helsinki.fi>
4 # Copyright © 2000 Josip Rodin
5 # Copyright © 2001 Joost Kooij
6 # Copyright © 2001 Wichert Akkerman <wakkerma@debian.org>
7 # Copyright © 2010-2015 Guillem Jover <guillem@debian.org>
9 # This is free software; you can redistribute it and/or modify
10 # it under the terms of the GNU General Public License as published by
11 # the Free Software Foundation; either version 2 of the License, or
12 # (at your option) any later version.
14 # This is distributed in the hope that it will be useful,
15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17 # GNU General Public License for more details.
19 # You should have received a copy of the GNU General Public License
20 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
22 =encoding utf8
24 =head1 NAME
26 dselect - Debian package management frontend
28 =head1 SYNOPSIS
30 B<dselect>
31 [I<option>...] [I<command>...]
33 =head1 DESCRIPTION
35 B<dselect>
36 is one of the primary user interfaces for managing packages on a Debian
37 system.
38 At the B<dselect> main menu, the system administrator can:
40 =over
42 =item *
44 Update the list of available package versions,
46 =item *
48 View the status of installed and available packages,
50 =item *
52 Alter package selections and manage dependencies,
54 =item *
56 Install new packages or upgrade to newer versions.
58 =back
60 B<dselect>
61 operates as a front-end to L<dpkg(1)>, the low-level Debian package
62 handling tool.
63 It features a full-screen package selections manager with package depends
64 and conflicts resolver.
65 When run with administrator privileges, packages can be installed,
66 upgraded and removed.
67 Various
68 access methods can be configured to retrieve available package version
69 information and installable packages from package repositories.
70 Depending on the used access method, these repositories can be public
71 archive servers on the internet, local archive servers or media discs.
72 The recommended access method is I<apt>, which is provided by the
73 package L<apt(8)>.
75 Normally B<dselect> is invoked without parameters.
76 An interactive menu is presented, offering the user a list of commands.
77 If a command is given as argument, then that command is started immediately.
78 Several
79 command line parameters are still available to modify the running behaviour
80 of B<dselect> or show additional information about the program.
82 =head1 OPTIONS
84 All options can be specified both on the command line and in the B<dselect>
85 configuration file I<%PKGCONFDIR%/dselect.cfg> or the files on the
86 configuration directory I<%PKGCONFDIR%/dselect.cfg.d/>.
87 Each line in the
88 configuration file is either an option (exactly the same as the
89 command line option but without leading hyphens) or a comment (if it starts
90 with a ‘B<#>’).
92 =over
94 =item B<--admindir> I<directory>
96 Changes the directory where the dpkg ‘I<status>’,
97 ‘I<available>’ and similar files are located.
98 Defaults to I<%ADMINDIR%> if B<DPKG_ADMINDIR> has not been set.
100 =item B<--instdir> I<directory>
102 Set the installation directory, which refers to the directory where
103 packages get installed (since dpkg 1.21.2).
104 Defaults to «I</>» if B<DPKG_ROOT> has not been set.
106 =item B<--root> I<directory>
108 Set the root directory to I<directory>, which sets the installation
109 directory to «I<directory>» and the administrative
110 directory to «I<directory>%ADMINDIR%» (since dpkg 1.21.0).
112 =item B<-D>I<file>, B<--debug> I<file>
114 Turn on debugging.
115 Debugging information is sent to I<file>.
117 =item B<--expert>
119 Turns on expert mode, i.e. doesn't display possibly annoying help
120 messages.
122 =item B<--color> I<screenpart>:[I<foreground>],[I<background>][:I<attr>[I<+attr>]...]
124 =item B<--colour> I<screenpart>:[I<foreground>],[I<background>][:I<attr>[I<+attr>]...]
126 Configures screen colors.
127 This works only if your display supports colors.
128 This option may be used multiple times (and is best used in
129 I<dselect.cfg>).
130 Each use changes the color (and optionally, other
131 attributes) of one part of the screen.
132 The parts of the screen (from top to bottom) are:
134 =over
136 =item B<title>
138 The screen title.
140 =item B<listhead>
142 The header line above the list of packages.
144 =item B<list>
146 The scrolling list of packages (and also some help text).
148 =item B<listsel>
150 The selected item in the list.
152 =item B<pkgstate>
154 In the list of packages, the text indicating the current state of each
155 package.
157 =item B<pkgstatesel>
159 In the list of packages, the text indicating the current state of the
160 currently selected package.
162 =item B<infohead>
164 The header line that displays the state of the currently selected package.
166 =item B<infodesc>
168 The package's short description.
170 =item B<info>
172 Used to display package info such as the package's description.
174 =item B<infofoot>
176 The last line of the screen when selecting packages.
178 =item B<query>
180 Used to display query lines
182 =item B<helpscreen>
184 Color of help screens.
186 =back
188 After the part of the screen comes a colon and the color specification.
190 can specify either the foreground color, the background color, or both,
191 overriding the compiled-in colors.
192 Use standard curses color names.
194 Optionally, after the color specification is another colon, and an
195 attribute specification.
196 This is a list of one or more attributes,
197 separated by plus (‘+’) characters.
198 Available attributes include (not all of these will work on all terminals):
199 B<normal>, B<standout>, B<underline>, B<reverse>, B<blink>,
200 B<bright>, B<dim>, B<bold>
202 =item B<-?>, B<--help>
204 Print a brief help text and exit successfully.
206 =item B<--version>
208 Print version information and exit successfully.
210 =back
212 =head1 COMMANDS
214 When
215 B<dselect>
216 is started it can perform the following commands, either directly if it
217 was specified on the command line or by prompting the user with a menu
218 of available commands if running interactively:
220 =head2 access
222 Choose and configure an access method to access package repositories.
224 By default, B<dselect> provides several methods such
225 as I<media>, I<file> or I<ftp>, but other
226 packages may provide additional methods, for example the I<apt> access method
227 provided by the L<apt(8)> package.
229 The use of the I<apt> access method is strongly recommended.
231 =head2 update
233 Refresh the available packages database.
235 Retrieves a list of available package versions from the package
236 repository, configured for the current access method, and update
237 the dpkg database.
238 The package lists are commonly provided by the
239 repository as files named I<Packages> or I<Packages.gz>.
240 These files can be generated by repository maintainers, using the
241 program L<dpkg-scanpackages(1)>.
243 Details of the update command depend on the access method's implementation.
244 Normally the process is straightforward and requires no user interaction.
246 =head2 select
248 View or manage package selections and dependencies.
250 This is the main function of B<dselect>.
251 In the select screen,
252 the user can review a list of all available and installed packages.
253 When run
254 with administrator privileges, it is also possible to interactively
255 change packages selection state.
256 B<dselect> tracks the implications
257 of these changes to other depending or conflicting packages.
259 When a conflict or failed depends is detected, a dependency resolution
260 subscreen is prompted to the user.
261 In this screen, a list of conflicting
262 or depending packages is shown, and for each package listed, the reason
263 for its listing is shown.
264 The user may apply the suggestions proposed
265 by B<dselect>, override them, or back out all the changes, including
266 the ones that created the unresolved depends or conflicts.
268 The use of the interactive package selections management screen is
269 explained in more detail below.
271 =head2 install
273 Installs selected packages.
275 The configured access method will fetch installable or upgradable packages
276 from the relevant repositories and install these using B<dpkg>.
277 Depending on the implementation of the access method, all packages can
278 be prefetched before installation, or fetched when needed.
279 Some access methods may also remove packages that were marked for removal.
281 If an error occurred during install, it is usually advisable to run
282 install again.
283 In most cases, the problems will disappear or be solved.
284 If problems persist or the installation performed was incorrect, please
285 investigate into the causes and circumstances, and file a bug in the
286 Debian bug tracking system.
287 Instructions on how to do this can be found
288 at L<https://bugs.debian.org/> or by reading the documentation
289 for L<bug(1)> or L<reportbug(1)>, if these are installed.
291 Details of the install command depend on the access method's implementation.
292 The user's attention and input may be required during installation,
293 configuration or removal of packages.
294 This depends on the maintainer scripts in the package.
295 Some packages make use of the L<debconf(1)>
296 library, allowing for more flexible or even automated installation
297 setups.
299 =head2 config
301 Configures any previously installed, but not fully configured packages.
303 =head2 remove
305 Removes or purges installed packages, that are marked for removal.
307 =head2 quit
309 Quit B<dselect>.
311 Exits the program with zero (successful) error code.
313 =head1 PACKAGE SELECTIONS MANAGEMENT
315 =head2 Introduction
317 B<dselect>
318 directly exposes
319 the administrator to some of the complexities involved with managing
320 large sets of packages with many interdependencies.
321 For a user who is
322 unfamiliar with the concepts and the ways of the Debian package management
323 system, it can be quite overwhelming.
324 Although B<dselect> is aimed
325 at easing package management and administration, it is only instrumental
326 in doing so and cannot be assumed to be a sufficient substitute for
327 administrator skill and understanding.
328 The user is required to
329 be familiar with the concepts underlying the Debian packaging system.
330 In case of doubt, consult the L<dpkg(1)> manual page and the distribution
331 policy.
333 Unless B<dselect> is run in expert
334 or immediate mode, a help screen is first displayed when choosing this
335 command from the menu.
336 The user is I<strongly> advised to study all of
337 the information presented in the online help screens, when one pops up.
338 The online help screens can at any time be invoked with the ‘B<?>’ key.
340 =head2 Screen layout
342 The select screen is by default split in a top and a bottom half.
343 The top half shows a list of packages.
344 A cursor bar can select an
345 individual package, or a group of packages, if applicable, by selecting
346 the group header.
347 The bottom half of the screen shows some details
348 about the package currently selected in the top half of the screen.
349 The type of detail that is displayed can be varied.
351 Pressing the ‘B<I>’ key toggles a full-screen display of the packages
352 list, an enlarged view of the package details, or the equally split screen.
354 =head2 Package details view
356 The package details view by default shows the extended package description
357 for the package that is currently selected in the packages status list.
358 The type of detail can be toggled by pressing the ‘B<i>’ key.
359 This alternates between:
361 =over
363 =item *
365 the extended description
367 =item *
369 the control information for the installed version
371 =item *
373 the control information for the available version
375 =back
377 In a dependency resolution screen, there is also the possibility of
378 viewing the specific unresolved depends or conflicts related to the
379 package and causing it to be listed.
381 =head2 Packages status list
383 The main select screen displays a list of all packages known to the Debian
384 package management system.
385 This includes packages installed on the system
386 and packages known from the available packages database.
388 For every package, the list shows the package's status, priority, section,
389 installed and available architecture, installed and available versions,
390 the package name and its short description, all in one line.
391 By pressing the ‘B<A>’ key, the display of the installed and
392 available architecture can be toggled between on an off.
393 By pressing the ‘B<V>’ key, the display of the installed and
394 available version can be toggled between on an off.
395 By pressing the ‘B<v>’ key, the package status display is toggled
396 between verbose and shorthand.
397 Shorthand display is the default.
399 The shorthand status indication consists
400 of four parts: an error flag, which should normally be clear, the
401 current status, the last selection state and the current selection state.
402 The first two relate to the actual state of the package, the second pair
403 are about the selections set by the user.
405 These are the meanings of the shorthand package status indicator codes:
407 =over
409 Error flag:
411 =over
413 =item I<empty>   no error
415 =item B<R>       serious error, needs reinstallation;
417 =back
419 Installed state:
421 =over
423 =item I<empty>   not installed;
425 =item B<*>       fully installed and configured;
427 =item B<->       not installed but some config files may remain;
429 =item B<U>       unpacked but not yet configured;
431 =item B<C>       half-configured (an error happened);
433 =item B<I>       half-installed (an error happened).
435 =back
437 Current and requested selections:
439 =over
441 =item B<*>       marked for installation or upgrade;
443 =item B<->       marked for removal, configuration files remain;
445 =item B<=>       on hold: package will not be processed at all;
447 =item B<_>       marked for purge, also remove configuration;
449 =item B<n>       package is new and has yet to be marked.
451 =back
453 =back
455 =head2 Cursor and screen movement
457 The package selection list and the dependency conflict
458 resolution screens can be navigated using motion
459 commands mapped to the following keys:
461 =over
463 =over
465 =item B<p, Up, k>           move cursor bar up
467 =item B<n, Down, j>         move cursor bar down
469 =item B<P, Pgup, Backspace> scroll list 1 page up
471 =item B<N, Pgdn, Space>     scroll list 1 page down
473 =item B<^p>                 scroll list 1 line up
475 =item B<^n>                 scroll list 1 line down
477 =item B<t, Home>            jump to top of list
479 =item B<e, End>             jump to end of list
481 =item B<u>                  scroll info 1 page up
483 =item B<d>                  scroll info 1 page down
485 =item B<^u>                 scroll info 1 line up
487 =item B<^d>                 scroll info 1 line down
489 =item B<B, Left-arrow>      pan display 1/3 screen left
491 =item B<F, Right-arrow>     pan display 1/3 screen right
493 =item B<^b>                 pan display 1 character left
495 =item B<^f>                 pan display 1 character right
497 =back
499 =back
501 =head2 Searching and sorting
503 The list of packages can be searched by package name.
504 This
505 is done by pressing ‘B</>’, and typing a simple search
506 string.
507 The string is interpreted as a
508 L<regex(7)>
509 regular expression.
510 If you add ‘B</d>’ to the search expression, dselect will also
511 search in descriptions.
512 If you add ‘B</i>’ the search will be case insensitive.
513 You may combine these two suffixes like this: ‘B</id>’.
514 Repeated searching is accomplished by repeatedly pressing the
515 ‘B<n>’ or ‘B<\>’ keys, until the wanted package is found.
516 If the search reaches the bottom of the list, it wraps to the top
517 and continues searching from there.
519 The list sort order can be varied by pressing
520 the ‘B<o>’ and ‘B<O>’ keys repeatedly.
521 The following nine sort orderings can be selected:
523 =over
525 =over
527 =item B<alphabet>
529 =item B<priority+section>
531 =item B<section+priority>
533 =item B<available>
535 =item B<available+priority>
537 =item B<available+section>
539 =item B<status>
541 =item B<status+priority>
543 =item B<status+section>
545 =back
547 =back
549 Where not listed above explicitly, alphabetic order is used as
550 the final subordering sort key.
552 =head2 Altering selections
554 The requested selection state of individual packages may be
555 altered with the following commands:
557 =over
559 =over
561 =item B<+, Insert>    install or upgrade
563 =item B<=, H>         hold in present state and version
565 =item B<:, G>         unhold: upgrade or leave uninstalled
567 =item B<-, Delete>    remove, but leave configuration
569 =item B<_>            remove & purge configuration
571 =back
573 =back
575 When the change request results in one or more unsatisfied depends
576 or conflicts, B<dselect> prompts the user with a dependency resolution
577 screen.
578 This will be further explained below.
580 It is also possible to apply these commands to groups of package
581 selections, by pointing the cursor bar onto a group header.
583 exact grouping of packages is dependent on the current list ordering
584 settings.
586 Proper care should be taken when altering large groups of selections,
587 because this can instantaneously create large numbers of unresolved
588 depends or conflicts, all of which will be listed in one dependency
589 resolution screen, making them very hard to handle.
590 In practice,
591 only hold and unhold operations are useful when applied to groups.
593 =head2 Resolving depends and conflicts
595 When the change request results in one or more unsatisfied depends
596 or conflicts, B<dselect> prompts the user with a dependency resolution
597 screen.
598 First however, an informative help screen is displayed.
600 The top half of this screen lists all the packages that will have
601 unresolved depends or conflicts, as a result of the requested change,
602 and all the packages whose installation can resolve any of these
603 depends or whose removal can resolve any of the conflicts.
604 The bottom half defaults to show the depends or conflicts that
605 cause the currently selected package to be listed.
607 When the sublist of packages is displayed initially, B<dselect>
608 may have already set the requested selection status of some of the
609 listed packages, in order to resolve the depends or conflicts that
610 caused the dependency resolution screen to be displayed.
611 Usually,
612 it is best to follow up the suggestions made by B<dselect>.
614 The listed packages' selection state may be reverted to the original
615 settings, as they were before the unresolved depends or conflicts
616 were created, by pressing the ‘B<R>’ key.
617 By pressing the ‘B<D>’ key, the automatic suggestions are reset,
618 but the change that caused the dependency resolution screen to be prompted
619 is kept as requested.
620 Finally, by pressing ‘B<U>’, the selections are again set to the
621 automatic suggestion values.
623 =head2 Establishing the requested selections
625 By pressing B<enter>, the currently displayed set of selections
626 is accepted.
627 If B<dselect> detects no unresolved depends as a result
628 of the requested selections, the new selections will be set.
629 However, if there are any unresolved depends, B<dselect> will again
630 prompt the user with a dependency resolution screen.
632 To alter a set of selections that creates unresolved depends or
633 conflicts and forcing B<dselect> to accept it, press the ‘B<Q>’
634 key.
635 This sets the selections as specified by the user, unconditionally.
636 Generally, don't do this unless you've read
637 the fine print.
639 The opposite effect, to back out any selections change requests and
640 go back to the previous list of selections, is attained by pressing
641 the ‘B<X>’ or B<escape> keys.
642 By repeatedly pressing these
643 keys, any possibly detrimental changes to the requested package
644 selections can be backed out completely to the last established
645 settings.
647 If you mistakenly establish some settings and wish to revert all the
648 selections to what is currently installed on the system, press the
649 ‘B<C>’ key.
650 This is somewhat similar to using the unhold command on all packages,
651 but provides a more obvious panic button in cases where the user
652 pressed B<enter> by accident.
654 =head1 EXIT STATUS
656 =over
658 =item B<0>
660 The requested command was successfully performed.
662 =item B<2>
664 Fatal or unrecoverable error due to invalid command-line usage, or
665 interactions with the system, such as accesses to the database,
666 memory allocations, etc.
668 =back
670 =head1 ENVIRONMENT
672 =over
674 =item B<DPKG_ROOT>
676 If set and the B<--instdir> or B<--root> options have not been specified,
677 it will be used as the filesystem root directory (since dpkg 1.21.0).
679 =item B<DPKG_ADMINDIR>
681 If set and the B<--admindir> or B<--root> option have not been specified,
682 it will be used as the B<dpkg> database directory (since dpkg 1.21.0).
684 =item B<HOME>
686 If set, B<dselect> will use it as the directory from which to read the
687 user specific configuration file.
689 =back
691 =head1 BUGS
694 B<dselect>
695 package selection interface is confusing to some new users.
696 Reportedly, it even makes seasoned kernel developers cry.
698 The documentation is lacking.
700 There is no help option in the main menu.
702 The visible list of available packages cannot be reduced.
704 The built in access methods can no longer stand up to current quality
705 standards.
706 Use the access method provided by L<apt(8)>, it is not only not
707 broken, it is also much more flexible than the built in access methods.
709 =head1 SEE ALSO
711 L<dpkg(1)>,
712 L<apt(8)>,
713 L<sources.list(5)>,
714 L<deb(5)>.