Aptsh Howto
by Marcin Wrochniak
<wrochniak at gmail.com>


  1. Introduction
  ===============


	1.1. Note
	=========

Note that some technical details may differ on your system, for example your GNU
 Readline library might be configured differently or your locales might be other
 (en_US is used in examples, although author personally uses pl_PL). But the gen
eral behaviour of Aptsh shouldn't differ too much.


	1.2. Apt
	========

If you read this, then you probably know what Apt is. And I hope you like it; if
 not, you will after reading this text. :)

So you're an Apt user. Your daily work doesn't require launching apt-get or apt-
cache too often. But from time to time it does, and then in consumes much time..
. well, maybe not as much as it would take without Apt, but you know that it cou
ld be done faster. When you need to install some piece of software, you search f
or it with apt-cache, copy package's name and paste it after apt-get install. Th
at's not good - it's better to use bash-completion. But it still may be not enou
gh; if so, try Aptsh. Of course, Aptsh is not just bash-completion rewritten in 
a mixture of C and C++. Beside tab-completion it can speed up your work in many 
other ways - just read further. 


	1.3. Pseudo-shell
	=================

The center of Aptsh is its pseudo-shell. It means that usage of Aptsh in shell-m
ode is similar to a normal shell, though results differ. :) While you use Bash f
or everything, Aptsh is used only for managing software installed on your system
. In Aptsh there are available commands like install, remove or dist-upgrade - y
ou know them from Apt.


  2. Usage
  ========


	2.1. Basics
	===========

If you want to see all commands available in Aptsh, they are in man aptsh, or ju
st help if you are in Aptsh's shell (a clue: pressing Tab twice in Aptsh doesn't
 list them all, I'll explain it later - just try to press Tab after typing 'queu
e' to see why). As you see, most of them are those old Apt commands, although th
ey are typed in without 'apt-get' and 'apt-cache' before. And that's it - just t
yping Apt commands directly after prompt.
Some examples:


  vrok@ankh ~ $ sudo aptsh
  Reading commands history...
  Generating and mapping caches...
  
  aptsh> remove xterm
  Reading package lists... Done
  Building dependency tree... Done
  The following packages will be REMOVED:
    xterm
  0 upgraded, 0 newly installed, 1 to remove and 32 not upgraded.
  Need to get 0B of archives.
  After unpacking 1188kB disk space will be freed.
  Do you want to continue [Y/n]? n
  Abort.
  Generating and mapping caches...
  
  aptsh> install xterm
  Reading package lists... Done
  Building dependency tree... Done
  xterm is already the newest version.
  0 upgraded, 0 newly installed, 0 to remove and 32 not upgraded.
  Generating and mapping caches...
  
  aptsh> show package_that_doesnt_exist
  W: Unable to locate package package_that_doesnt_exist
  E: No packages found
  
  aptsh> quit
  vrok@ankh ~ $


In example above you see how to launch Aptsh (with root privileges - that's the 
sudo thing), then you see effects of four Aptsh commands: remove, install, show 
and quit.


		2.1.1. Shell-mode is not a must
		===============================

Aptsh has a few features besides pseudo-shell which might appear usable to you, 
though you not necessarily must like the pseudo-shell (or you'd like to use thes
e features in your script, etc.). Aptsh can be used as a typical console program
 - in this mode you would use it like apt-get or apt-cache. Here's an example:


  bash:~# aptsh search frozen bubble
  fb-music-high - High quality, large music files for Frozen-Bubble
  fb-music-low - Lower quality, small music files for Frozen-Bubble
  frozen-bubble - Pop out the bubbles !
  frozen-bubble-data - Data files for Frozen-Bubble
  junior-puzzle - Debian Jr. Puzzles
  
  bash:~# aptsh install frozen-bubble
  Reading package lists... Done
  Building dependency tree
  Reading state information... Done
  frozen-bubble is already the newest version.
  0 upgraded, 0 newly installed, 0 to remove and 143 not upgraded.
  
  bash:~# aptsh orphans
  libreadline5-dev
  gstreamer0.10-plugins-bad-multiverse
  gstreamer0.10-plugins-ugly-multiverse
  
  bash:~#



		2.1.2. Looking for help
		=======================

Help connected with Aptsh can be found, besides this document, in the Aptsh manp
age and in help command. Since you probably know how to use the manpage, I will 
only explain how to use the help command.

If you just run help command, then it will launch Aptsh manpage++Looking for hel
p++
Help connected with Aptsh can be found, besides this document, in the Aptsh manp
age and in help command. Since you probably know how to use the manpage, I will 
only explain how to use the help command.

