Configure Vim

Vim configurations and customizations

---

• ⬆️ Top of Document

• 🏗️ Requirements

• ⚡ Quick Start

• 🧰 Usage

  • Vim GitGutter

  • Vim Go

  • Typescript Syntax for Vim

  • Emmet Vim

  • Gruvbox

  • Spell Under

  • UltiSnips

  • Vim Prettier

  • Expand Region

  • Vim Solidity (Syntax)

  • Fugitive

  • Commentary

  • Balanced Backspace

  • Balanced Braces

  • Balanced Quotes

  • Date Time

  • Emoji Syntax

  • MarkDown Headings

  • MarkDown Surrounds

  • Nudge Lines

  • Spelling Shortcuts

  • Splits Jump

  • Splits Resize

  • Lorem Ipsum

  • Rust Vim

  • Syntastic

  • You Complete Me

• 🗒 Notes

• 📈 Contributing

  • 🔱 Forking
  • 💱 Sponsor

• 📇 Attribution

• ⚖️ Licensing

---

Requirements

Awk, GAwk, or MAwk must be installed to make use of scripts within this repository, for Debian based Linux distributions that'd be similar to...

sudo apt-get install gawk

---

This repository requires the [Vim][vim_home] text editor to be installed the source code is available on GitHub -- vim/vim, and most GNU Linux package managers are able to install Vim directly, eg...

• Arch

  sudo packman -Syy
  
  sudo packman -S gvim

• Debian

  sudo apt-get update
  
  sudo apt-get install gvim

• Termux

  pkg install vim-python

Note, some configurations target Vim version 8.2 (or greater) features

Note; on desktop distributions for clipboard customization, and various plugins, gvim is recommended

Note; on mobile environments vim-python is recommended if attempting to use YouCompleteMe plugin features

---

For MakeTags Vim command ctags must be installed, eg...

• Arch

  sudo pacman -S ctags

• Debian

  sudo apt-get install exuberant-ctags

---

For the YouCompleteMe plugin you may need to install additional dependencies via distribution package manager, eg...

• Arch

  sudo pacman -S gcc go jdk-openjdk

• Debian

  sudo apt-get update
  
  sudo apt-get install g++-8          #> Provides C
  sudo apt-get install golang-go      #> Provided Go
  sudo apt-get install openjdk-8-jdk  #> Provides Java

... as well as manually install Rust and TypeScript via other methods, eg...

• Arch / Debian / most other desktop distributions

  #> Download and install Rust
  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  
  #> Add and download TypeScript to project dependencies
  cd <project> && npm install --save-dev typescript

• Termux

  pkg install rust

• LSP clients

  mkdir "${HOME}/git/hub/ycm-core"
  pushd "${_}"
  git clone git@github.com:ycm-core/lsp-examples.git
  pushd "lsp-examples"
  ## Un-comment/run the following if errors are raised
  # git remote add fork git@github.com:S0AndS0/lsp-examples.git
  # git fetch fork
  ./install.py \
    --enable-astro \
    --enable-bash \
    --enable-css \
    --enable-docker \
    --enable-erlang \
    --enable-postgres \
    --enable-ruby

---

For Rust Vim plugin, in addition to Rust it may be necessary to explicitly install the analyzer too

• Arch / Debian / most other desktop distributions

  rustup component add rust-src

• Termux

  pkg install rust-src

... Though provided that rustup is installed, then make install will attempt to do above via PlugInstall commands.

---

For the Syntastic plugin the shellcheck dependency may be installed via distribution package manager...

• Arch

  sudo pacman -S shellcheck

• Debian

  sudo apt-get install shellcheck

... as well as checkbashisms, which is often bundled with devscripts package...

• Arch

  sudo pacman -S checkbashisms

• Debian

  sudo apt-get install devscripts

Warning, the file-type recognition of Syntastic seems to be a little buggy for Bash script which by default are treated as sh scripts!

---

Git should be configured with GitHub for upgrade/update processes to function properly...

git config --global user.name='YourGitHubName'

