~pi/aka

ref: 9065cb5878f75c79b63b17813094385ca69cc479 aka/README -rw-r--r-- 3.7 KiB
9065cb58Paul Ivanov point to origin story, fix typo 1 year, 3 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
  .---------------------.
 / 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).


## 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.

## 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