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 general 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 could be done faster. When you need to install some piece of software, you 
search for it with apt-cache, copy package's name and paste it after apt-get 
install. That's not good - it's better to use bash-completion. But it still may 
be not enough; 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
	=================

Aptsh is a pseudo shell. It means that usage of Aptsh is similar to a normal 
shell, though results differ. :) While you use Bash for everything, Aptsh is 
used only for managing software installed on your system. In Aptsh there are 
available commands like install, remove or dist-upgrade - you 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 
just help if you are in Apt (a clue: pressing Tab twice in Aptsh doesn't list 
them all, I'll explain it later - just try to press Tab after typing 'queue' to 
see why). As you see, most of them are those old Apt commands, although they 
are typed in without 'apt-get' and 'apt-cache' before. And that's it - just 
typing 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.2. TAB completion
	===================

Without Tab completion, Aptsh would be like a car without the engine - you 
actually 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 same 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 one 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 space on your terminal by displaying only the master command. That * 
tells you that 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 command. 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 
one 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 
will 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 
available only for dpkg command. It handles all Dpkg's options (long, with -- 
and short, with -).


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

A list of commands that you have typed in is stored in Aptsh. You can access 
them with Up button. The list may be also kept in file, so it will be 
accessible even after Aptsh restart. If you want to disable the history, set 
use_history variable 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 one - it might be dangerous because the non-root users can read 
the file!), and history_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 
you know, that sometimes it's really hard to find the right package. In Aptsh, 
execpt the search command, which launches apt-cache search; and commands 
completion (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 
of files. So if you type in ls you will see running list of all available 
packages (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 often they are too complicated - except some situatuons. If you 
want to list all packages 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 
switch between normal and queue modes, type `. If you turned on the queue mode, 
the 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 = * 
aptsh>).


  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. 
Here'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 
arguments, you can give numbers of particular items or sections of them 
(queue-remove 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 one is queue-commit-say - it works similarily to the first one, except 
that it provides autoresponder (a mechanism which automatically responds to the 
commands' yes-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 
is 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 
breakline 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 
installed). 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 
answered n to the question. But the default answer was Y, so if we don't 
provide any 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 
require the orphaned package) installed on 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 
the deborphans program, though they are a little bit poorer (deborphans' source 
code 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 
textstring 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 
orphaned 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>