git config --global user.email='Name@Domain.TLD'

... Because local customizations are tracked by Git during the update process to mitigate risks of unintentional and/or unrecoverable overwrites.

---

For Solidity compiler npm and truffle are required

npm install -g truffle

---

For Prettier yarn is required

npm install -g yarn

---

Quick Start

Clone this project...

mkdir -vp ~/git/hub/S0AndS0

cd ~/git/hub/S0AndS0

git clone git@github.com:S0AndS0/configure-vim.git

Backup your current configurations...

[[ -f ~/.vimrc ]] && {
    mv ~/.vimrc ~/.vimrc.bak
}


[[ -d ~/.vimrc.d ]] && {
    mv ~/.vimrc.d ~/.vimrc.d.bak
}

Make commands may then be used to install, upgrade, or uninstall configurations...

make install

The install target will make symbolic links for ./vimrc file and recursively for files within ./vimrc.d/ directory, checkout a local branch for further customization, then download and install plugins via Plug

make uninstall

The uninstall target will remove symbolic links and empty sub-directories within ~/.vimrc.d/, and remove the Vim script for Plug

make upgrade

The upgrade target will remove current symbolic links, fetch configuration updates, merge non-conflicting changes, rebuild symbolic links, and then attempt to upgrade Plug script and plugins

Note, the merge process attempts to be nondestructive by using the ours target; meaning that anytime a merge conflict may arise local customizations are used automatically.

---

Usage

Once installed open a new Vim session to experiment with new configurations.

The following sub-sections cover some, but not all, plugins installed and configured by this repository; as well as some, but not all, common usage examples when applicable. For plugin management the Plug Vim script is utilized, check the configurations for details and full list of plugins that are used.

---

Vim GitGutter

Source: A Vim plugin which shows a git diff in the sign column.

Documentation

help gitgutter.txt

Normal mode mappings

• Stage the hunk under the cursor

<Leader>hs

• Preview the hunk under the cursor

<Leader>hp

• Undo the hunk under the cursor

<Leader>hu

Check the official documentation for more mappings and configuration guidance.

---

Vim Go

Source: Go development plugin for Vim

After installation via Plug run the following Vim Ex mode command to download and install dependencies;

:GoInstallBinaries

---

Solidity Compiler

Source

Run Ex mode :make command within any .sol file

:make

Tip, check trufflesuite/truffle issue 2217 if "EACCESS: permission denied" errors pop.

---

Typescript Syntax for Vim

Source: Syntax file and other settings for TypeScript.

Should be enabled automatically for TypeScript file-types, and/or .ts file suffixes. Check the official documentation for configuration guidance.

---

Emmet Vim

Source: emmet-vim is a vim plug-in which provides support for expanding abbreviations similar to emmet

Documentation

help emmet.txt

Insert mode mappings

Expand abbreviation or word uses the following key sequence

<C-y>,

• Build a new HTML5 file from template

html:5

• Expand nested elements example

div>p#foo$*3>a

... example results...

  <div>
      <p id="foo1">
          <a href=""></a>
      </p>
      <p id="foo2">
          <a href=""></a>
      </p>
      <p id="foo3">
          <a href=""></a>
      </p>
  </div>

Check the official documentation for more mappings and configuration guidance.

Note, this plugin sets omnifunc=emmet#completeTag

set omnifunc=emmet#completeTag
setlocal omnifunc=emmet#completeTag

---

Gruvbox

Source: Designed as a bright theme with pastel 'retro groove' colors and light/dark mode switching in the way of solarized

Check the official documentation for configuration guidance.

---

Spell Under

Source: plugin to change highlight scheme of spelling checker to use "UNDERLINE" instead of default "REVERSE" for color terminals when :colorscheme is set

Check the official documentation for configuration guidance.

---

UltiSnips

Source: UltiSnips - The ultimate snippit solution for Vim

Insert mode

• Ctrl ^ Enter → Expand snippit
• Tab → Next tab-stop
• Shift ^ Tab → Previous tab-stop

