lukoshkin/evangelist
A quick and easy way to set up all your workstations! The evangelist package contains vim, bash/zsh, and Jupyter Notebook configurations..
Vim Proliferation
"I came up with evangelist and am developing it so I could configure everything less when I am dead."
About the project
A wide set of configurations for Vim, Bash/Zsh, Tmux, and Jupyter.
Deploy them on a laptop, remote server, or in a docker container.
Revert to your original settings with the uninstall command.
More information on the first wiki page!
Contents
Installation
All settings made to the console (including Vim commands that rely on the console)
are fully supported by Ubuntu and (almost completely) by macOS. It is worth to
mention that the settings themselves are not as platform dependent as
the way of their installation. As the project grows, the settings
and the setup script will become more universal and cross-platform.
Evangelist
-
Clone the repository.
For example:git clone https://github.com/lukoshkin/evangelist.git ~/.config/evangelist cd ~/.config/evangelist
-
Install at least minimal list of prerequisites
Run./evangelist.sh checkhealthfor help. -
In your console, run from the project directory:
-
./evangelist.sh install <configs>
where<configs>can bebash,zsh,vim,tmux,jupyter
(you can specify more than one argument) -
To ensure the command history transfer, you may run instead:
export HISTFILE; ./evangelist.sh install <shell> <other args>
where<shell>isbashorzsh
-
-
Re-login in the shell.
-
Adjust for yourself (optional).
Usevimrc,zshrcorbashrccommands to customize settings.
Since Vim keeps all changes made to files with it, on Linux, one might consider
adding anacron job (or its equivalent on macOS) by running anacron/anacron.sh script.
-
to remove old undofiles
./anacron.sh old @monthly -
or those undofiles which counterparts no longer exist
./anacron.sh dead 30
Note, if you are a user of a different OS, you will have to set up 'auto-purge' of the undodir manually.
To get more information about what arguments anacron.sh takes, type ./anacron.sh.
Also, check the develop branch for recent updates. If there are any,
you may want to incorporate them by typing git checkout develop before
going to the step 2.
Docker
One can add vimmer-setup to their docker image (Ubuntu-based) with the command below.
It builds a new image with bash-settings installed on top of the existing environment.
Run this command from the directory where Dockerfile resides.
docker build --build-arg IMG_NAME=<name_of_the_base_image> -t <new_image_name> .If installing zsh-settings with the evangelist inside a docker container,
run the latter with -e TERM=xterm-256color option. Otherwise, you will end up
with broken colors during the process of both the installation and exploitation.
docker run --name <container_name> -e TERM=xterm-256color -ti <name_you_gave_in_build_command>
Features
- Light implementation of conda-autoenv
which supports both bash and zsh - Efficient navigation in the project directory (commands:
tree,d,gg,G) - Interactive command history search (key-bindings:
jjk,<M-kk>,/) - Jupyter empowered by Vim and basic set of notebook extensions
- Minimal configuration for Tmux and several configuration levels for Vim/Neovim
Before to go into details, let's get familiar with the imposed notation:
C in shortcuts stands for Ctrl.
M is for Meta, which is Alt or command, depending on the keyboard layout.
<*-*> is a combination of keys where first ones are modifier of the last one.
(a|b) means the use of either a or b key in the given combination.
By default, Leader is mapped to \ in Vim, LocalLeader to <Space>.
But you can change both values in your custom/custom.vim.
Patch 1.4.5 (!)
Shell
-
Bindings
modes: ins - insert, cmd - command, tbc - tab completionmode shortcut assignment ins jjExit insert mode cmd (j|k)Go to the (next | Previous) matching substring in cmd history
provided no substring, go to the (next | previous) cmdany <M-(j|k)>Go to the (next | previous) cmd matching the current buffer from
the beginning (Note: one more<j/k>press to exit from ins mode)any <C-q>Deletes the current buffer, so one can execute another cmd,
after which the original one would be restoredcmd /Start interactive fuzzy search over cmds in the history file tbc ?Start isearch (# of completion options can be narrowed
by typing more chars)any <C-a>Change the prefix of the current command NOTE: the following settings are only supported by X11 based platforms
(It means that they will not work or be active on such as macOS or the one with Wayland protocol)any <M-(+|-)>(in | de)crease terminal window transparency a bit -
Aliases and shell functions
alias/function assignment mkenv [env]Remember the environment used in a folder to
[de]activate the former when [leaving]/entering the latter
(supports only conda environments)mdCreate a directory (or nested folders) and cd there treeDraw a project tree (files and directories);
if not installeddtreeis called instead
(a "safe" wrapper around Unixtree)dtreeDraw a project tree (folders only) vOpen the last file closed (in Vim) vipMake the "vim-ipython" split in tmux
(available only if tmux settings are installed; former configuration)vrmswp [name]Delete swap file by name or part of its name dShow directories visited by user (autocd zsh option) (gg|G)Go through the dir stack in (forward | backward) direction gg <n>Go to n-th directory in the list obtained with d
(starting from 0)gg -<n>Remove n-th directory from the dir stack swapSwap names of two targets rexgrep <str>is equivalent to grep -rIn --exclude-dir='.?*' <str>, (exclude
hidden directories, binary files from recursive search; add numbering)(bash|zsh|vim)rc*Edit user-defined settings for the specified target _(bash|zsh|vim)rcOpen main config file for the specified target mathCalculate simple expressions
(the result is stored in_ANSand can be reused)evn|evangelistAlias for evangelist.sh executable script * Note, the priority is given to custom settings. Also, they will not be overwritten by
updates or new installations.
Vim
modes: n - normal, v - visual, t - terminal, c - command mapping
different setups: old settings (minimal), extended settings, Neovim-Lua (edge, v0.7)
-
General key-bindings and functions (common)
mode shortcut assignment n <Leader>enToggle spell-check n <Leader>yYank current buffer v <Leader>yYank selected text n <Leader>tsPaste date and time before the cursor n <Leader>nuToggle line numbering and sign column n <Space>b<Space>Split line at the next space after the cursor position v <Space>b<Space>Split the entire line at spaces n <Space>bbSplit line at the next char you previously searched with fv <Space>bbSplit the entire line at a separator you searched with /n <Space><Space>Clear a search pattern highlighting,
dismiss a message in the cmd line below or in floating winsn <Leader>xOpen file under the cursor with xdg-open any <C-s>Save changes to a file n+v <C-(j|k)>Move lines (down|up) n <M-(h|j|k|l)>Insert an empty line or space in the direction
which a movement key specifiesn <S-M-(h|j|k|l)>Same, but the cursor remains on the current char c TrimRemove all trailing spaces in the whole file or for visual selection c RmswpDelete the swap file corresponding to the current buffer v //Search for selected text
(doesn't work inVISUAL LINEmode)any <M-m>Toggle mouse v pPaste the last yanked text in place of selected one n <A-r>Repeat the last colon command used n <A-(n|N)>Do not center window when searching n <Space>tOpen the current buffer in a new tab.
One can close the tab later withZZorZQ -
Plugins (w/o dependencies) and related mappings
Available at all levels
n <Leader>ntOpen tree explorer
(helps to navigate through a project tree)n <Leader>nfOpen tree explorer
starting from a directory of the current filen <Leader>uOpen undo-tree nord.nvim Change the default color scheme to nord trailing-whitespace Trailing whitespace highlighting vim-eunuch Adds useful commands like :SudoWrite,:Rename, and etc.vim-heritage Create a parent directory (if need be) when saving a file vim-lastplace Open file at the last edit position vim-mundo Visualize Vim undo tree vim-pasta Auto-indent on pasting vim-repeat Repeat with .complex commands (e.g., containing<Plug>)vim-sleuth Automatically adjust shiftwidth&expandtabvim-surround Surround with quotation marks, tags, and more. Remove them or substitute vim-commentary Commenting and uncommenting lines With Neovim-Lua setup and entended settings
vimspector Code debugger vimtex Mappings, highlighting, compilation for LaTex files markdown-preview.nvim Preview markdown in the user's browser vim-slime Send code on the left to a split on the right and execute it if possible vim-ipython-cell Build cell layout for Python code with a delimiter n <Leader>mdOpen/close markdown preview n <C-p>Open CtrlP fuzzy finder Vimspector
n <Leader>dcSwitch to the debug mode
or continue runningn <Leader>drTerminate debug session and switch to regular editing
n<Leader>dsStop the debugger
(You can not continue from where you have stopped.
Unlike reset, all windows remain оpen)n <Leader>ddPause the debugger n <Leader>d0Restart the debugger n <Space>=Step into n <Space>+Step over n <Space>-Step out n <Space>.Toggle breakpoint n <Space>,Add a conditional breakpoint n <Space>:Add a function breakpoint n <Space>dbToggle section with breakpoints list n <Space>ddGo to the section with source code n <Space>dvGo to the variables section n <Space>dwGo to the watches section n <Space>doGo to the section with output n <Space>dtGo to the terminal
if Vimspector has opened itn <Space>dsGo to the 'stack trace' section With extended settings
vim-floaterm Terminal in a floating window coc.nvim Completion engine, syntax parsing, and more ctrlp.vim fuzzy search among MRU files, current folder content eregex.vim Toggle between Vim and Perl regular expressions ( <Leader>renmap)With Neovim-Lua setup
LuaSnip Code snippets auenv.nvim Automatically switch between conda envs bterm.nvim Simple terminal call bufferline.nvim Display tabs with buffers at the top dashboard-nvim Starting page on open fidget.nvim Widget displaying the loading progress of Neovim LSP gitsigns.nvim Mark changes to the working tree in the sign column vim-easy-align Align block of text lsp_signature.nvim Display signature help when modifying function arguments lualine.nvim Better status line null-ls.nvim Embed non-LSP sources in Neovim nvim-cmp Text/code-completion engine nvim-code-action-menu GUI for code action menu nvim-lspconfig Configs for Neovim LSP client nvim-neoclip.lua Pick one of previous yanks for pasting nvim-notify Display errors, warnings, hints in floating windows nvim-tree.lua File explorer nvim-treesitter Tree-sitter in Neovim project.nvim Automatically change CWD to the root of the project quick-scope Highlight word anchors within the line to do t/f-movement slime-wrapper.nvim Mimic JupyterLab telescope.nvim Advanced file search with preview vim-doge Generate documentation template for a function/class vim-sayonara Wipe out a buffer, don't close the window Jumps
n [gJump to the previous sign of gitsigns n ]gJump to the next sign of gitsigns n [dJump to the previous diagnostic n ]dJump to the next diagnostic n [eJump to the previous error (higher diagnostic severity lvl) n ]eJump to the next error (higher diagnostic severity lvl) n [bJump to the previous buffer n ]bJump to the next buffer Telescope
n <Leader>bOpen available buffers in Telescope n <Leader>foOpen most recently used files in Telescope n <Leader>fpOpen projects in Telescope n <Leader>fyOpen previous yanks in Telescope n <Leader>feOpen files in Telescope (exact search) n <Leader>ffOpen files in Telescope (fuzzy search) n <Leader>faSame but abolish all external ignore patterns n <Leader>fgFind string with grep options in Telescope n grOpen LSP references of the symbol under the cursor in Telescope n <Leader>fhFind a help tag with Telescope n <Leader>fkFind a key mapping with Telescope LSP keymaps (most of LSP mappings are valid for extended settings as well)
n gdGo to definition n gDGo to declaration n gsShow signature help n geShow diagnostic message n <Leader>iGo to implementation n <Leader>tdGo to type definition n KDisplay hover information about the symbol under the cursor n <Leader>rnRename symbol under the cursor n <Space>qOpen diagnostics in the location list n <Leader>fsOpen documents symbols in the location list n+v <Leader>caOpen code action menu Completions
i <C-e>Close the completion menu & restore the current line to its original state i <C-y>Close the completion menu & complete to the currently selected option i <Tab>Jump to the next position in a snippet Some mappings of evangelist's offspring projects
n <Space>ipStart IPython session in a split on the right n <Leader>ssSelect an interpreter to start a Vim-SLIME session n+t <M-t>Toggle bottom terminal t <C-t>Flip terminal from horizontal to vertical orientation Miscellanea
n+v <Leader>hrUndo change made to a hunk (in git diff) under the cursor
n+vgaAlign a block of text
One specifies the range by a movement or selection.
<Enter>switches the alignment moden <LocalLeader>dgGenerate documentation for a function or a class c :Insert <cmd>Paste the cmd output to the current buffer c :Print <lua_table>Print lua table in the cmdline window
n<C-(Up|Down|Left|Right)>Resize window
vertically (Up+/Down-)
or horizontally (Left-/Right+)
Jupyter
| mode | shortcut | assignment |
|---|---|---|
| Jupyter | n |
lift restrictions from selected cells |
| Jupyter | l |
make selected cells read-only |
| Jupyter | f |
freeze selected cells |
| Jupyter | 00 |
restart the kernel without confirmation |
| Jupyter | i |
enter Vim mode |
| Vim | <M-j> |
exit from Vim mode (enables Jupyter mode) |
| Jupyter | h(j|k) |
(un- | <blank> )collapse the selected heading cell's section |
| Jupyter | <C-(j|k)> |
move selected cells (down | up) |
| Jupyter | (J|K) |
extend selected cells (below | above) |
Check the rest settings with <F1> or H (<Shift-h>) while running Jupyter session.
Tmux
| shortcut | assignment |
|---|---|
<C-b> + (h|j|k|l) |
go to the window (on the left | below | above | on the right) |
<M-S-(h|j|k|l)> |
resize pane moving the border (to the left | down | up | to the right) |
<C-b> + (H|J|K|L) |
swap the window that has input focus with the one (on the left | below | above | on the right) |
<C-b>Q |
close vim buffers (saving them first if modified) and terminate tmux session |
<C-b>y |
toggle synchronous input in all panes |
<C-b>m |
toggle mouse support |
The described features correspond to zsh + Neovim setup. If you work in bash,
and your editor is Vim, then some of bindings may not be available. Moreover,
for macOS users, their default settings with command take precedence over
the ones defined by evangelist.
Troubleshooting
-
IDE
If for some reason you want to use Vim in the IDE, you will have to define
XDG base directory specification in.zshrc(since some IDEs don't read~/.zshenv). -
Vim vs Neovim
There is no much difference between them if comparing with latest Vim version.
But some plugins may produce errors in its old versions. For example,
in Vim 7.4enterfor opening a file or expanding a folder does not work.
Instead, you should useokey.
-
Ctrl-c
Currently, pressing
<C-c>during evangelist's execution kills the process group.
Since there is no clean-up procedure that would revert actions of unfinished command,
you may try to call the latter again or go from scratch withuninstall. -
_ignorecommonin zshIf some of your commands are not saved during zsh-session,
and you find this behavior undesirable, then you can remove
these commands from_ignorecommonstring in your$ZDOTDIR/extra.zsh -
Cannot enter insert mode
If you get stuck in vi-cmd mode in the shell, what happens infrequently,
you can handle this by hittingEnter,I(<S-i>),a, or any
other key combination that may be considered as an alternative toi. -
Meta key on macOS
To use shortcuts involving
Metakey on macOS, you need to check out
the Meta key option in iTerm2 preferences. Also, you may need to make
sure that there are no overlapping Meta key bindings with the ones
the system uses. In Neovim, you can try alternative bindings
involding command key (<D-...>instead of<A-...>and<M-...>). -
Tmux outputs errors on startup
If this is the case, one needs to comment out the lines/blocks
(they marked intmux.conf) that use the syntax of newer Tmux versions,
than the installed one. This will be fixed in the next patches. -
Enforce installation in a new folder
Because of the current implementation, you cannot simply change the
installation path by running./evangelist.sh install <shell>
under a new folder. You need to first unset the variable with
the installation path to an active evangelist instance:unset EVANGELIST; ./evangelist.sh install <args>
References
This work is based primarily on leveraging the following projects and resources.
| - vim-plug | a minimalist Vim plugin manager |
| - zcomet | Zsh plugin manager |
| - jupyter-vim-binding | Vim extension for Jupyter Notebook |
| - LunarVim | An IDE layer for Neovim |
| - dotfiles1
- dotfiles2 - dotfiles3 |
custom settings I found on Git |
TODO list
- Write Dockerfile
- Add
install,update,reinstall,uninstallcontrol functions - Add
EVANGELISTenvironment variable - Write bash/zsh completions
- Write Wiki evangelist
- Switch from
init.vimtoinit.lua(for Neovim) - Switch from CoC to configs with Native LSP (for Neovim)
- Test LunarVim / SpaceVim
- Tidy up the repository