.---------------------.
 / aka - also known as /
/---------------------/

Simple, persistent, shell-based command aliasing

Usage: aka alias               show stored aliases
       aka alias NAME CMD...   store an alias for CMD
       aka NAME [...]          run CMD, optionally with more arguments

By default, aliases are stored in the `.aka` file of the current working
directory. Optionally, the location of that file can be modified by setting the
AKA_FILE environment variable. Tested on Debian, OpenBSD, and OpenWRT, aka uses
portable shell syntax and should work everywhere that has a typical /bin/sh


Examples:

    $ aka alias demo more

    $ aka demo --version
    more from util-linux 2.36

    $ aka alias demo git

    $ aka demo --version
    git version 2.28.0

The command you alias can have parameters

    $ aka alias l ls -f

    $ aka l
    .aka .. aka aka_tiny . README .git

And you can pass additional parameters

    $ aka l -tR
    .. aka_tiny aka .git .aka README .

You can see all of the currently stored aliases

    $ aka alias
    l='ls -f'
    demo='git'

And edit them using your favorite text editor

    $ cat .aka
    alias demo='git'
    alias l='ls -f'

Everything that is not aliased will get executed as a regular command.

    $ aka python3 --version
    Python 3.8.6

## Why would anyone want this?

A practical use case might be to have

.
├── c_proj
│   └── .aka       | alias doit='make install'
├── go_proj
│   └── .aka       | alias doit='go run'
└── python_proj
    └── .aka       | alias doit='pip install .'

Now you can `aka doit` to your hearts content inside each of those folders, and
have that execute the appropriate build commands for the type of project it is.

    $ for x in *; do (cd $x && aka doit); done
    make: *** No rule to make target 'install'.  Stop.
    go run: no go files listed
    ERROR: Directory '.' is not installable. Neither 'setup.py' nor 'pyproject.toml' found.

If you're curious, you can read a bit more about aka's origin story here:

    https://pirsquared.org/blog/aka.html

## Installation

Grab aka, make it executable, and place it somewhere in your path.

The standard version of aka (~40 lines) that prints usage and has comments
explaining the code is here:

    https://git.sr.ht/~pi/aka/blob/main/aka

If you just want the business logic, functional equivalent (~10 lines) is here:

    https://git.sr.ht/~pi/aka/blob/main/aka_tiny

## How it works

aka is a tiny portable shell script that gets executed via /bin/sh, sources
AKA_FILE and evals the positional parameters, thus applying aliases and
whatever other shell script shenanigans stored in AKA_FILE.

For example, this means that you can put something like

    alias my='AKA_FILE=~/.my_aliases aka'

in your shell's startup files, and thereafter use the `my` command as an `aka`
invocation that always sources ~/.my_aliases file in your home directory,
regardless of where you run it.

## Notes

Initial prototype uses aliases, which may not work for programs that depend on
establishing their behavior based on the `argv[0]` name they were called by
(busybox, for example).

If you want to create aliases that include quotes, multiple commands, output
redirection, or job control, you either have to escape the special characters
like `>` and `&` with backslashes when creating the alias, or edit `.aka` file
to add them directly in there:

    $ aka alias redir_example echo \"hi\" \> log.txt
    $ aka alias double_date date \;  date

In the example above, if we don't put a backslash in front of the semicolon, we
will be terminating our aka alias for double_date with just one call do date,
and calling the second date command immediately.

And finally, aka stores the aliases using single quotes, so if you have
commands where you need to preserve single quotes, you should edit the `.aka`
file by hand to change the alias definition to use double quotes.

## Ideas

[x] AKA_FILE environment variable set to the file containing the desired
    shellscript file to source. Otherwise we look for the `.aka` file in the
    current directory.

[ ] `aka unalias` command?

## Related Projects

https://direnv.net/
"direnv is an extension for your shell. It augments existing shells with a new
feature that can load and unload environment variables depending on the current
directory." The direnv website has links to a half dozen similar projects.

https://manpages.debian.org/stretch/dpkg/update-alternatives.1.en.html
Debian's alternatives system is similar: it lets you switch out raw `XX`
command for *all* users, which is why you have to run update-alternatives as
root. With aka, you're defining the `aka XX` commands and they only apply on a
per-folder basis (or per AKA_FILE environment variable, if set).

## Changelog

2020-10-02: initial version

2020-10-03: added `AKA_FILE` environment variable

2020-10-08: publicly announced

2020-10-28: added notes about multiple commands, redirection, and quotes

## License

aka is distributed under a 3-clause BSD license.

## Author

aka was written by Paul Ivanov
https://pirsquared.org
https://git.sr.ht/~pi/aka