If you just run help command, then it will launch Aptsh manpage. But if you laun
ch it with names of some commands, then you will see short descriptions of these
 commands. Example:


  aptsh> help orphans orphans-all install remove help
  orphans      List libraries not required by any installed package
  orphans-all  List packages not required by any other installed package
  install      Install (or upgrade) one or more packages or .deb files
  remove       Remove one or more packages (see also purge)
  help         Display short info about given commands, or Aptsh's manpage (if n
o arguments)
  
  aptsh>



	2.2. TAB completion
	===================

Without Tab completion, Aptsh would be like a car without the engine - you actua
lly can use in the Flinstone way, but it's simpler just to walk.

If you use the Unix shell, you probably know what the headline of this paragraph
 means (Yes, there are shells without Tab completion, but nowadays it's just as 
basic as a cup of coffee in the morning). Tab completion in Aptsh works in the s
ame way, except it usually lists matching packages, not files.


		2.2.1. Commands completion
		==========================

But let's get down to the business... First sort of completion is used for Aptsh
 commands. You may expect that there actually is nothing special to say, but it'
s no so simple. There are groups of commands serving to similar tasks, like help
 and help-howto. First one displays typical Unix manual page for Aptsh, second o
ne displays this document.

See this:


  aptsh>
  add              dump             policy           source
  autoclean        dump-cfg         queue*           stats
  build-dep        dumpavail        quit             unmet
  check            help             rdepends         update
  clean            install          remove           upgrade
  depends          listfiles        rls              whatis
  dist-upgrade     ls               search           whichpkg
  dotty            madison          show
  dpkg             orphans*         showpkg
  dselect-upgrade  pkgnames         showsrc
  
  aptsh>


There's nothing about help-howto, just help (plus a * character). As you already
 know, these two funtions compose a group. Grouping of commands serves to save s
pace on your terminal by displaying only the master command. That * tells you th
at it's just a master (root) of a command group. Of course, completion works for
 all commands, not only these basic; you just have to type in the whole master c
ommand. Just see this:


  aptsh> help (TAB pressed twice)
  help  help-howto
  aptsh> help


It works! :) And it doesn't show any star sign, because now only members of a on
e group are being shown. You can check other groups, like queue or orphans.


		2.2.2. Packages completion
		==========================

Second type of completion is used for packages. This one is very simple, it's in
 the old Bash style. Of course, when you want to install some packages, Aptsh wi
ll prompt you all available packages; and only installed when removing. As usual
, some examples.


  aptsh> install (TAB pressed twice)
  Display all 20571 possibilities? (y or n)
  
  aptsh> remove (TAB pressed twice)
  Display all 1038 possibilities? (y or n)
  
  aptsh> install kde (TAB pressed twice)
  Display all 164 possibilities? (y or n)
  
  aptsh> install xterm (TAB pressed twice)
  xterm         xtermcontrol  xterminal     xtermset
  
  aptsh> install xterm



		2.2.3. Dpkg special completion
		==============================

The last one type of completion in Aptsh is very unique and (currently) is avail
able only for dpkg command. It handles all Dpkg's options (long, with -- and sho
rt, with -).


	2.3. Commands history
	=====================

A list of commands that you have typed in is stored in Aptsh. You can access the
m with Up button. The list may be also kept in file, so it will be accessible ev
en after Aptsh restart. If you want to disable the history, set use_history vari
able in aptsh.conf to 0. Other variables connected with history are history_file
 - it's a file where the commands list is saved (please do not use the default o
ne - it might be dangerous because the non-root users can read the file!), and h
istory_count - it's the number of commands you want to save to a file (if it's 0
, then history is not saved).


	2.4. Searching packages
	=======================


		2.4.1. Intro
		============

When you use a system like Debian with large numer of available packages, then y
ou know, that sometimes it's really hard to find the right package. In Aptsh, ex
ecpt the search command, which launches apt-cache search; and commands completio
n (which also may be considered as a kind of searching), there are few more ways
.


		2.4.2. ls
		=========

The ls command works like the normal ls, except that it lists packages instead o
f files. So if you type in ls you will see running list of all available package
s (you can pipe them to more or less - try to type ls | less). And if you use a 
wildcard - then you will see only packages equal to the wildcard (for instance, 
ls kde* will show only packages that begin with kde). Here's an example:


  aptsh> ls wmi*
  wmitime
  wmifs
  wmibam
  wmix
  wminet
  wmifinfo
  
  aptsh> ls wmi* | grep x$
  wmix
  
  aptsh> ls gnome*games
  gnome-card-games
  gnome-games
  
  aptsh>



		2.4.3. rls
		==========

ls command uses wildcards to find the packages, and rls uses regular expressions
 for the same job. Regular expressions are more powerful than wildcards, but oft