Warning for <C-CR> to be passed to Vim correctly may, often will, require configuring the terminal emulator too;

• Alacritty ~/.config/alacritty/alacritty.yml (snip)

  key_bindings:
    - { key: Return,  mods: Control,  chars: "\x1b[13;5u" }

---

Expand Region

Source allows you to visually select increasingly larger regions of text

Documentation

help vim-expand-region.txt

Visual mode

• + Expand visual selection

• _ Contract visual selection

Check the official documentation for configuration guidance.

---

Vim Solidity (Syntax)

Source: Syntax files for Solidity, the contract-oriented programming language for Ethereum

---

Abolish

Source: easily search for, substitute, and abbreviate multiple variants of a word

help abolish.txt

Visual mode mappings

• Start Subvert search/replace for highlighted text

Ctrl^r

---

Vim Prettier

Source: Vim plugin wrapper for Prettier

Note Solidity Prettier plugin is included when installing this Vim plugin.

Documentation

help vim-prettier.txt

Ex mode commands

:Prettier

---

Fugitive

Source: Fugitive is the premier Vim plugin for Git. Or maybe it's the premier Git plugin for Vim?

Documentation

help fugitive.txt

Ex mode commands

This plugin encapsulates many Git features via :Git or :G prefix

• Commit staged changes

G commit

• Rename current file buffer and preform git mv

GMove new-name.ext

• Push changes

Git push

Check the official documentation for more mappings and configuration guidance.

---

Commentary

Source: Comment stuff out

Documentation

help commentary.txt

Normal mode mappings

• Comment or uncomment current line

gcc

• Comment or uncomment lines that {motion} moves over

gc{motion}

Visual mode mappings

• Comment or uncomment the highlighted lines

{Visual}gc

Check the official documentation for more mappings and configuration guidance.

---

Balanced Backspace

Source: Attempts to balance removal of quotes and braces

Documentation

help balanced-backspace.txt

Insert mode mappings

Pressing backspace...

<BS>

... within empty and open; curly-brace, parenthesis, square-braces, double-quotes, single-quotes, or backticks, will remove closing symbol of the same type.

Behaviour may be modified for individual, or all, file-types recognized by Vim; check the documentation for details.

Configuration

---

Balanced Braces

Source: Balance parentheses, curly-braces, and square-brackets

Documentation

help balanced-braces.txt

Insert mode mappings

For most files an opening; curly-brace, parenthesis, or square-bracket, will insert the closing symbol after the cursor position.

And a closing; curly-brace, parenthesis, or square-bracket, when cursor is already on one of those symbols will cause the cursor to move left once.

Behaviour may be modified for individual, or all, file-types recognized by Vim; check the documentation for details.

Configuration

---

Balanced Quotes

Source: Attempts to balance quotes in unobtrusive ways

Documentation

help balanced-quotes.txt

Insert mode mappings

For most file-types an opening; single-quote, double-quote, or backtick, will insert a closing symbol after the cursor.

And a closing/repealed; single-quote, double-quote, or backtick, when the cursor is on a closing symbol will cause the cursor to move left once.

Note, this plugin will look backwards on the same line to determine if quotes need to be balanced or if the cursor should instead be moved.

Because of specific conditional logic this plugin allows for triple quotes to be inserted, this is to avoid annoying Python developers and MarkDown authors.

Behaviour may be modified for individual, or all, file-types recognized by Vim; check the documentation for details.

Configuration

---

Date time

Source: Commands for injecting date and/or time into current buffer

Documentation

:help date-time.txt

Normal mode mappings

• <Leader>d Append current date after cursor position

• <Leader>D Insert current date before/at cursor position

• <Leader>t Append current time after cursor position

• <Leader>T Insert current time before/at cursor position

Visual select mode mappings

• <Leader>R Replace visual selection with date/time

---

Emoji Syntax

Source: Vim syntax for emoji conceal characters

Documentation

help emoji-syntax.txt

Ensure that conceallevel is greater than 0 and that filetype is recognized as markdown

