{"id":13903196,"url":"https://github.com/bonidjukic/aka","last_synced_at":"2025-07-18T00:33:43.592Z","repository":{"id":82746759,"uuid":"159230041","full_name":"bonidjukic/aka","owner":"bonidjukic","description":"Simple, single-file-executable command-line tool which lets you define per directory config files as aliases for shell commands.","archived":false,"fork":false,"pushed_at":"2019-02-23T21:36:43.000Z","size":1338,"stargazers_count":31,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-08-07T22:36:41.948Z","etag":null,"topics":["alias","command-line","lua","shell"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bonidjukic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-11-26T20:42:19.000Z","updated_at":"2024-06-22T03:57:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"799b6940-86f9-4821-9235-60d6fcff1da5","html_url":"https://github.com/bonidjukic/aka","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonidjukic%2Faka","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonidjukic%2Faka/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonidjukic%2Faka/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonidjukic%2Faka/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bonidjukic","download_url":"https://codeload.github.com/bonidjukic/aka/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226320947,"owners_count":17606379,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alias","command-line","lua","shell"],"created_at":"2024-08-06T22:01:49.625Z","updated_at":"2024-11-25T11:31:25.033Z","avatar_url":"https://github.com/bonidjukic.png","language":"Lua","funding_links":[],"categories":["shell"],"sub_categories":[],"readme":"# aka\n\n**aka is a simple, single-file-executable command-line tool which lets you define per directory config files as aliases for shell commands.**\n\n\n[![LuaRocks version](https://img.shields.io/luarocks/v/bonidjukic/aka.svg)](https://luarocks.org/modules/bonidjukic/aka)\n[![Build Status](https://travis-ci.com/bonidjukic/aka.svg?branch=master)](https://travis-ci.com/bonidjukic/aka)\n[![Code Coverage](https://codecov.io/github/bonidjukic/aka/branch/master/graphs/badge.svg)](https://codecov.io/gh/bonidjukic/aka/branch/master)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\n## Motivation\n\nBeing an avid user of Linux' `alias` command, oftentimes I found myself frustrated with a couple of \"more advanced\" use-cases and wanted a really simple tool which would:\n\n- be able to use namespaced (nested) aliases;\n- be able to define configuration files in directories which would serve as per-directory-context aliases;\n- be able to list all aliases within the current directory's context;\n- use simple format for configuration files (as close as possible to `alias` syntax);\n- integrate nicely with version control (e.g. add configuration file to the VCS to be shared among team members).\n\n## Features\n\n- define both [simple and nested aliases](#configuration-file)\n- list defined aliases (`aka -l` or `aka --list`)\n- recursively seek for `.aka` config file in parent directories\n\n## Usage\n\n\u003ca href=\"https://asciinema.org/a/215736?autoplay=1\" target=\"_blank\"\u003e\u003cimg src=\"https://asciinema.org/a/215736.svg\" /\u003e\u003c/a\u003e\n\n---\n\n### Overview\nUsing `aka` is quite straightforward:\n\n- create an `.aka` text file in a directory where you'd like to be able to use `aka` aliases;\n- define your aliases;\n- run `aka [your_alias]` to execute your aliases;\n- run `aka -l` or `aka --list` to list all available aliases\n\n### Configuration File\n\nConfiguration files are actually [Lua](https://www.lua.org/) files which means we're using:\n\n- `lua` strings for regular / simple aliases;\n- `lua` tables for namespaced / nested aliases;\n- `--` for single line and `[[]]` for multiple line comments.\n\nHere is an example of a configuration file to get started with:\n```lua\n-- regular aliases\npwd_alias = 'pwd' -- usage: aka pwd_alias\ndu_alias = 'du -h' -- usage: aka du_alias\n\n-- nested aliases\nalias_group = {\n  alias_subgroup = {\n    list = 'ls -alh' -- usage: aka alias_group alias_subgroup list\n  }\n}\n```\nA more practical example could be:\n\n```lua\n-- example project's docker containers management commands\ndocker = {\n  bash = {\n    django = 'docker exec -i -t $(docker ps -f name=django --format \"{{.Names}}\") /bin/bash',\n    postgres = 'docker exec -i -t $(docker ps -f name=postgres --format \"{{.Names}}\") /bin/bash'\n  },\n  build = {\n    django = 'docker-compose -f local.yml up --build django',\n    postgres = 'docker-compose -f local.yml up --build postgres',\n    all = 'docker-compose -f local.yml up --build'\n  }\n}\n```\n\nIn the example above we'd be able to use namespaced aliases like this:\n- `aka docker bash django` or;\n- `aka docker bash postgres` or;\n- `aka docker build all`\n- etc.\n\n### Command Line Interface\n\n```\naka - per directory shell aliases\n\nUsage:\n  aka alias [sub_alias sub_sub_alias ...]\n  aka -l|--list\n  aka -h|--help\n\nOptions:\n  -l, --list        List all aliases\n  -h, --help        Print usage\n```\n\n## Installation\n\n### Use Pre-compiled Binary\n\n#### Overview\n\nThe goal from the start was for this tool to be easily distributable across Linux machines (not having to have Lua on your system to be able to use `aka`).\n\nWith this in mind and the fact that [Lua is small](https://www.lua.org/about.html), pre-compiled x86_64 linux binaries are available for download which contain the entire LuaJIT compiler and `aka` source code.\n\n#### Download\n\nhttps://github.com/bonidjukic/aka/releases/latest\n\n### Using [LuaRocks](https://luarocks.org) To Install\n\nTo install `aka` using `luarocks` package manager, run this command in your terminal:\n\n```\nluarocks install aka\n```\n\nIf you don't have [LuaRocks](https://luarocks.org)  installed, this [document](https://github.com/luarocks/luarocks/wiki/Download)  can guide you through the process.\n\n### Building From Source\n\n#### Prerequisites\nBuilding `aka` from source is possible, but at the moment, [luastatic](https://github.com/ers35/luastatic) command line tool is a prerequisite for the build process.\n\n`luastatic` is used to build a standalone executable from a Lua source code.\n\n#### Building\n\nTo build `aka` run:\n\n`make` or `make build`\n\n#### Installing\n\nTo install `aka` run:\n\n```make install```\n\n#### Uninstalling\n\nTo uninstall `aka` run:\n\n```make uninstall```\n\n## Testing\n\n### Prerequisites\n\n[Busted](https://github.com/Olivine-Labs/busted) unit testing framework is required to run the tests.\n\n### Running The Tests\n\nNavigate to `aka` project's root directory and run:\n\n```\nbusted\n```\n\n## Roadmap\n\nThere are a couple of features I'm planning to add in the near future:\n\n- [✔] ~~ability to execute `aka` from children directories as well (currently it's only possible to execute `aka` from the same directory where the config file is located);~~\n- [✔] ~~ability to pass arguments to aliases (this is not possible ATM);~~\n- [...] ability to define `.aka.local` config file which could be used to override aliases from `.aka` config (useful when `.aka` is added to VCS and you'd like to have a different local version of a certain alias);\n- [...] ability to autocomplete `aka` aliases using bash completions.\n\n## Nomenclature\n\nIf it's not obvious, `aka` was named after the acronym of the *Also known as* adverb, i.e. *a.k.a* which is a synonym of *alias* and also has a nice side effect of being very short to type.\n\n## Versioning\n\n[SemVer](http://semver.org/) is used for versioning. For the versions available, see the [tags on this repository](https://github.com/bonidjukic/aka/tags).\n\n## Changelog\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) \u0026mdash; please see the [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes.\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE.md](LICENSE.md) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonidjukic%2Faka","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbonidjukic%2Faka","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonidjukic%2Faka/lists"}