en they are too complicated - except some situatuons. If you want to list all pa
ckages with kde in their names, it's simpler to write rls kde than ls *kde*.


  aptsh> rls ^wmi
  wmitime
  wmifs
  wmibam
  wmix
  wminet
  wmifinfo
  
  aptsh> rls ^wmi.*x$
  wmix
  
  aptsh> rls ^gnome.*games$
  gnome-card-games
  gnome-games
  
  aptsh> rls irssi
  irssi-scripts
  irssi-snapshot
  irssi-common
  irssi-text
  xirssi
  irssi-snapshot-dev
  irssi
  irssi-plugin-icq
  
  aptsh>



	2.5. Command queue
	==================


		2.5.1. Switching between modes
		==============================

The command queue mechanism is a quite important part of Aptsh. When you are in 
the queue mode, all commands are only stored in memory, they are not executed at
 the time. They will be executed later, of course if you will launch them. To sw
itch between normal and queue modes, type `. If you turned on the queue mode, th
e prompt should change into the one that's specified in ps1_s variable in aptsh.
conf. If you turned on normal mode, prompt will change into ps1 variable.

Below is an example how to switch between modes (ps1 = aptsh> and ps1_s = * apts
h>).


  aptsh> show
  E: No packages found
  
  aptsh> `
  
  * aptsh> show
  
  * aptsh> `
  
  aptsh>



		2.5.2. Manipulating the queue
		=============================

A special commands group serves for command queue manipulation and execution. He
re's a list of commands connected with manipulation:

queue - Show the queue.

queue-clear - Clean the queue.

queue-remove - Remove commands from list (queue). Give commands' numbers as argu
ments, you can give numbers of particular items or sections of them (queue-remov
e 1 2 3 is correct as well as queue-remove 1-3).

A little example of how it works:


  aptsh> `
  
  * aptsh> rls
  
  * aptsh> ls
  
  * aptsh> show kde
  
  * aptsh> show gnome
  
  * aptsh> a
  Warning: Unknown command: a
  
  * aptsh> b
  Warning: Unknown command: b
  
  * aptsh> c
  Warning: Unknown command: c
  
  * aptsh> d
  Warning: Unknown command: d
  
  * aptsh> `
  
  aptsh> queue
  1: rls
  2: ls
  3: show kde
  4: show gnome
  5: a
  6: b
  7: c
  8: d
  
  aptsh> queue-remove 1 3 6-8
  
  aptsh> queue
  1: ls
  2: show gnome
  3: a
  
  aptsh> queue-clear
  
  aptsh> queue
  
  aptsh>



		2.5.3. Executing commands from queue
		====================================

Two commands are responsible for launching the command queue. First one, simpler
, is queue-commit. It just iterates through all commands in the queue. Second on
e is queue-commit-say - it works similarily to the first one, except that it pro
vides autoresponder (a mechanism which automatically responds to the commands' y
es-or-no questions).

queue-commit in action:


  aptsh> `
  
  * aptsh> remove xterm
  
  * aptsh> install xterm
  
  * aptsh> `
  
  aptsh> queue-commit
   >>> Doing step 1 of 2...
  Reading package lists... Done
  Building dependency tree... Done
  The following packages will be REMOVED:
    kubuntu-desktop xterm
  0 upgraded, 0 newly installed, 2 to remove and 44 not upgraded.
  Need to get 0B of archives.
  After unpacking 1221kB disk space will be freed.
  Do you want to continue [Y/n]? n
  Abort.
  Generating and mapping caches...
   >>> Doing step 2 of 2...
  Reading package lists... Done
  Building dependency tree... Done
  xterm is already the newest version.
  0 upgraded, 0 newly installed, 0 to remove and 44 not upgraded.
  Generating and mapping caches...
  
  aptsh>


This is fine, but it still requires user's activity. Sometimes you may not want 
to play with Apt's questions - if so, then use queue-commit-say command, which i
s provided with autoresponer. It's really simple to use: command's arguments are
 the answer to all questions (stdin of command-queue will be repeately feed with
 the arguments). If you don't provide any arguments, then Aptsh will use breakli
ne character as the answer, so in most cases the default actions will be taken (
for instance, if Apt asks you with [Y/n] (where Yes is the default one) or [y/N]
 (where No is the default one) question, then pressing Enter key will cause the 
default action). 

In example below, we try to remove and then install xterm (it's already installe
d). The autoresponer will answer n to Apt's question.


  aptsh> `
  * aptsh> remove xterm
  
  * aptsh> install xterm
  
  * aptsh> `
  
  aptsh> queue-commit-say n
   >>> Doing step 1 of 2...
  Reading package lists... Done
  Building dependency tree... Done
  The following packages will be REMOVED:
    xterm
  0 upgraded, 0 newly installed, 1 to remove and 42 not upgraded.
  Need to get 0B of archives.
  After unpacking 1188kB disk space will be freed.
  Do you want to continue [Y/n]? Abort.
  Generating and mapping caches...
   >>> Doing step 2 of 2...
  Reading package lists... Done
  Building dependency tree... Done
  xterm is already the newest version.
  0 upgraded, 0 newly installed, 0 to remove and 42 not upgraded.
  Generating and mapping caches...
  
  aptsh>


As you have just seen, it had neither removed nor installed xterm, because it an
swered n to the question. But the default answer was Y, so if we don't provide a
ny arguments to queue-commit-say, then Apt will decide for us and xterm will be 
removed.


  aptsh> queue
  1: remove xterm
  2: install xterm
  
  aptsh> queue-commit-say
   >>> Doing step 1 of 2...
  Reading package lists... Done
  Building dependency tree... Done
  The following packages will be REMOVED:
    xterm
  0 upgraded, 0 newly installed, 1 to remove and 42 not upgraded.
  Need to get 0B of archives.
  After unpacking 1188kB disk space will be freed.
  Do you want to continue [Y/n]? 
  (Reading database ... 76203 files and directories currently installed.)
  Removing xterm ...
  Generating and mapping caches...
   >>> Doing step 2 of 2...
  Reading package lists... Done
  Building dependency tree... Done
  Suggested packages:
    xfonts-cyrillic
  The following NEW packages will be installed:
    xterm
  0 upgraded, 1 newly installed, 0 to remove and 42 not upgraded.
  Need to get 0B/510kB of archives.
  After unpacking 1188kB of additional disk space will be used.
  Preconfiguring packages ...
  Selecting previously deselected package xterm.
  (Reading database ... 76183 files and directories currently installed.)
  Unpacking xterm (from .../xterm_6.8.2-10_i386.deb) ...
  Setting up xterm (6.8.2-10) ...
  Generating and mapping caches...
  
  aptsh>



	2.6. Orphaned packages
	======================


		2.6.1. Orphaned package?
		========================

Orphaned package is a package without any reverse dependencies (packages that re
quire the orphaned package) installed in the system.


		2.6.2. Orphans commands group
		=============================

The orphans commands group contains two commands: orphans and orphans-all. They 
both serve to locate orphaned packages on your system. They work similarily to t
he deborphans program, though they are a little bit poorer (deborphans' source c
ode couldn't have been acquired by Aptsh, because it's completely different).


		2.6.3. orphans command
		======================

The orphans command finds all orphaned packages which have libs or libdevel text
string in their Section field, so it actually should list all orphaned libraries
.

Why only libraries? Well, when you want to clean your system, you will probably 
want to remove unneeded libraries - and orphaned libraries are unneeded, unless 
you don't use them in programming or something. And you don't want to remove orp
haned programs, because you use them.

Example:


  aptsh> orphans
  libreadline5-dev
  liballegro4.1
  libsndfile1
  
  aptsh>



		2.6.4. orphans-all command
		==========================

But well, you may really want to see all orphaned packages, not only libraries. 
If so, use this command. Its output is a little bit different from the orphans' 
one - it produces two columns, first one contains the Section and second one the
 Name.

Example:


  aptsh> orphans-all
  python           python-crypto
  base             lilo
  python           python2.4-pycurl
  [...]
  libs             libsndfile1
  net              lftp
  
  aptsh>



	2.7. Other commands
	===================


		2.7.1. changelog, news
		======================

The changelog command retrieves changelogs for given packages from Debian server
s, and dumps them to standard output (you can give many names). news command is 
similar, but it dumps only the latest entry from the changelog. Both these comma
nds use external command (wget) to fetch files. Therefore, if you are behind a p
roxy server, you should configure wget to have this command working, BUT: wget c
onnects through proxy if its address is given in http_proxy shell variable, as w
ell as Apt does. Thus, if Apt works properly, these commands should work properl
y too.


		2.7.2. whatis
		=============

The whatis command lists short descriptions of given packages. You probably woul
d use it to check quickly what a package is and what it does. Here's a short exa
mple:


  aptsh> whatis aptsh
  aptsh: apt interactive shell
  
  aptsh> whatis apt dpkg kde
  apt: Advanced front-end for dpkg
  dpkg: package maintenance system for Debian
  kde: the K Desktop Environment official modules
  
  aptsh>



		2.7.3. toupgrade
		================

The toupgade dumps a list of packages installed on your system, which are availa
ble in newer versions. These are packages, which will be upgraded if you run the
 upgrade command.


		2.7.4. Other other commands
		===========================

If a command is not described here, then try to use the help command to get some
 information. It also may appear that it is just a wrapper for a feature of an e
xternal program, then probably more detailed description will be available in do
cumentation of the external program.