neovim-fundamentals.md

Using NeoVim effectively requires mastering its keybindings, understanding how to navigate between modes, and leveraging plugins and customization to streamline your workflow. Here's a structured guide to get you started and maximize your efficiency:

1. Master the Modes

NeoVim has multiple modes, and the most effective way to use it is by switching between them efficiently.

• Normal Mode: This is the default mode (press Esc to enter it).

  • In this mode, you move around and manipulate text without actually inserting any.

• Insert Mode: This is the mode for typing text (enter it by pressing i, a, o, etc.).

  • Press Esc to return to Normal mode from Insert mode.

• Visual Mode: Used for selecting text. You can enter Visual mode by pressing v.

  • Press V for Line Visual Mode to select entire lines.

• Command Mode: Used for executing commands (start it with : in Normal mode).

  • Commands like :wq (write and quit) and :q! (quit without saving) are entered here.

2. Essential Navigation

Navigating within a file in NeoVim can be done much faster using keybindings rather than relying on arrow keys or mouse.

Movement

• h/j/k/l: Move left, down, up, right.
• w: Jump to the start of the next word.
• b: Jump to the start of the previous word.
• 0: Jump to the beginning of the line.
• $: Jump to the end of the line.
• gg: Jump to the top of the file.
• G: Jump to the bottom of the file.
• Ctrl-u: Move up half a page.
• Ctrl-d: Move down half a page.

Searching

• /: Search forward (type your search term after /).
• n: Jump to the next occurrence of the search.
• N: Jump to the previous occurrence.

3. Efficient Editing

Insert Mode Shortcuts

• i: Enter insert mode before the current character.
• I: Enter insert mode at the beginning of the line.
• a: Enter insert mode after the current character.
• A: Enter insert mode at the end of the line.
• o: Insert a new line below and enter insert mode.
• O: Insert a new line above and enter insert mode.

Copy, Cut, and Paste

• y: Yank (copy) text. yw yanks a word, yy yanks a line.
• d: Delete (cut) text. dw deletes a word, dd deletes a line.
• p: Paste after the cursor.
• P: Paste before the cursor.

Undo and Redo

• u: Undo the last action.
• Ctrl + r: Redo the undone action.

Visual Mode Editing

• v: Enter visual mode to select text.
• V: Enter line-wise visual mode.
• y: Yank the selected text.
• d: Delete the selected text.
• >: Indent the selected text.
• <: Un-indent the selected text.

4. Working with Multiple Files and Buffers

Opening Files

• :e filename: Open a new file.
• :w filename: Save the current file under a new name.

Buffers (Files)

• :ls: List open buffers.
• :b1: Switch to buffer 1 (replace 1 with the buffer number).
• :bd: Close the current buffer.

Splitting Windows

• :split filename: Open a file in a horizontal split.
• :vsplit filename: Open a file in a vertical split.
• Ctrl-w + w: Switch between windows.
• Ctrl-w + q: Close the current window.

Tabs

• :tabnew filename: Open a file in a new tab.
• :tabnext: Go to the next tab.
• :tabprev: Go to the previous tab.

5. Essential Plugins for Productivity

To further enhance your NeoVim experience, you'll need a few plugins. Here’s how to use them effectively:

File Explorer: Nvim-Tree

Use nvim-tree for file navigation. This plugin acts as a file explorer inside NeoVim.

• Toggle file tree: <leader>e
• Navigate directories: Use arrow keys to expand/collapse directories.

Fuzzy Finder: Telescope

Use Telescope to quickly search files, functions, and more.

• Search files: <leader>f
• Search for text inside files: <leader>g
• Search recent files: <leader>r

Git Integration: Gitsigns

Use gitsigns to track changes directly in your editor.

• Stage hunk: :Gitsigns stage_hunk
• Undo stage hunk: :Gitsigns undo_stage_hunk
• Preview hunk: :Gitsigns preview_hunk

6. Code Intelligence with LSP (Language Server Protocol)

For programming languages, LSP support is crucial for autocompletion, linting, and formatting.

Common LSP Commands:

• Go to definition: gd
• Show hover documentation: K
• Show diagnostics (errors): :LspDiagnostics
• Code actions: :LspCodeAction

Completion with nvim-cmp:

If you're using nvim-cmp for completion, this allows you to autocomplete code suggestions:

• Tab: Cycle through completion suggestions.
• Enter: Select the completion.

7. Visual Enhancements

Make your NeoVim stylish:

• Theme: Use a visually pleasing theme like tokyonight.nvim by adding it to your init.lua and activating it via vim.cmd[[colorscheme tokyonight]].
• Lualine: Configure lualine for a modern status line.

Example of configuring lualine:

require('lualine').setup {
  options = {
    theme = 'tokyonight'
  }
}

8. Key Mappings for Efficiency

Custom key mappings can significantly speed up your workflow. Here are a few to make your life easier:

