Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cykerway/complete-alias
automagical shell alias completion;
https://github.com/cykerway/complete-alias
Last synced: 7 days ago
JSON representation
automagical shell alias completion;
- Host: GitHub
- URL: https://github.com/cykerway/complete-alias
- Owner: cykerway
- License: gpl-3.0
- Created: 2016-12-24T00:33:42.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2022-06-29T15:40:34.000Z (over 2 years ago)
- Last Synced: 2024-02-11T18:45:31.463Z (9 months ago)
- Language: Shell
- Homepage: https://repo.cykerway.com/complete-alias
- Size: 80.1 KB
- Stars: 655
- Watchers: 18
- Forks: 63
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# complete-alias
automagical shell alias completion;
- works with all common aliases, even self-aliases;
- one completion function, for all aliases;
- alias completion as easy as type-and-tab;
## install
1. install dependency [bash-completion][];
- linux:
install `bash-completion` using system package manager:
dnf install bash-completion ## fedora
apt install bash-completion ## debianfor other linux distros, see faq;
- macos (experimental):
install `bash-completion` homebrew formulae version 2:
brew install bash-completion@2
- windows (experimental):
see faq;
2. source `complete_alias` in `~/.bash_completion`:
. {complete_alias}
where `{complete_alias}` is the path of `complete_alias`;
## usage
1. edit aliases to complete in `complete_alias`:
for example, to complete aliases `foo`, `bar` and `baz`:
complete -F _complete_alias foo
complete -F _complete_alias bar
complete -F _complete_alias baz2. to complete an alias, type it and press ``;
## example
to complete alias `sctl` aliased to `systemctl`:
$ alias sctl='systemctl'
$ cp complete_alias ~/.complete_alias
$ echo ". ~/.complete_alias" >> ~/.bash_completion
$ echo "complete -F _complete_alias sctl" >> ~/.complete_alias
$ sctl
add-requires
add-wants
cancel
cat
condreload
...## config
to config `complete-alias`, set these envars *before* sourcing the main script:
- `COMPAL_AUTO_UNMASK`
this is a bool; default is `0`; when set to `1`, enables auto unmask; when
set to `0`, uses manual unmask;auto unmask automatically manages non-alias command completions, but incurs
a small overhead on source; manual unmask is the traditional way of setting
non-alias command completions, which is static and faster but requires user
intervention if the preset is not satisfying;## compat
- support for gnu bash(>=4.4) on linux is aimed;
- support for older versions of bash is uncertain;
- support for other shells is possible but unlikely;
- support for other operating systems is experimental;
## faq
- how to install it on windows?
support for windows is limited to [msys2][] and [git for windows][gfw]:
- msys2:
msys2 features [pacman][] so you can install like linux:
pacman -S bash-completion
cat complete_alias >> ~/.bash_completion- git for windows:
tldr: steal `bash_completion` and source it before `complete_alias`;
git for windows provides git bash, which is a minimal environment based
on msys2; for what matters here, git bash does not have package manager;
so the above install procedure does not apply;the idea is, you must somehow get `bash-completion` and load it before
`complete-alias` in a shell environment; for example, you can download
`bash-completion` package from [a msys2 mirror][msys2-mirror]; however,
the easiest solution i found to make things work is to simply download
the main script [`bash_completion`][bash_completion] from its git repo;
this does not give you its entirety, but is good enough to work;now you have 2 files: `bash_completion` and `complete_alias`; you need
to source them in this order in `~/.bashrc`:. ~/.bash_completion.sh
. ~/.complete_alias.shattention: here we renamed the files; we cannot use `~/.bash_completion`
because this is the very filename sourced by the very script; using this
filename will cause an infinite loop;now install is complete; add your own aliases in `~/.complete_alias.sh`;
- how to install `bash-completion` on other linux distros?
these commands are sourced from wikis and users:
pacman -S bash-completion ## arch
yum install bash-completion ## centos
emerge --ask app-shells/bash-completion ## gentoo
zypper install bash-completion ## suse
apt install bash-completion ## ubuntuthese commands are not tested; open a ticket if you find them not working;
- how to complete *all* my aliases?
run this one-liner *after* all aliases have been defined:
complete -F _complete_alias "${!BASH_ALIASES[@]}"
it works like this:
complete -F _complete_alias foo
complete -F _complete_alias bar
complete -F _complete_alias baz
...note that if you simply put this one-liner in `complete_alias` code, things
may not work, depending on the order of file sourcing, which in turn varies
across user configurations; the correct way to use this one-liner is to put
it in the same file where aliases are defined; for example, if your aliases
are defined in `~/.bashrc`, then that file should look like this:alias foo='...'
alias bar='...'
alias baz='...'
...
complete -F _complete_alias "${!BASH_ALIASES[@]}"- what are special characters in alias body?
these characters have special meanings and may cause errors when used in
alias body (this is not a complete list):- newline (`\n`):
we do not allow alias body to contain the newline character; this limits
the cases to consider and makes smaller, faster code; we treat a newline
as a word breaker in the outmost scope, but you better not rely on this;- backquote (`` ` ``):
avoid the old-style backquote form `` `command` `` of command
substitution as much as possible; instead, use the `$(command)` form;
the backquote form is more tricky and less legible when nested in quotes
or another command substitution; we do not intend to fully support
backquotes;- backslash (`\`):
avoid backslashes unless you absolutely have to use them; they are
mostly used to escape a character; we have double quotes that can do the
same; the bash manual is not complete on where a backslash is special
and where it is literal; and we may make mistakes on its interpretation;- colon (`:`):
a colon seems innocent but is special to word completion code: it is one
of the characters that breaks words for the completer; you can read more
about it at [this link][bash-faq]; however, we do not guarantee the same
treatment of colons here as there; we treat a colon as a word breaker in
the outmost scope and a literal otherwise; if you always want it to be a
literal, just quote it;- why is `sudo` completion not working correctly?
there is a known case with `sudo` that can go wrong; for example:
$ unalias sudo
$ complete -r sudo
$ alias ls='ping'
$ complete -F _complete_alias ls
$ sudo ls
{ip}
{ip}
{ip}
...here we are expecting a list of files, but the completion reply is a list of
ip addrs; the reason is, the completion function for `sudo` is almost always
`_sudo`, which is provided by `bash-completion`; this function strips `sudo`
then meta-completes the remaining command line; in our case, this is `ls` to
be completed by `_complete_alias`; but there is no way for `_complete_alias`
to see the original command line, and so it cannot tell `ls` from `sudo ls`;
as a result, `ls` and `sudo ls` are always completed the same even when they
should not; unfortunately, there is nothing `_complete_alias` can do here;the easiest solution is to make `sudo` a self-alias:
$ alias sudo='sudo'
$ complete -F _complete_alias sudo
$ alias ls='ping'
$ complete -F _complete_alias ls
$ sudo ls
{file}
{file}
{file}
...this gives `_complete_alias` a chance to see the original command line, then
decide what is the right thing to do; you may add a trailing space to `sudo`
alias body if you like it that way, and things still work correctly (listing
ip addrs is correct in this case):$ alias sudo='sudo '
$ complete -F _complete_alias sudo
$ alias ls='ping'
$ complete -F _complete_alias ls
$ sudo ls
{ip}
{ip}
{ip}
...## license
The source code is licensed under the [GNU General Public License v3.0][GPLv3].
Copyright (C) 2016-2021 Cyker Way
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.You should have received a copy of the GNU General Public License along with
this program. If not, see .[GPLv3]: https://www.gnu.org/licenses/gpl-3.0.txt
[bash-completion]: https://github.com/scop/bash-completion
[bash-faq]: https://tiswww.case.edu/php/chet/bash/FAQ
[bash_completion]: https://raw.githubusercontent.com/scop/bash-completion/master/bash_completion
[gfw]: https://gitforwindows.org/
[msys2-mirror]: http://repo.msys2.org/
[msys2]: http://www.msys2.org/
[pacman]: https://wiki.archlinux.org/index.php/Pacman