How does NvChad work?

Understanding the basics

Before getting into the topic, first you should understand the vim.tbl_deep_extend function which is used for merging tables and their values recursively.

• The function vim.tbl_deep_extend is normally used to merge 2 tables, and its syntax looks like this:

-- table 1
local person = {
    name = "joe",
    age = 19,
}

-- table 2
local someone = {
    name = "siduck",
}

-- "force" will overwrite equal values from the someone table over the person table
local result = vim.tbl_deep_extend("force", person, someone)

-- result : 
{
    name = "siduck", -- as you can see, name has been overwritten
    age = 19,
}

Its usage can be used in even more complex tables. As was mentioned before, it works recursively, which means that it will apply the same behavior for nested table values:

local person = {
    name = "joe",
    age = 19,
    skills = {"python", "java", "c++"}

    distros_used = {
        ubuntu = "5 years",
        arch = "10 minutes",
        manjaro = "10 years",
    }
}

local someone = {
    name = "siduck",
    skills = {"js", "lua"},

    distros_used = {
       ubuntu = "1 month",
       artix = "2 years"
    }
}

local result = vim.tbl_deep_extend("force", person, someone)

The resulting table will have merged each property from the tables, and the same for the skills and distros_used values:

{
   name = "siduck",
   age = 19

   skills = {"js", "lua"},

   distros_used = {
       ubuntu = "1 month",
       arch = "10 minutes",
       manjaro = "10 years",
       artix = "2 years"
   }
}

-- tbl_deep_extend function merges values recursively, but if there's an array (list), it won't merge the list tables. 

-- Example: the first table has {"python", "java", "c++"} and the second table has {"js","lua"}. 

-- Now you might be wondering that it should merge it like this: { "python", "java", "c++", "lua"}

-- But no! thats wrong, the result will be only {"js","lua"}

To sum up, tbl_deep_extend merges dictonary tables recursively (i.e tables which have key/value pair but not lists).

Config Structure

├── init.lua ( main init.lua )
│
├── lua
│   │
│   ├── core
│   │   ├── default_config.lua
│   │   ├── mappings.lua
│   │   ├── utils.lua 
│   │   └── init.lua  
│   │
│   ├── plugins
│   │    ├── init.lua 
│   │    └── configs
│   │        ├── cmp.lua
│   │        └── other configs
│   │  
│   │   USER CONFIG  
│   │  
│   ├── custom *
│   │   ├── chadrc.lua
│   │   ├── init.lua
│   │   ├── more files, dirs

• init.lua - runs whole config
• core/default_config - returns a table of default options in NvChad.
• core/mappings - default mappings
• core/init - default globals, nvim options, commands, autocmds
• core/utils - helpful functions

Custom config

There are 2 important files in custom dir which extend NvChad:

• custom/chadrc.lua meant to override that table in default_config.lua file
• custom/init.lua runs in the main init.lua, its meant to have vim options, globals, autocmds, commands etc.

From now on, whenever we talk about paths, keep in mind that they're relative to the lua folder in your nvim config (by default it should be ~/.config/nvim/).

• It is not recommended to make changes outside the custom dir, because NvChad config is a repo and it gitignores only the custom dir, it uses git pull to update the config.

• Any other file outside the custom dir will be treated as a change by git, meaning that NvChad will not be able to fast-forward the pull.

• Check example_config for reference.

Themes

You can see all the themes with the following keymap: <leader> + th.

The leader key is the space in NvChad.

Mappings

If you want to know all the keymaps, you can run the following comands:

• NvCheatsheet
• Telescope keymaps