From 9fd6772b202295d7f643bd94681428c0caffd026 Mon Sep 17 00:00:00 2001 From: David Kalnischkies Date: Tue, 20 Oct 2015 17:45:35 +0200 Subject: revamp apt(8) to refer more instead of duplicating As apt is targetted at users, lets try to make apt(8) for users as well by giving only a quick overview about what is available and some pointers for how to find a whole lot more details. --- doc/apt.8.xml | 209 ++++++++++++++++++++++++++++------------------------------ 1 file changed, 100 insertions(+), 109 deletions(-) (limited to 'doc/apt.8.xml') diff --git a/doc/apt.8.xml b/doc/apt.8.xml index 18b97f547..6e541b557 100644 --- a/doc/apt.8.xml +++ b/doc/apt.8.xml @@ -31,151 +31,142 @@ &synopsis-command-apt; Description - apt (Advanced Package Tool) is the - command-line tool for handling packages. It provides a commandline - interface for the package management of the system. - - See also &apt-get; and &apt-cache; for more low-level command options. + apt provides a high-level commandline interface for + the package management system. It is intended as an end user interface and + enables some options better suited for interactive usage by default + compared to more specialized APT tools like &apt-get; and &apt-cache;. + + Much like apt itself, its manpage is intended as an end + user interface and as such only mentions the most used commands and options + partly to not duplicate information in multiple places and partly to avoid + overwelming readers with a cornucopia of options and details. - - list is used to - display a list of packages. It supports shell pattern for matching - package names and the following options: - , - , - , - - are supported. - - - - - search searches for the given - term(s) and display matching packages. + (&apt-get;) + is used to download package + information from all configured sources. Other commands operate on + this data to e.g. perform package upgrades or search in and display + details about all packages available for installation. - - show shows the package information - for the given package(s). + (&apt-get;) + is used to install available + upgrades of all packages currently installed on the system from the + sources configured via &sources-list;. New packages will be + installed if required to statisfy dependencies, but existing + packages will never be removed. If an upgrade for a package requires + the remove of an installed package the upgrade for this package + isn't performed. - - - install is followed by one or more - package names desired for installation or upgrading. - - - A specific version of a package can be selected for installation by - following the package name with an equals and the version of the package - to select. This will cause that version to be located and selected for - install. Alternatively a specific distribution can be selected by - following the package name with a slash and the version of the - distribution or the Archive name (stable, testing, unstable). - + (&apt-get;) + full-upgrade performs the function of + upgrade but will remove currently installed packages if this is + needed to upgrade the system as a whole. + - - remove is identical to install except that packages are - removed instead of installed. Note that removing a package leaves its - configuration files on the system. If a plus sign is appended to the package - name (with no intervening space), the identified package will be - installed instead of removed. + , , (&apt-get;) + Performs the requested action on one or more packages + specified via ®ex;, &glob; or exact match. The requested action + can be overidden for specific packages by append a plus (+) to the + package name to install this package or a minus (-) to remove it. + + A specific version of a package can be selected for installation by + following the package name with an equals (=) and the version of the + package to select. Alternatively the version from a specific release can be + selected by following the package name with a forward slash (/) and + codename (&stable-codename;, &testing-codename;, sid …) or suite name (stable, + testing, unstable). This will also select versions from this release + for dependencies of this package if needed to satisfy the request. + + Removing a package removes all packaged data, but leaves usually + small (modified) user configuration files behind, in case the + remove was an accident. Just issuing an installtion request for the + accidently removed package will restore it funcation as before in + that case. On the other hand you can get right of these leftovers + via calling purge even on already removed + packages. Note that this does not effect any data or configuration + stored in your home directory. + - (and the alias since 1.1) - autoremove is used to remove packages that were automatically - installed to satisfy dependencies for other packages and are now no longer needed. + (&apt-get;) + + autoremove is used to remove packages that were + automatically installed to satisfy dependencies for other packages + and are now no longer needed as dependencies changed or the package(s) + needing them were removed in the meantime. + + Try to ensure that the list does not include applications you have + grown to like even through they there once installed just as a + dependency of another package. You can mark such a package as manually + installed by using &apt-mark;. Packages which you have installed explicitly + via install are never proposed for automatic removal as well. + - - edit-sources lets you edit - your sources.list file and provides basic sanity checks. + (&apt-cache;) + can be used to search for the given + ®ex; term(s) in the list of the available packages and display + matches. This can e.g. be useful if you are looking for packages + having a specific feature. If you are looking for a package + including a specific file try &apt-file;. - - update is used to - resynchronize the package index files from their sources. + (&apt-cache;) + Show information about the given package(s) including + its dependencies, installation and download size, sources the + package is available from, the description of the packages content + and many more. It can e.g. be helpful to look at this information + before allowing &apt; to remove a package or while searching for + new packages to install. - - - upgrade is used to install the - newest versions of all packages currently installed on the system - from the sources enumerated in - /etc/apt/sources.list. New packages will be - installed, but existing packages will never be removed. + + (work-in-progress) + is somewhat similar to dpkg-query --list + in that it can display a list of packages satisfying certain + criteria. It supports &glob; patterns for matching package names as + well as options to list installed (), + upgradeable () or all available + () versions. - - full-upgrade performs the - function of upgrade but may also remove installed packages - if that is required in order to resolve a package conflict. + (work-in-progress) + edit-sources lets you edit + your &sources-list; files in your preferred texteditor while also + providing basic sanity checks. - - options - &apt-cmdblurb; - - - - &apt-commonoptions; - - - - Script usage + Script usage and Differences to other APT tools The &apt; commandline is designed as a end-user tool and it may - change the output between versions. While it tries to not break - backward compatibility there is no guarantee for it either. - All features of &apt; are available in &apt-cache; and &apt-get; - via APT options. Please prefer using these commands in your scripts. - - - - Differences to &apt-get; - The apt command is meant to be pleasant for - end users and does not need to be backward compatible like - &apt-get;. Therefore some options are different: - - - - The option DPkg::Progress-Fancy is enabled. - - - - The option APT::Color is enabled. - - - - A new list command is available - similar to dpkg --list. - - - - The option upgrade has - --with-new-pkgs enabled by default. - - - - - - + change behaviour between versions. While it tries to not break + backward compatibility there is no guarantee for it either if it + seems benefitial for interactive use. + + All features of &apt; are available in dedicated APT tools like &apt-get; + and &apt-cache; as well. &apt; just changes the default value of some + options (see &apt-conf; and specifically the Binary scope). So prefer using + these commands (potentially with some additional options enabled) in your + scripts as they keep backward compatibility as much as possible. + See Also &apt-get;, &apt-cache;, &sources-list;, - &apt-conf;, &apt-config;, + &apt-conf;, &apt-config;, The APT User's guide in &guidesdir;, &apt-preferences;, the APT Howto. -- cgit v1.2.3