+ </sect3>
+ <sect3>
+ <title>Listing and deleting breakpoints</title>
+
+ <para>The list of breakpoints currently enabled can be displayed using
+ <literal>:show breaks</literal>:</para>
+<screen>
+*Main> :show breaks
+[0] Main qsort.hs:1:11-12
+[1] Main qsort.hs:2:15-46
+</screen>
+
+ <para>To delete a breakpoint, use the <literal>:delete</literal>
+ command with the number given in the output from <literal>:show breaks</literal>:</para>
+
+<screen>
+*Main> :delete 0
+*Main> :show breaks
+[1] Main qsort.hs:2:15-46
+</screen>
+
+ <para>To delete all breakpoints at once, use <literal>:delete *</literal>.</para>
+
+ </sect3>
+ </sect2>
+
+ <sect2 id="single-stepping">
+ <title>Single-stepping</title>
+
+ <para>Single-stepping is a great way to visualise the execution of your
+ program, and it is also a useful tool for identifying the source of a
+ bug. GHCi offers two variants of stepping. Use
+ <literal>:step</literal> to enable all the
+ breakpoints in the program, and execute until the next breakpoint is
+ reached. Use <literal>:steplocal</literal> to limit the set
+ of enabled breakpoints to those in the current top level function.
+ Similarly, use <literal>:stepmodule</literal> to single step only on
+ breakpoints contained in the current module.
+ For example:</para>
+
+<screen>
+*Main> :step main
+Stopped at qsort.hs:5:7-47
+_result :: IO ()
+</screen>
+
+ <para>The command <literal>:step
+ <replaceable>expr</replaceable></literal> begins the evaluation of
+ <replaceable>expr</replaceable> in single-stepping mode. If
+ <replaceable>expr</replaceable> is omitted, then it single-steps from
+ the current breakpoint. <literal>:stepover</literal>
+ works similarly.</para>
+
+ <para>The <literal>:list</literal> command is particularly useful when
+ single-stepping, to see where you currently are:</para>
+
+<screen>
+[qsort.hs:5:7-47] *Main> :list
+4
+5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
+6
+[qsort.hs:5:7-47] *Main>
+</screen>
+
+ <para>In fact, GHCi provides a way to run a command when a breakpoint is
+ hit, so we can make it automatically do
+ <literal>:list</literal>:</para>
+
+<screen>
+[qsort.hs:5:7-47] *Main> :set stop :list
+[qsort.hs:5:7-47] *Main> :step
+Stopped at qsort.hs:5:14-46
+_result :: [Integer]
+4
+5 main = print (qsort [8, 4, 0, 3, 1, 23, 11, 18])
+6
+[qsort.hs:5:14-46] *Main>
+</screen>
+ </sect2>
+
+ <sect2 id="nested-breakpoints">
+ <title>Nested breakpoints</title>
+ <para>When GHCi is stopped at a breakpoint, and an expression entered at
+ the prompt triggers a
+ second breakpoint, the new breakpoint becomes the “current”
+ one, and the old one is saved on a stack. An arbitrary number of
+ breakpoint contexts can be built up in this way. For example:</para>
+
+<screen>
+[qsort.hs:2:15-46] *Main> :st qsort [1,3]
+Stopped at qsort.hs:(1,0)-(3,55)
+_result :: [a]
+... [qsort.hs:(1,0)-(3,55)] *Main>
+</screen>
+
+ <para>While stopped at the breakpoint on line 2 that we set earlier, we
+ started a new evaluation with <literal>:step qsort [1,3]</literal>.
+ This new evaluation stopped after one step (at the definition of
+ <literal>qsort</literal>). The prompt has changed, now prefixed with
+ <literal>...</literal>, to indicate that there are saved breakpoints
+ beyond the current one. To see the stack of contexts, use
+ <literal>:show context</literal>:</para>
+
+<screen>
+... [qsort.hs:(1,0)-(3,55)] *Main> :show context
+--> main
+ Stopped at qsort.hs:2:15-46
+--> qsort [1,3]
+ Stopped at qsort.hs:(1,0)-(3,55)
+... [qsort.hs:(1,0)-(3,55)] *Main>
+</screen>
+
+ <para>To abandon the current evaluation, use
+ <literal>:abandon</literal>:</para>
+
+<screen>
+... [qsort.hs:(1,0)-(3,55)] *Main> :abandon
+[qsort.hs:2:15-46] *Main> :abandon
+*Main>
+</screen>
+ </sect2>
+
+ <sect2 id="ghci-debugger-result">
+ <title>The <literal>_result</literal> variable</title>
+ <para>When stopped at a breakpoint or single-step, GHCi binds the
+ variable <literal>_result</literal> to the value of the currently
+ active expression. The value of <literal>_result</literal> is
+ presumably not available yet, because we stopped its evaluation, but it
+ can be forced: if the type is known and showable, then just entering
+ <literal>_result</literal> at the prompt will show it. However,
+ there's one caveat to doing this: evaluating <literal>_result</literal>
+ will be likely to trigger further breakpoints, starting with the
+ breakpoint we are currently stopped at (if we stopped at a real
+ breakpoint, rather than due to <literal>:step</literal>). So it will
+ probably be necessary to issue a <literal>:continue</literal>
+ immediately when evaluating <literal>_result</literal>. Alternatively,
+ you can use <literal>:force</literal> which ignores breakpoints.</para>
+ </sect2>
+
+ <sect2 id="tracing">
+ <title>Tracing and history</title>
+
+ <para>A question that we often want to ask when debugging a program is
+ “how did I get here?”. Traditional imperative debuggers
+ usually provide some kind of stack-tracing feature that lets you see
+ the stack of active function calls (sometimes called the “lexical
+ call stack”), describing a path through the code
+ to the current location. Unfortunately this is hard to provide in
+ Haskell, because execution proceeds on a demand-driven basis, rather
+ than a depth-first basis as in strict languages. The
+ “stack“ in GHC's execution engine bears little
+ resemblance to the lexical call stack. Ideally GHCi would maintain a
+ separate lexical call stack in addition to the dynamic call stack, and
+ in fact this is exactly
+ what our profiling system does (<xref linkend="profiling" />), and what
+ some other Haskell debuggers do. For the time being, however, GHCi
+ doesn't maintain a lexical call stack (there are some technical
+ challenges to be overcome). Instead, we provide a way to backtrack from a
+ breakpoint to previous evaluation steps: essentially this is like
+ single-stepping backwards, and should in many cases provide enough
+ information to answer the “how did I get here?”
+ question.</para>
+
+ <para>To use tracing, evaluate an expression with the
+ <literal>:trace</literal> command. For example, if we set a breakpoint
+ on the base case of <literal>qsort</literal>:</para>
+
+<screen>
+*Main> :list qsort
+1 qsort [] = []
+2 qsort (a:as) = qsort left ++ [a] ++ qsort right
+3 where (left,right) = (filter (<=a) as, filter (>a) as)
+4
+*Main> :b 1
+Breakpoint 1 activated at qsort.hs:1:11-12
+*Main>
+</screen>
+
+ <para>and then run a small <literal>qsort</literal> with
+ tracing:</para>
+
+<screen>
+*Main> :trace qsort [3,2,1]
+Stopped at qsort.hs:1:11-12
+_result :: [a]
+[qsort.hs:1:11-12] *Main>
+</screen>
+
+ <para>We can now inspect the history of evaluation steps:</para>
+
+<screen>
+[qsort.hs:1:11-12] *Main> :hist
+-1 : qsort.hs:3:24-38
+-2 : qsort.hs:3:23-55
+-3 : qsort.hs:(1,0)-(3,55)
+-4 : qsort.hs:2:15-24
+-5 : qsort.hs:2:15-46
+-6 : qsort.hs:3:24-38
+-7 : qsort.hs:3:23-55
+-8 : qsort.hs:(1,0)-(3,55)
+-9 : qsort.hs:2:15-24
+-10 : qsort.hs:2:15-46
+-11 : qsort.hs:3:24-38
+-12 : qsort.hs:3:23-55
+-13 : qsort.hs:(1,0)-(3,55)
+-14 : qsort.hs:2:15-24
+-15 : qsort.hs:2:15-46
+-16 : qsort.hs:(1,0)-(3,55)
+<end of history>
+</screen>
+
+ <para>To examine one of the steps in the history, use
+ <literal>:back</literal>:</para>
+
+<screen>
+[qsort.hs:1:11-12] *Main> :back
+Logged breakpoint at qsort.hs:3:24-38
+_result :: [a]
+as :: [a]
+a :: a
+[-1: qsort.hs:3:24-38] *Main>
+</screen>
+
+ <para>Note that the local variables at each step in the history have been
+ preserved, and can be examined as usual. Also note that the prompt has
+ changed to indicate that we're currently examining the first step in
+ the history: <literal>-1</literal>. The command
+ <literal>:forward</literal> can be used to traverse forward in the
+ history.</para>
+
+ <para>The <literal>:trace</literal> command can be used with or without
+ an expression. When used without an expression, tracing begins from
+ the current breakpoint, just like <literal>:step</literal>.</para>
+
+ <para>The history is only available when
+ using <literal>:trace</literal>; the reason for this is we found that
+ logging each breakpoint in the history cuts performance by a factor of
+ 2 or more. GHCi remembers the last 50 steps in the history (perhaps in
+ the future we'll make this configurable).</para>
+ </sect2>
+
+ <sect2 id="ghci-debugger-exceptions">
+ <title>Debugging exceptions</title>
+ <para>Another common question that comes up when debugging is
+ “where did this exception come from?”. Exceptions such as
+ those raised by <literal>error</literal> or <literal>head []</literal>
+ have no context information attached to them. Finding which
+ particular call to <literal>head</literal> in your program resulted in
+ the error can be a painstaking process, usually involving
+ <literal>Debug.Trace.trace</literal>, or compiling with
+ profiling and using <literal>+RTS -xc</literal> (see <xref
+ linkend="prof-time-options" />).</para>
+
+ <para>The GHCi debugger offers a way to hopefully shed some light on
+ these errors quickly and without modifying or recompiling the source
+ code. One way would be to set a breakpoint on the location in the
+ source code that throws the exception, and then use
+ <literal>:trace</literal> and <literal>:history</literal> to establish
+ the context. However, <literal>head</literal> is in a library and
+ we can't set a breakpoint on it directly. For this reason, GHCi
+ provides the flags <literal>-fbreak-on-exception</literal> which causes
+ the evaluator to stop when an exception is thrown, and <literal>
+ -fbreak-on-error</literal>, which works similarly but stops only on
+ uncaught exceptions. When stopping at an exception, GHCi will act
+ just as it does when a breakpoint is hit, with the deviation that it
+ will not show you any source code location. Due to this, these
+ commands are only really useful in conjunction with
+ <literal>:trace</literal>, in order to log the steps leading up to the
+ exception. For example:</para>
+
+<screen>
+*Main> :set -fbreak-on-exception
+*Main> :trace qsort ("abc" ++ undefined)
+“Stopped at <exception thrown>
+_exception :: e
+[<exception thrown>] *Main> :hist
+-1 : qsort.hs:3:24-38
+-2 : qsort.hs:3:23-55
+-3 : qsort.hs:(1,0)-(3,55)
+-4 : qsort.hs:2:15-24
+-5 : qsort.hs:2:15-46
+-6 : qsort.hs:(1,0)-(3,55)
+<end of history>
+[<exception thrown>] *Main> :back
+Logged breakpoint at qsort.hs:3:24-38
+_result :: [a]
+as :: [a]
+a :: a
+[-1: qsort.hs:3:24-38] *Main> :force as
+*** Exception: Prelude.undefined
+[-1: qsort.hs:3:24-38] *Main> :print as
+as = 'b' : 'c' : (_t1::[Char])
+</screen>
+
+ <para>The exception itself is bound to a new variable,
+ <literal>_exception</literal>.</para>
+
+ <para>Breaking on exceptions is particularly useful for finding out what
+ your program was doing when it was in an infinite loop. Just hit
+ Control-C, and examine the history to find out what was going
+ on.</para>
+ </sect2>
+
+ <sect2><title>Example: inspecting functions</title>
+ <para>
+ It is possible to use the debugger to examine function values.
+ When we are at a breakpoint and a function is in scope, the debugger
+ cannot show
+ you the source code for it; however, it is possible to get some
+ information by applying it to some arguments and observing the result.
+ </para>
+
+ <para>
+ The process is slightly complicated when the binding is polymorphic.
+ We show the process by means of an example.
+ To keep things simple, we will use the well known <literal>map</literal> function:
+<programlisting>
+import Prelude hiding (map)
+
+map :: (a->b) -> [a] -> [b]
+map f [] = []
+map f (x:xs) = f x : map f xs
+</programlisting>
+ </para>
+
+ <para>
+ We set a breakpoint on <literal>map</literal>, and call it.
+<screen>
+*Main> :break 5
+Breakpoint 0 activated at map.hs:5:15-28
+*Main> map Just [1..5]
+Stopped at map.hs:(4,0)-(5,12)
+_result :: [b]
+x :: a
+f :: a -> b
+xs :: [a]
+</screen>
+ GHCi tells us that, among other bindings, <literal>f</literal> is in scope.
+ However, its type is not fully known yet,
+ and thus it is not possible to apply it to any
+ arguments. Nevertheless, observe that the type of its first argument is the
+ same as the type of <literal>x</literal>, and its result type is shared
+ with <literal>_result</literal>.
+ </para>
+
+ <para>
+ As we demonstrated earlier (<xref linkend="breakpoints" />), the
+ debugger has some intelligence built-in to update the type of
+ <literal>f</literal> whenever the types of <literal>x</literal> or
+ <literal>_result</literal> are discovered. So what we do in this
+ scenario is
+ force <literal>x</literal> a bit, in order to recover both its type
+ and the argument part of <literal>f</literal>.
+<screen>
+*Main> seq x ()
+*Main> :print x
+x = 1
+</screen>
+ </para>
+ <para>
+ We can check now that as expected, the type of <literal>x</literal>
+ has been reconstructed, and with it the
+ type of <literal>f</literal> has been too:</para>
+<screen>
+*Main> :t x
+x :: Integer
+*Main> :t f
+f :: Integer -> b
+</screen>
+ <para>
+ From here, we can apply f to any argument of type Integer and observe
+ the results.
+<screen><![CDATA[
+*Main> let b = f 10
+*Main> :t b
+b :: b
+*Main> b
+<interactive>:1:0:
+ Ambiguous type variable `b' in the constraint:
+ `Show b' arising from a use of `print' at <interactive>:1:0
+*Main> :p b
+b = (_t2::a)
+*Main> seq b ()
+()
+*Main> :t b
+b :: a
+*Main> :p b
+b = Just 10
+*Main> :t b
+b :: Maybe Integer
+*Main> :t f
+f :: Integer -> Maybe Integer
+*Main> f 20
+Just 20
+*Main> map f [1..5]
+[Just 1, Just 2, Just 3, Just 4, Just 5]
+]]></screen>
+ In the first application of <literal>f</literal>, we had to do
+ some more type reconstruction
+ in order to recover the result type of <literal>f</literal>.
+ But after that, we are free to use
+ <literal>f</literal> normally.
+ </para>
+ </sect2>
+
+ <sect2><title>Limitations</title>
+ <itemizedlist>
+ <listitem>
+ <para>When stopped at a breakpoint, if you try to evaluate a variable
+ that is already under evaluation, the second evaluation will hang.
+ The reason is
+ that GHC knows the variable is under evaluation, so the new
+ evaluation just waits for the result before continuing, but of
+ course this isn't going to happen because the first evaluation is
+ stopped at a breakpoint. Control-C can interrupt the hung
+ evaluation and return to the prompt.</para>
+ <para>The most common way this can happen is when you're evaluating a
+ CAF (e.g. main), stop at a breakpoint, and ask for the value of the
+ CAF at the prompt again.</para>
+ </listitem>
+ <listitem><para>
+ Implicit parameters (see <xref linkend="implicit-parameters"/>) are only available
+ at the scope of a breakpoint if there is an explicit type signature.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+
+ <sect1 id="ghci-invocation">
+ <title>Invoking GHCi</title>
+ <indexterm><primary>invoking</primary><secondary>GHCi</secondary></indexterm>
+ <indexterm><primary><option>––interactive</option></primary></indexterm>
+
+ <para>GHCi is invoked with the command <literal>ghci</literal> or
+ <literal>ghc ––interactive</literal>. One or more modules or
+ filenames can also be specified on the command line; this
+ instructs GHCi to load the specified modules or filenames (and all
+ the modules they depend on), just as if you had said
+ <literal>:load <replaceable>modules</replaceable></literal> at the
+ GHCi prompt (see <xref linkend="ghci-commands" />). For example, to
+ start GHCi and load the program whose topmost module is in the
+ file <literal>Main.hs</literal>, we could say:</para>
+
+<screen>
+$ ghci Main.hs
+</screen>
+
+ <para>Most of the command-line options accepted by GHC (see <xref
+ linkend="using-ghc"/>) also make sense in interactive mode. The ones
+ that don't make sense are mostly obvious.</para>
+
+ <sect2>
+ <title>Packages</title>
+ <indexterm><primary>packages</primary><secondary>with GHCi</secondary></indexterm>
+
+ <para>Most packages (see <xref linkend="using-packages"/>) are
+ available without needing to specify any extra flags at all:
+ they will be automatically loaded the first time they are
+ needed.</para>
+
+ <para>For hidden packages, however, you need to request the
+ package be loaded by using the <literal>-package</literal> flag:</para>
+
+<screen>
+$ ghci -package readline
+GHCi, version 6.8.1: http://www.haskell.org/ghc/ :? for help
+Loading package base ... linking ... done.
+Loading package readline-1.0 ... linking ... done.
+Prelude>
+</screen>
+
+ <para>The following command works to load new packages into a
+ running GHCi:</para>
+
+<screen>
+Prelude> :set -package <replaceable>name</replaceable>
+</screen>
+
+ <para>But note that doing this will cause all currently loaded
+ modules to be unloaded, and you'll be dumped back into the
+ <literal>Prelude</literal>.</para>
+ </sect2>
+
+ <sect2>
+ <title>Extra libraries</title>
+ <indexterm><primary>libraries</primary><secondary>with GHCi</secondary></indexterm>
+
+ <para>Extra libraries may be specified on the command line using
+ the normal <literal>-l<replaceable>lib</replaceable></literal>
+ option. (The term <emphasis>library</emphasis> here refers to
+ libraries of foreign object code; for using libraries of Haskell
+ source code, see <xref linkend="ghci-modules-filenames"/>.) For
+ example, to load the “m” library:</para>
+
+<screen>
+$ ghci -lm
+</screen>
+
+ <para>On systems with <literal>.so</literal>-style shared
+ libraries, the actual library loaded will the
+ <filename>lib<replaceable>lib</replaceable>.so</filename>. GHCi
+ searches the following places for libraries, in this order:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Paths specified using the
+ <literal>-L<replaceable>path</replaceable></literal>
+ command-line option,</para>
+ </listitem>
+ <listitem>
+ <para>the standard library search path for your system,
+ which on some systems may be overridden by setting the
+ <literal>LD_LIBRARY_PATH</literal> environment
+ variable.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>On systems with <literal>.dll</literal>-style shared
+ libraries, the actual library loaded will be
+ <filename><replaceable>lib</replaceable>.dll</filename>. Again,
+ GHCi will signal an error if it can't find the library.</para>
+
+ <para>GHCi can also load plain object files
+ (<literal>.o</literal> or <literal>.obj</literal> depending on
+ your platform) from the command-line. Just add the name the
+ object file to the command line.</para>
+
+ <para>Ordering of <option>-l</option> options matters: a library
+ should be mentioned <emphasis>before</emphasis> the libraries it
+ depends on (see <xref linkend="options-linker"/>).</para>
+ </sect2>
+
+ </sect1>
+
+ <sect1 id="ghci-commands">
+ <title>GHCi commands</title>
+
+ <para>GHCi commands all begin with
+ ‘<literal>:</literal>’ and consist of a single command
+ name followed by zero or more parameters. The command name may be
+ abbreviated, with ambiguities being resolved in favour of the more
+ commonly used commands.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <literal>:abandon</literal>
+ <indexterm><primary><literal>:abandon</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Abandons the current evaluation (only available when stopped at
+ a breakpoint).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:add</literal> <optional><literal>*</literal></optional><replaceable>module</replaceable> ...
+ <indexterm><primary><literal>:add</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Add <replaceable>module</replaceable>(s) to the
+ current <firstterm>target set</firstterm>, and perform a
+ reload. Normally pre-compiled code for the module will be
+ loaded if available, or otherwise the module will be
+ compiled to byte-code. Using the <literal>*</literal>
+ prefix forces the module to be loaded as byte-code.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:back</literal>
+ <indexterm><primary><literal>:back</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Travel back one step in the history. See <xref
+ linkend="tracing" />. See also:
+ <literal>:trace</literal>, <literal>:history</literal>,
+ <literal>:forward</literal>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:break [<replaceable>identifier</replaceable> |
+ [<replaceable>module</replaceable>] <replaceable>line</replaceable>
+ [<replaceable>column</replaceable>]]</literal>
+ </term>
+ <indexterm><primary><literal>:break</literal></primary></indexterm>
+ <listitem>
+ <para>Set a breakpoint on the specified function or line and
+ column. See <xref linkend="setting-breakpoints" />.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:browse</literal><optional><literal>!</literal></optional> <optional><optional><literal>*</literal></optional><replaceable>module</replaceable></optional> ...
+ <indexterm><primary><literal>:browse</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Displays the identifiers defined by the module
+ <replaceable>module</replaceable>, which must be either
+ loaded into GHCi or be a member of a package. If
+ <replaceable>module</replaceable> is omitted, the most
+ recently-loaded module is used.</para>
+
+ <para>If the <literal>*</literal> symbol is placed before
+ the module name, then <emphasis>all</emphasis> the
+ identifiers in scope in <replaceable>module</replaceable> are
+ shown; otherwise the list is limited to the exports of
+ <replaceable>module</replaceable>. The
+ <literal>*</literal>-form is only available for modules
+ which are interpreted; for compiled modules (including
+ modules from packages) only the non-<literal>*</literal>
+ form of <literal>:browse</literal> is available.
+ If the <literal>!</literal> symbol is appended to the
+ command, data constructors and class methods will be
+ listed individually, otherwise, they will only be listed
+ in the context of their data type or class declaration.
+ The <literal>!</literal>-form also annotates the listing
+ with comments giving possible imports for each group of
+ entries.</para>
+<screen>
+Prelude> :browse! Data.Maybe
+-- not currently imported
+Data.Maybe.catMaybes :: [Maybe a] -> [a]
+Data.Maybe.fromJust :: Maybe a -> a
+Data.Maybe.fromMaybe :: a -> Maybe a -> a
+Data.Maybe.isJust :: Maybe a -> Bool
+Data.Maybe.isNothing :: Maybe a -> Bool
+Data.Maybe.listToMaybe :: [a] -> Maybe a
+Data.Maybe.mapMaybe :: (a -> Maybe b) -> [a] -> [b]
+Data.Maybe.maybeToList :: Maybe a -> [a]
+-- imported via Prelude
+Just :: a -> Maybe a
+data Maybe a = Nothing | Just a
+Nothing :: Maybe a
+maybe :: b -> (a -> b) -> Maybe a -> b
+</screen>
+ <para>
+ This output shows that, in the context of the current session, in the scope
+ of <literal>Prelude</literal>, the first group of items from
+ <literal>Data.Maybe</literal> have not been imported (but are available in
+ fully qualified form in the GHCi session - see <xref
+ linkend="ghci-scope"/>), whereas the second group of items have been
+ imported via <literal>Prelude</literal> and are therefore available either
+ unqualified, or with a <literal>Prelude.</literal> qualifier.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <literal>:cd</literal> <replaceable>dir</replaceable>
+ <indexterm><primary><literal>:cd</literal></primary></indexterm>
+ </term>
+ <listitem>
+ <para>Changes the current working directory to
+ <replaceable>dir</replaceable>. A
+ ‘<literal>˜</literal>’ symbol at the
+ beginning of <replaceable>dir</replaceable> will be replaced
+ by the contents of the environment variable
+ <literal>HOME</literal>.</para>
+
+ <para>NOTE: changing directories causes all currently loaded