set conceallevel=1

---

MarkDown Headings

Source: Vim plugin that adds short-cuts/commands for MarkDown headings

Documentation

help markdown-heading-transform.txt

help markdown-heading-link.txt

Normal mode mappings

Note, by default mappings are activated only for markdown file-type

• Change current line to a heading of specified level, or update current heading level

<Leader>h1 - <Leader>h4

• Add or update reference link to current heading line

<Leader>hl

---

MarkDown Surrounds

Source: Toggles MarkDown elements; bold, italic, and strike-through

Documentation

help markdown-surrounds.txt

Normal mode mappings

Note, by default mappings are activated only for markdown file-type

• Toggle bold state of current (big) word or line

<Leader>b

<Leader>B

• Toggle italic state of current (big) word or line

<Leader>i

<Leader>I

• Toggle highlight state of current (big) word or line

<Leader>hi

<Leader>HI

• Toggle strike-through state of current (big) word or line

<Leader>st

<Leader>ST

---

Nudge Lines

Source: Vim plugin that nudges visually selected lines up or down

Documentation

help nudge-lines.txt

Visual mode mappings

• Move selected line(s) up, combine with Shift to attempt indentation reformatting

<C-k>

<C-K>

• Move selected line(s) down, combine with Shift to attempt indentation reformatting

<C-j>

<C-J>

Note, either set of motions may be prefixed with a count, eg. 5<C-k> will move selection five lines upwards.

Warning, combining count with Shift has undefined behavior.

---

Spelling Shortcuts

Source: Replaces misspelled word with first suggested correction

Documentation

help spelling-shortcuts.txt

Normal mode mappings

• Accept first spelling correction for previous word

<Leader>sp

• Accept first spelling correction for current word

<Leader>sc

• Accept first spelling correction for next word

<Leader>sn

---

Splits Jump

Source: Vim plugin for jumping between splits swiftly

Documentation

help splits-jump.txt

Normal mode mappings

• Relative jump to split above

<C-k>

• Relative jump towards left split

<C-l>

• Relative jump to split below

<C-j>

• Relative jump towards right split

<C-h>

---

Splits Resize

Source: Vim plugin for re-sizing splits swiftly

Documentation

help splits-jump.txt

Normal mode mappings

• Resize active vertical split by -2

<A-h>

• Resize active horizontal split by +2

<A-j>

• Resize active horizontal split by -2

<A-k>

• Resize active vertical split by +2

<A-l>

Note, any of above motions may be prefixed with a count to override the default of 2 rows/columns, eg. 5<A-l> will resize an active vertical split by +5 instead of +2

Additionally, to improve compatibility with various devices <ESC> or Meta-key may be used instead of Alt

---

Lorem Ipsum

Source: Insert a dummy text of a certain length

Documentation

help loremipsum.txt

Ex mode commands

:Loremipsum [WORDCOUNT] [PARAGRAPH_TEMPLATE] [PREFIX POSTFIX]

:Loreplace [REPLACEMENT] [PREFIX] [POSTFIX]

---

Rust Vim

Source

Documentation

help rust.txt

help rust-syntastic.txt

Check the official documentation for configuration guidance.

Configuration

---

Syntastic

Source: Syntastic is a syntax checking plugin for Vim created by Martin Grenfell

Documentation

help syntastic.txt

Ex mode commands

• Output information about checkers available for file-type

SyntasticInfo

• Manually cause a syntax check

SyntasticCheck

Check the official documentation for configuration guidance.

Configuration

---

You Complete Me

Source: a code-completion engine for Vim

Documentation

help youcompleteme

Normal mode mappings

Jump to definition

<Leader>jd

Ex mode commands

• Open quick-fix split

YcmDiags

• Echos the type of the variable or method under the cursor, and where it differs, the derived type.

YcmCompleter GetType

• Displays the preview window populated with quick info about the identifier under the cursor

YcmCompleter GetDoc

• Where available, attempts to make changes to the buffer to correct diagnostics on the current line

YcmCompleter FixIt