-- Save file with Ctrl+s
vim.api.nvim_set_keymap('n', '<C-s>', ':w<CR>', { noremap = true, silent = true })

-- Close file with Ctrl+q
vim.api.nvim_set_keymap('n', '<C-q>', ':q<CR>', { noremap = true, silent = true })

-- Quick exit from insert mode using 'jj' 
vim.api.nvim_set_keymap('i', 'jj', '<Esc>', { noremap = true, silent = true })

9. Explore NeoVim's Help System

NeoVim has excellent documentation. Use :help to access it anytime. For example, to learn more about yank, you can run:

:help yank

10. Practice

The more you use NeoVim, the more natural its powerful shortcuts and keybindings will feel. Take time to practice, and soon, your speed and efficiency will dramatically increase.

Cheat Sheet Summary

Action	Command/Keybinding
Save and quit	:wq
Quit without saving	:q!
Enter insert mode	i, a, o
Enter normal mode	Esc
Move by word	w (forward), b (backward)
Jump to start/end of line	0 (start), $ (end)
Yank (copy)	yy (line), yw (word)
Paste	p (after), P (before)
Undo/Redo	u (undo), Ctrl+r (redo)
Open a file	:e filename
Split window horizontally/vertically	:split / :vsplit
Fuzzy file search (Telescope)	<leader>f
Toggle file tree	<leader>e

By mastering these commands and keybindings, you'll start to navigate and edit code in NeoVim far more effectively!

Using the Terminal in Neovim

NeoVim includes a built-in terminal emulator, which allows you to run a terminal session directly within your editor. This is a powerful feature for staying inside the NeoVim environment while performing tasks like running scripts, compiling code, or interacting with your system shell.

How to Open and Use a Terminal in NeoVim

1. Open a Terminal

