Update tech_docs/vim_reference.md

2024-05-06 06:03:24 +00:00
parent dd2e248f24
commit 615d93ec8c
1 changed files with 423 additions and 0 deletions
--- a/tech_docs/vim_reference.md
+++ b/tech_docs/vim_reference.md
@@ -92,6 +92,429 @@ This outline provides a structured path for learning VIM, starting from the basi
 Feel free to adjust the outline based on your specific needs and learning goals. Remember to practice regularly and refer to the VIM documentation (`:help`) for more in-depth information on each topic.
 ---
 # VIM: Zero to Hero
 ## I. Introduction to VIM
 ### A. What is VIM?
   VIM (Vi IMproved) is a powerful, highly configurable text editor built to enable efficient text editing. It is an improved version of the vi editor, which was developed by Bill Joy in 1976. VIM is designed for users who want to edit text quickly and effectively, using only the keyboard.
 ### B. Why use VIM?
   There are several compelling reasons to learn and use VIM:
   1. Efficiency: VIM is designed to keep your hands on the keyboard, reducing the need to reach for the mouse. This can significantly improve your editing speed and productivity.
   2. Ubiquity: VIM (or vi) is pre-installed on most Unix-based systems, including Linux and macOS. Knowing VIM allows you to edit text efficiently on almost any system.
   3. Customizability: VIM is highly configurable, allowing you to tailor the editor to your specific needs and preferences.
   4. Extensibility: VIM has a large ecosystem of plugins that can extend its functionality, transforming it into a full-fledged IDE for various programming languages.
   5. Longevity: VIM's key bindings and editing model are deeply ingrained in muscle memory, making it a valuable skill that you can carry with you throughout your career.
 ### C. VIM's Modal Editing Philosophy
   One of the key features that sets VIM apart from other text editors is its modal editing philosophy. In VIM, there are several modes, each designed for a specific purpose:
   1. Normal Mode: Used for navigation and text manipulation. This is the default mode in VIM.
   2. Insert Mode: Used for inserting new text.
   3. Visual Mode: Used for selecting text and performing operations on the selection.
   4. Command-line Mode: Used for entering Ex commands and searching.
   By separating the editing process into distinct modes, VIM allows you to perform complex text manipulations efficiently, without relying on cumbersome key combinations or menus.
 ## II. Getting Started with VIM
 ### A. Installing VIM
   VIM is pre-installed on most Unix-based systems. However, if you're using Windows or want to install the latest version of VIM, you can follow these steps:
   - **Windows**: Download the installer from the official VIM website (https://www.vim.org) and run it.
   - **macOS**: Use Homebrew to install VIM by running `brew install vim` in the terminal.
   - **Linux**: Use your distribution's package manager (e.g., `apt-get install vim` on Debian-based systems, `yum install vim` on Red Hat-based systems).
 ### B. Opening and Closing Files
   To open a file in VIM, simply run `vim filename` in the terminal. If the file doesn't exist, VIM will create a new empty buffer for it.
   To save and close a file, use the following Ex commands:
   - `:w` - Save the changes to the file.
   - `:q` - Quit VIM (fails if there are unsaved changes).
   - `:wq` or `:x` - Save the changes and quit VIM.
   - `:q!` - Quit VIM without saving changes.
 ### C. Basic Navigation
 #### 1. Arrow Keys vs. hjkl
   While you can use the arrow keys to navigate in VIM, it's recommended to use the `hjkl` keys instead:
   - `h` - Move left
   - `j` - Move down
   - `k` - Move up
   - `l` - Move right
   Using `hjkl` keeps your fingers on the home row, improving your editing efficiency.
 #### 2. Word and Line Movements
   VIM provides several keys for moving by words and lines:
   - `w` - Move to the start of the next word
   - `b` - Move to the start of the previous word
   - `e` - Move to the end of the current word
   - `0` - Move to the start of the line
   - `^` - Move to the first non-blank character of the line
   - `$` - Move to the end of the line
 #### 3. Document Navigation
   To navigate through the document, you can use the following keys:
   - `gg` - Go to the first line of the document
   - `G` - Go to the last line of the document
   - `:`_`n`_`Enter` - Go to line _`n`_
   - `Ctrl+f` - Scroll forward one page
   - `Ctrl+b` - Scroll backward one page
   - `Ctrl+d` - Scroll down half a page
   - `Ctrl+u` - Scroll up half a page
 ### D. Modes in VIM
 #### 1. Normal Mode
   Normal mode is the default mode in VIM. It's used for navigation and text manipulation. To enter normal mode from any other mode, press `Esc`.
 #### 2. Insert Mode
   Insert mode is used for inserting new text. To enter insert mode from normal mode, press `i`. To return to normal mode, press `Esc`.
 #### 3. Visual Mode
   Visual mode is used for selecting text and performing operations on the selection. There are three types of visual mode:
   - Character-wise visual mode: Press `v` to enter this mode. It allows you to select text character by character.
   - Line-wise visual mode: Press `V` to enter this mode. It allows you to select entire lines.
   - Block-wise visual mode: Press `Ctrl+v` to enter this mode. It allows you to select rectangular blocks of text.
   To exit visual mode and return to normal mode, press `Esc`.
 #### 4. Command-line Mode
   Command-line mode is used for entering Ex commands and searching. To enter command-line mode from normal mode, press `:`. To execute a command, press `Enter`. To return to normal mode without executing a command, press `Esc`.
 This covers the introduction to VIM and the basics of getting started with the editor. In the following sections, we'll dive deeper into mastering VIM's features and leveraging its power for efficient text editing.
 ## III. Mastering the Basics
 ### A. Editing Text
 #### 1. Inserting and Appending Text
   In normal mode, you can use the following keys to enter insert mode:
   - `i` - Insert text before the cursor
   - `a` - Append text after the cursor
   - `I` - Insert text at the beginning of the line
   - `A` - Append text at the end of the line
   - `o` - Open a new line below the current line and enter insert mode
   - `O` - Open a new line above the current line and enter insert mode
 #### 2. Deleting, Changing, and Yanking (Copying)
   VIM provides a set of operators for manipulating text:
   - `d` - Delete text
   - `c` - Change text (delete and enter insert mode)
   - `y` - Yank (copy) text
   - `p` - Put (paste) yanked or deleted text after the cursor
   - `P` - Put yanked or deleted text before the cursor
   These operators can be combined with motions or text objects to specify the range of text to operate on. For example:
   - `dw` - Delete from the cursor to the start of the next word
   - `c$` - Change from the cursor to the end of the line
   - `yap` - Yank a paragraph
 ### B. Searching and Replacing
 #### 1. Basic Search
   To search for a pattern in VIM, use the `/` command followed by the pattern you want to search for. Press `Enter` to perform the search. To find the next occurrence, press `n`. To find the previous occurrence, press `N`.
 #### 2. Find and Replace
   VIM's `:substitute` command allows you to find and replace text:
   - `:s/old/new` - Replace the first occurrence of "old" with "new" on the current line
   - `:s/old/new/g` - Replace all occurrences of "old" with "new" on the current line
   - `:%s/old/new/g` - Replace all occurrences of "old" with "new" in the entire file
   - `:%s/old/new/gc` - Replace all occurrences of "old" with "new" in the entire file, with a prompt for confirmation before each replacement
 ### C. Using the Clipboard
 #### 1. Copying and Pasting Lines
   To copy (yank) a line, use the `yy` command in normal mode. To paste the yanked line below the current line, use the `p` command. To paste the yanked line above the current line, use the `P` command.
 #### 2. Copying and Pasting Words
   To copy (yank) a word, use the `yiw` command in normal mode ("yank inner word"). To paste the yanked word after the cursor, use the `p` command. To paste the yanked word before the cursor, use the `P` command.
 ### D. Undo and Redo
   VIM maintains an undo tree that allows you to undo and redo changes:
   - `u` - Undo the last change
   - `Ctrl+r` - Redo the last undone change
   - `U` - Undo all changes to the current line
 ## IV. Leveraging the Power of VIM
 ### A. Text Objects and Motions
 #### 1. Word and WORD Text Objects
   VIM distinguishes between words (separated by punctuation or whitespace) and WORDs (separated by whitespace only):
   - `w` - Move to the start of the next word
   - `b` - Move to the start of the previous word
   - `e` - Move to the end of the current word
   - `W` - Move to the start of the next WORD
   - `B` - Move to the start of the previous WORD
   - `E` - Move to the end of the current WORD
   These motions can be combined with operators like `d`, `c`, and `y` to operate on words and WORDs.
 #### 2. Sentence and Paragraph Text Objects
   VIM provides text objects for manipulating sentences and paragraphs:
   - `(` - Move to the start of the current sentence
   - `)` - Move to the end of the current sentence
   - `{` - Move to the start of the current paragraph
   - `}` - Move to the end of the current paragraph
   These text objects can be combined with operators like `d`, `c`, and `y` to operate on sentences and paragraphs. For example:
   - `dis` - Delete the current sentence (excluding the space after the period)
   - `cip` - Change the current paragraph
 #### 3. Code Block Text Objects
   VIM provides text objects for manipulating code blocks:
   - `[{` - Move to the start of the current code block
   - `]}` - Move to the end of the current code block
   These text objects can be combined with operators like `d`, `c`, and `y` to operate on code blocks. For example:
   - `di{` - Delete the contents of the current code block (excluding the braces)
   - `ya}` - Yank the current code block (including the braces)
 #### 4. Combining Text Objects with Motions
   Text objects can be combined with numeric arguments to operate on multiple instances. For example:
   - `d2w` - Delete the next two words
   - `c3s` - Change the next three sentences
   - `y4p` - Yank the next four paragraphs
 ### B. Visual Mode and Text Selection
 #### 1. Character-wise Visual Mode
   Character-wise visual mode allows you to select text character by character. To enter this mode, press `v` in normal mode. You can then use motion commands to expand the selection. To operate on the selected text, use operators like `d`, `c`, `y`, `p`, `U` (uppercase), `u` (lowercase), `>` (indent), and `<` (unindent).
 #### 2. Line-wise Visual Mode
   Line-wise visual mode allows you to select entire lines. To enter this mode, press `V` in normal mode. You can then use motion commands to expand the selection. The same operators mentioned above can be used to operate on the selected lines.
 #### 3. Block-wise Visual Mode
   Block-wise visual mode allows you to select rectangular blocks of text. To enter this mode, press `Ctrl+v` in normal mode. You can then use motion commands to expand the selection. This mode is particularly useful for working with tabular data or making column-based edits.
 #### 4. Operating on Selected Text
   Once you have made a selection in visual mode, you can use various operators to manipulate the selected text:
   - `d` - Delete the selected text
   - `c` - Change the selected text (delete and enter insert mode)
   - `y` - Yank (copy) the selected text
   - `p` - Put (paste) the yanked text after the cursor
   - `U` - Convert the selected text to uppercase
   - `u` - Convert the selected text to lowercase
   - `>` - Indent the selected text
   - `<` - Unindent the selected text
 ### C. Ex Commands
 #### 1. Opening and Saving Files
   - `:e filename` - Open "filename" in a new buffer
   - `:w` - Save the current buffer
   - `:sav filename` - Save the current buffer as "filename"
   - `:q` - Quit the current buffer (fails if there are unsaved changes)
   - `:q!` - Force quit the current buffer (discards unsaved changes)
   - `:wq` or `:x` - Save the current buffer and quit
   - `:wa` - Save all buffers
   - `:qa` - Quit all buffers (fails if there are unsaved changes)
   - `:qa!` - Force quit all buffers (discards unsaved changes)
 #### 2. Line Manipulation
   - `:n` - Go to line "n"
   - `:$` - Go to the last line
   - `:.` - Repeat the last command
   - `:m n` - Move the current line to after line "n"
   - `:copy n` or `:t n` - Copy the current line and paste it after line "n"
   - `:d` - Delete the current line
   - `:'<,'>d` - Delete the visually selected lines
 #### 3. Searching and Replacing
   - `:/pattern` - Search forward for "pattern"
   - `:?pattern` - Search backward for "pattern"
   - `:s/old/new` - Replace the first occurrence of "old" with "new" on the current line
   - `:s/old/new/g` - Replace all occurrences of "old" with "new" on the current line
   - `:%s/old/new/g` - Replace all occurrences of "old" with "new" in the entire file
   - `:%s/old/new/gc` - Replace all occurrences of "old" with "new" in the entire file with confirmation
 #### 4. Filtering and Executing External Commands
   - `:r filename` - Insert the contents of "filename" below the cursor
   - `:r !command` - Execute "command" in the shell and insert its output below the cursor
   - `:%!command` - Execute "command" in the shell with the entire buffer as input and replace the buffer with the command's output
 #### 5. Managing Multiple Files
   - `:e filename` - Edit "filename" in a new buffer
   - `:bn` - Go to the next buffer
   - `:bp` - Go to the previous buffer
   - `:bd` - Close (delete) the current buffer
   - `:ls` - List all open buffers
 #### 6. Setting Options
   - `:set option` - Enable "option"
   - `:set nooption` - Disable "option"
   - `:set option=value` - Set "option" to "value"
   - `:set option?` - Show the current value of "option"
   - `:set` - Show all modified options
   - `:set all` - Show all options
   Some common options include:
   - `number` or `nu` - Show line numbers
   - `relativenumber` or `rnu` - Show relative line numbers
   - `ignorecase` or `ic` - Ignore case when searching
   - `smartcase` or `scs` - Override "ignorecase" when the search pattern contains uppercase characters
   - `expandtab` or `et` - Use spaces instead of tabs
   - `tabstop=n` or `ts=n` - Set the width of a tab character to "n" spaces
   - `shiftwidth=n` or `sw=n` - Set the indentation width to "n" spaces
   - `autoindent` or `ai` - Enable automatic indentation
 ### D. Marks and Jumps
 #### 1. Setting and Jumping to Marks
   Marks allow you to quickly return to specific locations in your files:
   - `m{a-zA-Z}` - Set a mark labeled "{a-zA-Z}" at the cursor position
   - `` `{a-zA-Z}`` - Jump to the mark labeled "{a-zA-Z}"
   - `''` - Return to the last jump position
 #### 2. Using the Jumplist
   VIM maintains a jumplist that remembers the previous locations you've jumped to:
   - `Ctrl+o` - Jump to the previous location in the jumplist
   - `Ctrl+i` - Jump to the next location in the jumplist
   - `:jumps` - Show the jumplist
 ### E. Registers
 #### 1. Unnamed Register
   The unnamed register (`""`) is used by default when you delete, yank, or put text without specifying a register.
 #### 2. Named Registers
   Named registers (`"{a-zA-Z}`) allow you to store and recall text:
   - `"{a-zA-Z}d` - Delete text into register "{a-zA-Z}"
   - `"{a-zA-Z}y` - Yank text into register "{a-zA-Z}"
   - `"{a-zA-Z}p` - Put the text from register "{a-zA-Z}"
 #### 3. System Clipboard Register
   The system clipboard register (`"+`) allows you to interact with the system clipboard:
   - `"+y` - Yank text into the system clipboard
   - `"+p` - Put the text from the system clipboard
 #### 4. Read-Only Registers
   VIM provides several read-only registers for accessing special information:
   - `"%` - Contains the current file name
   - `"#` - Contains the alternate file name
   - `".` - Contains the last inserted text
   - `":` - Contains the last executed command
   - `"/` - Contains the last searched pattern
 This section covers the essential features and commands for mastering VIM and leveraging its power for efficient text editing. In the following sections, we'll explore how to customize VIM, learn some useful tips and tricks, and integrate VIM with other tools.
 ## V. Customizing VIM
 ### A. The .vimrc File
   The `.vimrc` file is used to configure VIM according to your preferences. It is a plain text file that contains VIM commands and is executed every time you start VIM. You can create or edit the `.vimrc` file in your home directory:
   - Unix-like systems: `~/.vimrc`
   - Windows: `%USERPROFILE%\_vimrc`
 ### B. Basic Settings
   Here are some basic settings you might want to include in your `.vimrc` file:
   ```vim
   " Enable syntax highlighting
   syntax on
   " Enable line numbers
   set number
   " Enable relative line numbers
   set relativenumber
   " Enable auto-indentation
   set autoindent
   " Convert tabs to spaces
   set expandtab
   " Set the tab width to 4 spaces
   set tabstop=4
   set shiftwidth=4
   " Enable case-insensitive searching
   set ignorecase
   " Enable smart case-sensitive searching
   set smartcase
   " Enable highlighting of search results
   set hlsearch
   " Enable incremental searching
   set incsearch
   " Disable creating backup files
   set nobackup
   set nowritebackup
   set noswapfile
   ```
 ### C. Key Mappings
   You can create custom key mappings in your `.vimrc` file to simplify common tasks or to make VIM behave more like other editors you're used to. Here are some examples:
   ```vim
   " Map the 'jk' key sequence to escape insert mode
   inoremap jk <Esc>
   " Map 'Ctrl+s' to save the current file
   nnoremap <C-s> :w<CR>
   " Map 'Ctrl+q' to close the current buffer
   nnoremap <C-q> :bd<CR>
   " Map 'Ctrl+h/j/k/l' to navigate between split windows
   nnoremap <C-h> <C-w>h
   nnoremap <C-j> <C-w>j
   nnoremap <C-k> <C-w>k
   nnoremap <C-l> <C-w>l
   ```
   Note: `inoremap` is used for insert mode mappings, `nnoremap` is used for normal mode mappings, and `<CR>` represents the Enter key.
 ### D. Plugins
 #### 1. Plugin Managers
   Plugin managers make it easy to install, update, and remove VIM plugins. Some popular plugin managers include:
   - [Vundle](https://github.com/VundleVim/Vundle.vim)
   - [vim-plug](https://github.com/junegunn/vim-plug)
   - [Pathogen](https://github.com/tpope/vim-pathogen)
   To use a plugin manager, follow the installation instructions in its documentation and add the necessary configuration to your `.vimrc` file.
 #### 2. Essential Plugins
   Here are some essential plugins that can greatly enhance your VIM experience:
   - [NERDTree](https://github.com/preservim/nerdtree) - A file explorer sidebar
   - [CtrlP](https://github.com/ctrlpvim/ctrlp.vim) - A fuzzy file finder
   - [Syntastic](https://github.com/vim-syntastic/syntastic) - A syntax checking plugin
   - [vim-surround](https://github.com/tpope/vim-surround) - Easily manipulate surrounding characters (brackets, quotes, tags, etc.)
   - [vim-commentary](https://github.com/tpope/vim-commentary) - Easily comment and uncomment lines of code
   - [vim-fugitive](https://github.com/tpope/vim-fugitive) - A Git wrapper for VIM
   - [vim-airline](https://github.com/vim-airline/vim-airline) - A customizable status line and tabline
   To install a plugin using a plugin manager, add the necessary configuration to your `.vimrc` file and run the appropriate installation command provided by the plugin manager.
 ### E. Color Schemes
   Color schemes can make your VIM experience more visually appealing and comfortable. Here's how you can install and configure color schemes:
   1. Download a color scheme file (`.vim`) from a source like [vim-colors](https://github.com/rainglow/vim) or [Vim Colors](http://vimcolors.com/).
   2. Place the color scheme file in the `~/.vim/colors/` directory (create it if it doesn't exist).
   3. Add the following line to your `.vimrc` file to enable the color scheme:
      ```vim
      colorscheme <scheme_name>
      ```
      Replace `<scheme_name>` with the name of the color scheme file (without the `.vim` extension).
   4. Restart VIM for the changes to take effect.
   Some popular color schemes include:
   - [gruvbox](https://github.com/morhetz/gruvbox)
   - [solarized](https://github.com/altercation/vim-colors-solarized)
   - [dracula](https://github.com/dracula/vim)
   - [onedark](https://github.com/joshdick/onedark.vim)
 Customizing VIM allows you to tailor the editor to your specific needs and preferences, making it a more comfortable and efficient environment for your text editing tasks. Experiment with different settings, key mappings, plugins, and color schemes to find the configuration that works best for you.
 Remember to keep your `.vimrc` file organized and well-commented, as it can quickly grow in complexity as you add more customizations. It's also a good idea to keep your `.vimrc` file under version control (e.g., in a Git repository) so that you can easily track changes and synchronize your configuration across different machines.
 ---
 Vim (Vi IMproved) is an enhanced version of the original Vi (Visual) editor. While Vim and Vi share many similarities, Vim offers a wide range of additional features and improvements that make it more powerful and user-friendly. Most of the basic concepts and commands that I mentioned earlier are applicable to both Vim and Vi. However, Vim extends and builds upon Vi's functionality.