.. highlight:: bash

Tips and Tricks
===============

The tips and tricks included in this section may enhance your EDM experience.


Auto-completion
---------------

If you use the Bash shell for interacting with EDM, we provide a nice
auto-completion script that you can enable.

:download:`Click here <../edm-completion.bash>` to download the script.

Save the script to a convenient location, and then *source* it in your startup
script. For example, if you place the auto-completion script in your ``$HOME``
directory, add the following to your ``~/.bashrc`` file::

    source ~/edm-completion.bash


In order to set this up for all users, copy this script to the
``/opt/local/etc/bash_completion.d`` directory on OSX or to the
``/etc/bash_completion.d`` directory on Linux.

In order to activate auto-completion restart your shell, or manually *source*
your ``~/.bashrc``. Now, pressing the Tab key while writing a EDM command will
return a set of suggestions::

    $ edm environments<tab><tab>
    create   export   import   list     prefix   remove   upgrade

Currently, this feature only works for commands and subcommands.
EDM's inline help, which is described in the following section, can be used
to obtain more information about command options and arguments.


Getting help
------------

The EDM command line application has extensive inline help that can be used to
explore the tool's functionality and save time. Inline help is available for
all EDM commands/subcommands and can be invoked using the ``-h``/``--help``
option::

    $ edm [COMMAND [SUBCOMMAND]] --help

Appending ``-h``/``--help`` to any EDM command guarantees that the command
will be a no-op, so the user can freely explore the CLI without
disturbing the working environment.


Example: clearing the cache
^^^^^^^^^^^^^^^^^^^^^^^^^^^

In this example, we will use EDM's inline help facility to find a command to
**non-interactively delete downloaded eggs from the cache**. To begin, we must
first find a command to manipulate the EDM cache::

    $ edm --help
    Usage: edm [OPTIONS] COMMAND [ARGS]...

    Options:
      ...
      -h, --help                      Show this message and exit.

    List of commands:
      available-runtimes  List available runtimes.
      cache               Perform operations on the EDM cache.
      check-connection    Check connection to configured server.
      ...

    Additional help topics:
      configuration         Learn how to configure EDM
      ...

Topics in the *Additional help topics* section offer detailed inline
documentation of different EDM features for quick reference. To access the
help text for a given ``TOPIC``, simply do::

    $ edm help TOPIC

We see from the help output that the ``cache`` command might have what we
are looking for. We then get the inline help for ``cache`` to see what
subcommands it offers::

    $ edm cache -h
    Usage: edm cache [OPTIONS] COMMAND [ARGS]...

      Perform operations on the EDM cache.

    Options:
      -h, --help  Show this message and exit.

    Commands:
      info   Cache size information.
      list   List cache contents.
      purge  Free disk space by clearing EDM caches.


The next step is a predictable one::

    $ edm cache purge -h
    Usage: edm cache purge [OPTIONS]

      Free disk space by clearing EDM caches.

    Options:
      --all              Operate on runtime and package caches.
      --runtimes         Operate on runtime cache only.
      --packages         Operate on package cache only.
      --downloaded-only  Target downloaded fixtures only.
      --extracted-only   Target extracted fixtures only.
      -y, --yes          If given, always assume yes to every prompt, and run non-
                         interactively.
      -h, --help         Show this message and exit.


With this information, we can construct the EDM command that we want::

    $ edm cache purge --packages --downloaded-only -y



Aliases
-------

To make the CLI more user friendly, EDM offers aliases for some commands:

==================    =========================================
    Command                         Alias
==================    =========================================
``environments``      ``envs``, ``env``
``application``       ``app``
==================    =========================================