To open a terminal in NeoVim, run the following command in normal mode (press Esc to make sure you're in normal mode):

:term

This will open a terminal window in the current buffer.

2. Switching Between Modes in Terminal

When you're in the terminal, you’ll automatically be in Terminal Mode, which means the keybindings work as they would in a normal terminal shell.

• Normal Mode: To switch back to normal NeoVim mode from the terminal, press Ctrl + \, followed by Ctrl + n.

3. Running Commands in the Terminal

Once inside the terminal, you can run commands just as you would in your regular terminal:

• Type any shell command (like ls, git, npm start, etc.).
• Use Ctrl + d to exit the terminal session.

4. Navigating Between Terminal and Other Windows

You can split the NeoVim window and have the terminal in one section, while editing files in another. This helps to work with code and the terminal simultaneously.

• Split the terminal vertically:

  :vsplit | term

• Split the terminal horizontally:

  :split | term

5. Navigating Between Windows

After splitting windows or using a terminal buffer alongside other files, you can navigate between the windows (buffers) with:

• Ctrl + w w: Switch between windows.
• Ctrl + w + h/j/k/l: Move between windows in specific directions (h for left, l for right, j for down, k for up).

6. Close the Terminal

To close a terminal, you can do the following:

• If you’re inside the terminal, exit the shell (e.g., type exit and hit Enter).
• You can also close it from normal mode by closing the window:

  :q

7. Useful Keybindings for Terminal Mode

To make it easier to switch between terminal and normal mode, you can set up custom keybindings in your init.lua or init.vim configuration file:

-- Keybinding to quickly switch between terminal and normal mode
vim.api.nvim_set_keymap('t', '<Esc>', [[<C-\><C-n>]], { noremap = true, silent = true })

-- To quickly close a terminal from normal mode
vim.api.nvim_set_keymap('t', '<leader>q', [[<C-\><C-n>:q<CR>]], { noremap = true, silent = true })

This will let you press Esc to exit Terminal mode and return to Normal mode.

Example Workflow: Running a Program and Editing Files

1. Open a terminal in NeoVim:

   :vsplit | term

2. Run your program inside the terminal (e.g., npm start for a Node.js app).

3. Use Ctrl + w + w to switch between your code and the terminal.

4. Make edits in your code files in the other window, save the file with :w, and use the terminal to see the output or rerun the program.

Summary of Useful Commands

Action	Command
Open a terminal	:term
Switch from terminal to normal mode	Ctrl + \ followed by Ctrl + n
Split window and open terminal	:split | term (horizontal)
Split window and open terminal	:vsplit | term (vertical)
Close terminal window	:q or exit
Switch between terminal and other windows	Ctrl + w w

This will allow you to fully utilize the terminal inside NeoVim, keeping your workflow efficient without leaving the editor.

Yes, there is a way to reverse the split behavior in NeoVim so that the terminal opens below instead of on top when you use :split.

---

By default, :split opens a new window above the current one. To reverse this behavior and make the new split open below the current window, you can use the :belowright command.

Reverse Split Command

To open the terminal below the current window, use:

:belowright split | term

Explanation:

• belowright: Forces the new split to open below the current window.
• split: Opens a new split window.
• | term: Executes the terminal command after the split.

You can also set this behavior for future splits using a keybinding if you prefer to always open the terminal below:

Keybinding for Terminal Below

You can add this keybinding to your init.lua or init.vim:

vim.api.nvim_set_keymap('n', '<leader>t', ':belowright split | term<CR>', { noremap = true, silent = true })

Now, whenever you press <leader>t, it will open the terminal in a split below your current window.

---

In NeoVim (and Vim), the <leader> key is a configurable key that acts as a prefix for custom keybindings. It's used to define shortcuts for commands you frequently use, allowing you to personalize your workflow. The default value of <leader> is typically the backslash (\), but many users prefer to set it to a different key like the spacebar for easier access.

Setting the <leader> Key

You can set the <leader> key to something more convenient (like the spacebar) by adding this to your init.lua or init.vim configuration file:

vim.g.mapleader = " "

Now, whenever you see <leader>, it will refer to the spacebar.

Example of <leader>t

In the example I provided earlier, this line:

vim.api.nvim_set_keymap('n', '<leader>t', ':belowright split | term<CR>', { noremap = true, silent = true })

means that pressing the spacebar (<leader>) followed by t will run the command :belowright split | term, which opens a terminal in a horizontal split below the current window.

• t:
  • <leader> refers to the spacebar (if you configured it that way).
  • t is the key pressed after <leader>, which runs the command.

Customizing Keybindings with <leader>

You can use <leader> to create custom keybindings for many actions. For example:

• Saving the file:

  vim.api.nvim_set_keymap('n', '<leader>w', ':w<CR>', { noremap = true, silent = true })

  Pressing spacebar + w will save the file.

• Quitting NeoVim:

  vim.api.nvim_set_keymap('n', '<leader>q', ':q<CR>', { noremap = true, silent = true })

  Pressing spacebar + q will quit NeoVim.

Summary

• <leader> is a key that acts as a prefix for custom keybindings.
• You can set it to any key (commonly spacebar) for easier access.
• Using <leader> in keybindings helps streamline your workflow by allowing you to define fast shortcuts for frequently used commands.

---

How to Enter Terminal Mode Automatically

When you open a terminal with :split | term, you are in Normal Mode, which is why the terminal isn't responsive right away. To enter Terminal Mode automatically after opening a terminal, you can adjust your command to:

:split | term | startinsert

This will do the following:

• :split: Opens a new horizontal split.
• :term: Opens the terminal in that split.
• :startinsert: Switches you to Insert Mode, which is how you interact with the terminal.

Keybinding to Open Terminal in Split and Enter Insert Mode

You can add a keybinding to make this process even smoother. Add this to your init.lua or init.vim:

vim.api.nvim_set_keymap('n', '<leader>t', ':belowright split | term | startinsert<CR>', { noremap = true, silent = true })

Now, whenever you press <leader>t, it will open a terminal in a horizontal split below the current window and automatically switch to Terminal Mode, allowing you to start typing commands right away.

Explanation of What Happened

When you manually typed clea, you were actually still in Normal Mode, where NeoVim interprets key presses as commands. The terminal wasn’t activated until you switched to Insert Mode (or pressed i), which is what the terminal needs to interact with your shell. By using startinsert, you ensure that NeoVim switches to Terminal Mode (or Insert Mode) automatically.

Summary

• Use :split | term | startinsert to open a terminal and automatically switch to insert mode.
• You can also map this to a convenient keybinding like <leader>t to make the process faster.

---

:belowright split | exe 'term' | startinsert

This way, the term command is executed as part of an Ex command, and then startinsert is applied to enter Insert Mode.

Keybinding Update

If you’re using a keybinding, you can update it as follows:

The issue you're encountering occurs because the `|` (pipe) character in NeoVim is interpreted as chaining multiple Ex commands (NeoVim/Vim commands). However, you can't directly use `|` between certain commands in NeoVim like `term` and `startinsert`.

To fix this, you can use the `:exe` command to execute a sequence of commands more reliably. Here’s how you can modify the command:

```bash
:belowright split | exe 'term' | startinsert

This way, the term command is executed as part of an Ex command, and then startinsert is applied to enter Insert Mode.

Keybinding Update

If you’re using a keybinding, you can update it as follows:

vim.api.nvim_set_keymap('n', '<leader>t', ':belowright split | exe "term" | startinsert<CR>', { noremap = true, silent = true })

Why This Works

• :belowright split: Opens a split below the current window.
• :exe 'term': Executes the term command in a way that works with chaining.
• startinsert: Switches to Insert Mode, enabling interaction with the terminal.

Now you should be able to open a terminal in a split and have it activate correctly without errors.

Let me know if this solves the issue!```

Why This Works

• :belowright split: Opens a split below the current window.
• :exe 'term': Executes the term command in a way that works with chaining.
• startinsert: Switches to Insert Mode, enabling interaction with the terminal.

Now you should be able to open a terminal in a split and have it activate correctly without errors.