search

ardagnir / athame

Full vim for your shell (bash, zsh, gdb, python, etc)
GNU General Public License v3.0
1.63k stars 34 forks source link
readline vim-mode zsh

readme

Athame

Athame patches your shell to add full Vim support by routing your keystrokes through an actual Vim process. Athame can currently be used to patch readline (used by bash, gdb, python, etc) and/or zsh (which doesn't use readline).

Demo

Don't most shells already come with a vi-mode?

Yes, and if you're fine with basic vi imitations designed by a bunch of Emacs users, feel free to use them. ...but for the true Vim fanatics who sacrifice goats to the modal gods, Athame gives you the full power of Vim.

Requirements

Setting up Athame Readline

Option 1: (Arch Linux only) Use the AUR

Use readline-athame-git from the AUR.

Option 2: (The safest method) Install a local copy of Readline/Bash

git clone --recursive http://github.com/ardagnir/athame
cd athame
mkdir -p ~/local
./readline_athame_setup.sh --prefix=$HOME/local/
./bash_readline_setup.sh --prefix=$HOME/local/ --use_readline=$HOME/local/
cp athamerc ~/.athamerc

You can now run ~/local/bin/bash to run bash with Athame.

Option 3: Install Athame as your default Readline

For Ubuntu/Debian:

git clone --recursive http://github.com/ardagnir/athame
cd athame
./readline_athame_setup.sh --libdir=/lib/x86_64-linux-gnu --use_sudo

Otherwise:

git clone --recursive http://github.com/ardagnir/athame
cd athame
./readline_athame_setup.sh --use_sudo

You may need to rebuild bash if your installed version doesn't use your system readline (this is usually the case in Ubuntu and OSX):

./bash_readline_setup.sh --use_sudo

Additional Notes

Setting up Athame Zsh

Option 1: (Arch Linux only) Use the AUR

Use zsh-athame-git from the AUR.

Option 2: (The safest method) Install a local copy of Zsh

Windows Note: zsh tests don't work in Windows because zsh gets stuck in the background. Add --notest to the setup script line if installing on Windows.

git clone --recursive http://github.com/ardagnir/athame
cd athame
mkdir -p ~/local
./zsh_athame_setup.sh --prefix=$HOME/local/
cp athamerc ~/.athamerc

Add "unset zle_bracketed_paste" to the end of your ~/.zshrc

You can now run ~/local/bin/zsh to run zsh with Athame.

Option 3: Install Athame as your default Zsh

Windows Note: zsh tests don't work in Windows because zsh gets stuck in the background. Add --notest to the setup script line if installing on Windows.

git clone --recursive http://github.com/ardagnir/athame
cd athame
./zsh_athame_setup.sh --use_sudo

Add "unset zle_bracketed_paste" to the end of your ~/.zshrc

Additional Notes

Configuration

Athame can be configured through the following environment variables. They can be set on the fly or you can add them to your ~/.bashrc or ~/.zshrc. Make sure you use export if you add them to your ~/.zshrc.

FAQ

How do I use this?

It's just like Vim. Imagine your history is stored inside a Vim buffer (because it is!) with a blank line at the bottom. Your cursor starts on that blank line each time readline is called. Unless you're in command mode, some special chars (such as carriage return) are handled by readline/zsh.

Some example commands (there's no specific code for these, it's just Vim):

The default athamerc modifies up/down arrows in insert mode to jump to the end of the line, like in a normal shell, but you can change this.

You can also enable history searching arrows in the athamerc. (If you enable this and you use arrows, it searches for text that begins with what you've typed. It's like Vim's command mode.)

? and / are reversed from bash's vi-mode. Why?

Bash's vi-mode has ? go down and / go up. In actual Vim (and thus, Athame) they go the other way.

Why does Athame start in insert/normal mode?

The default athamerc includes "startinsert" to make Athame start in insert mode. If you remove that line, it will start in normal mode.

Why is my Athame slow?

Athame should be very fast, but it will slow down if your Vim setup is slow or if you have invalid vimscript in either your athamerc or vimrc. Try using a clean vimrc or athamerc and see if it speeds up. If not, file an issue.

If Athame is only slow in command mode (:?/), you should be able to fix it by updating Vim to version 8.1+.

I installed Athame for Readline, but it isn't doing anything!

Are you using the system readline? Type:

ldd $(which bash)

This should include libreadline. If it doesn't, you need to build bash to use the system readline. You can do this by running:

./bash_readline_setup.sh

Which chars are sent to vim and which to readline/zsh?

Control-C usually sends a SIGNINT signal that is handled by zsh, readline, or the program that calls readline. For other keys:

I got the error "Couldn't load vim path"

Is Vim at the correct path? You can change the path Athame looks at with the --vimbin flag.

How do I disable/uninstall Athame?

To temporarily disable Athame, export ATHAME_ENABLED=0

To compile readline/zsh without the Athame patches, run the setup script with a --noathame flag.

To get rid of Athame completly, you should probably just replace it with the non-patched version of readline/zsh from your distro.

Or, if you're cool with not having a shell, you can uninstall it by cding into the readline or zsh directory and typing sudo make uninstall.

Depending on your approach, you may want to manually remove /usr/lib/athame* and /etc/athamerc as well.

Why do the Up/Down arrows make the cursor jump to the end of the line?

This is done through vimscript in the athamerc to make Athame more like a normal shell. Feel free to comment it out.

How do I disable/change the way Athame shows Vim's mode?

By default Athame shows the Vim mode at the bottom of the screen. This can be disabled using export ATHAME_SHOW_MODE=0

Athame stores the current mode in the ATHAME_VIM_MODE environment variable. You can use this to display the Vim mode yourself. See https://github.com/ardagnir/athame/issues/21 for an example using powerline.

Similarly, Vim commands are displayed at the bottom of the screen by default. These can be disabled using export ATHAME_SHOW_COMMAND=0 and accessed using ATHAME_VIM_COMMAND

Why don't arrow keys work when I add Athame to my convoluted Zsh setup?

Because arrow keys are evil! Just kidding. :P

Ohmyzsh and some other zsh setups put your terminal into application mode to help their keymaps. Athame doesn't like this, and besides, you're using Vim as your keymap. You can override this by adding the following to the end of your ~/.zshrc:

function zle-line-init(){
  echoti rmkx
}
zle -N zle-line-init

Why isn't there an Athame package for my favorite distro?

...because you haven't made one yet. The Athame setup script comes with a --nobuild flag so that you can build it however you want or your package can just apply the Athame patches itself.

This is awesome! Can I help?

The best way to help is to look at the issue section and submit patches to fix bugs.

If you have a shell that I'm missing, you can also try making a patch to communicate between it and Athame (see athame_readline.h and athame_zsh.h for the functions you need to implement).

What about donations?

I'm not accepting donations, but you should consider donating to the EFF so that we don't end up living in a scary dystopian future where everyone is forced to use emacs.

Bugs

License

GPL v3