Check the official documentation for more mappings and configuration guidance.

Configuration

---

Notes

This repository may not be feature complete and/or fully functional, Pull Requests that add features or fix bugs are certainly welcomed.

---

Because there are many plugins utilized by this set of configurations, here are a few performance profiling tips...

• Profile time spent on syntax highlighting

syntax off
syntime on
syntax on

" ... Scroll about for a bit...

syntime report

• Profile time spent executing functions and various Vim scripts

profile start /tmp/vim-profile.log
profile func *
profile file *

" ... preform actions...

profile pause
noautocmd qall!

---

Contributing

Options for contributing to configure-vim and S0AndS0

---

Forking

Start making a Fork of this repository to an account that you have write permissions for.

• Add remote for fork URL. The URL syntax is git@github.com:<NAME>/<REPO>.git...

cd ~/git/hub/S0AndS0/configure-vim

git remote add fork git@github.com:<NAME>/configure-vim.git

• Commit your changes and push to your fork, eg. to fix an issue...

cd ~/git/hub/S0AndS0/configure-vim


git commit -F- <<'EOF'
:bug: Fixes #42 Issue


**Edits**


- `<SCRIPT-NAME>` script, fixes some bug reported in issue
EOF


git push fork main

Note, the -u option may be used to set fork as the default remote, eg. git push -u fork main however, this will also default the fork remote for pulling from too! Meaning that pulling updates from origin must be done explicitly, eg. git pull origin main

• Then on GitHub submit a Pull Request through the Web-UI, the URL syntax is https://github.com/<NAME>/<REPO>/pull/new/<BRANCH>

Note; to decrease the chances of your Pull Request needing modifications before being accepted, please check the dot-github repository for detailed contributing guidelines.

---

Sponsor

Thanks for even considering it!

Via Liberapay you may on a repeating basis.

Regardless of if you're able to financially support projects that S0AndS0 maintains, please consider sharing projects that are useful with others, because one of the goals of maintaining Open Source repositories is to provide value to the community.

---

Attribution

• GitHub -- github-utilities/make-readme

• GitHub -- mcantor/no_plugins

• GitHub -- junegunn/vim-plug

• GitHub -- vim-syntastic/syntastic

• GitHub -- vim-syntastic/syntastic

• GitHub Gist -- jackkinsella/.vimrc

• GitHub -- rust-lang/rustup -- Issue 2411

• GitHub -- tpope/vim-markdown

• GitHub -- tran-simon/fuchsia -- docs/development/languages/rust/editors.md

• Rust Analyzer -- Installation

• Rust Analyzer -- Installation

• Shapeshed -- Vim: you don't need NERDtree or (maybe) netrw

• Shortcut Foo -- Top 50 Vim Configuration Options

• StackOverflow -- how do I make vim do normal bash like tab completion for file names

• StackOverflow -- How to get path to the current vimscript being executed

• StackOverflow -- How to see which plugins are making Vim slow?

• StackOverflow -- map shift tab in vim to inverse tab in vim

• StackOverflow -- vim how to turn off search highlight after timeout x seconds

• Reddit -- How to automatically close netrw when exiting a file?

• YouTube -- A look through my vimrc

• YouTube -- Advanced Vim Workflows

• YouTube -- Damian Conway, 'More Instantly Better Vim' - OSCON 2013

• YouTube -- Using Vim's Built in Complete Menu for Autocompleting Words

• YouTube -- Vim as a Python IDE - Martin Brochhaus

• YouTube -- Vim Life: VimRC update plugins and Autocmds

• VI StackExchange -- What's t_TE and t_TI added by vim8?

• VI StackExchange Why doesn't the backspace key work in insert mode?

• VI StackExchange -- Cycle through autocomplete menu using tab

• VI StackExchange -- vim ex mode write to stdout

• VI StackExchange -- Vim slows down over time with syntax on

---

License

Vim configurations and customizations
Copyright (C) 2024 S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, version 3 of the License.

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 Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

For further details review full length version of AGPL-3.0 License.