From 7811dbdb020dbaab66b4d0bac1136b33b004b450 Mon Sep 17 00:00:00 2001 From: "Hunter T." Date: Sun, 24 Nov 2024 20:27:42 -0800 Subject: [PATCH 1/5] Update vscode settings --- .vscode/settings.json | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.vscode/settings.json b/.vscode/settings.json index 507676d..93fbf4c 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,9 +1,14 @@ { "cSpell.words": [ "DCONF", + "LSCOLORS", "mktemp", "Neovim", "nvim", + "pacman", + "Powerlevel", + "Repology", + "TPPM", "vimscript" ] } From 6e2b4365fc4b5aa532d7aca9051ac278025a6f4d Mon Sep 17 00:00:00 2001 From: "Hunter T." Date: Sun, 24 Nov 2024 20:28:06 -0800 Subject: [PATCH 2/5] Remove csv file no longer used --- includes/csv/neovim-plugin-info.csv | 9 --------- 1 file changed, 9 deletions(-) delete mode 100644 includes/csv/neovim-plugin-info.csv diff --git a/includes/csv/neovim-plugin-info.csv b/includes/csv/neovim-plugin-info.csv deleted file mode 100644 index 30f2334..0000000 --- a/includes/csv/neovim-plugin-info.csv +++ /dev/null @@ -1,9 +0,0 @@ -Plugins,Description -[HiPhish/rainbow-delimiters.nvim](https://github.com/HiPhish/rainbow-delimiters.nvim),Rainbow delimiters for Neovim with Tree-sitter. -[vim-airline/vim-airline](https://github.com/vim-airline/vim-airline),Lean & mean status/tabline for vim that's light as air. -[vim-airline/vim-airline-themes](https://github.com/vim-airline/vim-airline-themes),A collection of themes for vim-airline. -[morhetz/gruvbox](https://github.com/morhetz/gruvbox),Retro groove color scheme for Vim. -[dense-analysis/ale](https://github.com/dense-analysis/ale),"Check syntax in Vim asynchronously and fix files, with Language Server Protocol (LSP) support." -[ntpeters/vim-better-whitespace](https://github.com/ntpeters/vim-better-whitespace),Better whitespace highlighting for Vim. -[nvim-treesitter/nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter),Nvim Treesitter configurations and abstraction layer. -[mechatroner/rainbow_csv](https://github.com/mechatroner/rainbow_csv),Highlight columns in CSV and TSV files and run queries in SQL-like language. From 88dc7dc7f6224ac78a887ddc4b48a47b63fc9bd8 Mon Sep 17 00:00:00 2001 From: "Hunter T." Date: Sun, 24 Nov 2024 20:28:19 -0800 Subject: [PATCH 3/5] Update site name --- mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index 4c41fbb..9d0c740 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: Customized Unix Terminal +site_name: Custom Unix Terminal site_url: https://cut.hthompson.dev site_author: Hunter T. # TODO: Add a site description. From 1b10e4cd50c35dad72a78779af242c1be010fafd Mon Sep 17 00:00:00 2001 From: "Hunter T." Date: Sun, 24 Nov 2024 22:31:05 -0800 Subject: [PATCH 4/5] Update CHANGELOG.md --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 14dc04f..02f8a08 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,8 @@ As a note, if the changelog only says "removed(program)", assume it's been remov - Reworked the Gnome Terminal Profile, so it no longer overwrite existing profiles. - Added a workflow that can do the same thing as `update_submodule.bash`, but automatically via dependabot. - Update the wording and information in main document. +- Add more context to a few sections... +- Added a new section regarding syntax highlighting for `neovim`. ## 2024.4.25 From dfca3ebd4cd558284a56d6db3f31aaea0bb2d2f5 Mon Sep 17 00:00:00 2001 From: "Hunter T." Date: Sun, 24 Nov 2024 22:34:07 -0800 Subject: [PATCH 5/5] Major improvements to the wording and information of this document... The last three sections still require some updating --- docs/index.md | 139 +++++++++++++++++++++++++++++--------------------- 1 file changed, 81 insertions(+), 58 deletions(-) diff --git a/docs/index.md b/docs/index.md index 41cc1c0..67a1569 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,22 +1,24 @@ - - # Custom Unix Terminal -This document serves as a guide for how I customize my terminal in macOS and Linux. It includes a variety of configurations, settings, and programs that I find helpful for my daily workflow. The document is divided into several sections, each focusing on a different aspect of terminal customization. +This document serves as an informational guide on how I've customized my terminal in macOS and Linux. It includes a variety of configurations, settings, and programs that enhance my productivity and improve my overall experience within the terminal environment. The document is divided into several sections, each focusing on a different aspect of terminal customization, such as shell frameworks, themes, resource files, plugins, and more. + +/// admonition | Disclaimer + type: warning + +This guide assumes you have a basic understanding of the Unix terminal and are comfortable working with configuration files. If you're new to the terminal or need clarification on any of the instructions provided, I recommend proceeding with caution and seeking additional resources or assistance. + +/// ## Useful Programs -The following table contains a list of terminal programs that I find particularly useful. These programs are separated into two categories: Third Party Package Managers (TPPM) and Native Package Managers (NPM). +The following table consists of CLI programs that have been useful to me in my day-to-day work. These programs are divided into two categories: Third Party Package Managers (TPPM) and Native Package Managers (NPM). -The **TPPM** section features programs that can be installed using package managers like Homebrew, Pip, Cargo, Npm, Gem, or Git(1). For each program, I've included a brief description, the operating systems it supports, and the package managers available for installation. +The **TPPM** section features programs that can be installed via package managers like Homebrew, Pip, Cargo, Npm, Gem, or Git(1). For each program, I've included a brief description, the operating systems it supports, and the package managers available for installation. { .annotate } -1. While most of these programs can be installed via `git`, they will only be marked as such if recommended by the program's documentation or myself, or if it's the only available installation method. +1. While all of these programs can be installed manually with `git`, they will only be marked as such if it is recommended by the program's documentation, myself, or if it's the only available method. -The **NPM** section lists programs that can be installed using the system's default package manager. Since the Linux distributions that I primarily use are Debian- and Arch-based, all the programs in this section are confirmed to be installable via `apt` or `pacman`. For other Linux distributions, you can check [Repology](https://repology.org/) to see if the program is available in your distribution's package manager. Similar to the **TPPM** section, I've included additional information such as a brief description for each program and a link to its Repology page. +The **NPM** section lists programs that can be installed using the system's default package manager. Since I primarily use Debian and Arch-based Linux distributions, all the programs in this section are confirmed to be installable via `apt` or `pacman`. For other Linux distributions, refer to [Repology](https://repology.org/) to see if the program is available via your distribution's package manager. Like the **TPPM** section, I've included additional information such as a brief description of each program and a link to its Repology page. /// tab | Third Party Package Manager @@ -32,27 +34,33 @@ Applicable Operating Systems: Linux /// -## Customizing ZSH +## Z Shell (Zsh) -### Framework +The Z shell, or `zsh`, is a powerful and feature-rich shell that offers many improvements over the default shells provided by most Unix-based operating systems. It includes advanced features such as improved tab completion, spelling correction, and shared command history, making it a popular choice among developers and power users. This section covers the shell framework, theme, resource file, plugins, and aliases that I use to customize my `zsh` environment. -[Oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh) is my preferred framework due to its popularity, reliability, and consistent updates. As one of the leading zsh frameworks, it made its initial commit on August 23, 2009, allowing it enough time to develop and refine its features. +### Shell Framework -[Below](#oh-my-zsh-plugins) is a list of oh-my-zsh plugins that I use and find to provide useful functionality. +A framework makes customizing the shell much more manageable, whether it be through plugins or themes. I often prefer complete control over my configurations, but the convenience provided by a framework has dramatically improved my workflow and ease of management. + +Due to its popularity, reliability, and consistent updates, my framework of choice has become [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh). As one of the leading `zsh` frameworks, it made its initial commit on August 23, 2009, allowing it enough time to improve and refine its features. + + ### Shell Theme -In combination with oh-my-zsh, I use [Starship](https://github.com/starship/starship) as my shell theme. Starship is a fast, minimal, and highly customizable shell prompt that displays information about the current directory, git branch, and other relevant details. It is written in Rust, making it very fast and lightweight. +Similar to how a shell framework enhances the shell's functionality, a shell theme improves its appearance and the user experience. A well-designed theme can provide valuable information at a glance, such as the current directory, git branch, and other relevant details. -As a note, I previously used [Powerlevel10k](https://github.com/romkatv/powerlevel10k), which is another **excellent** shell theme. However, as of May 21, 2024, Powerlevel10k has entered a ["life support" mode](https://github.com/romkatv/powerlevel10k/commit/bde5ca4c2aa6e0c52dd7f15cf216dffdb1ec788c). In the maintainer's words, "The project has very limited support", with "no new features are in the works", "most bugs will go unfixed", and "help requests will be ignored". As such, I decided to switch to an actively maintained project and mature alternative, Starship. +My preferred shell theme is [Starship](https://github.com/starship/starship), which draws inspiration from several well-known and popular [shell themes](https://github.com/starship/starship#-inspired-by). It is written in Rust, making it fast, lightweight, and highly customizable. Starship is designed to support a wide range of shells and external tools, making it a versatile choice for users across different platforms. -### ZSH Resource File +Before Starship, I used [Powerlevel10k](https://github.com/romkatv/powerlevel10k), which is another **excellent** shell theme. However, as of May 21, 2024, Powerlevel10k has entered a ["life support" mode](https://github.com/romkatv/powerlevel10k/issues/2690). In the [maintainer's words](https://github.com/romkatv/powerlevel10k#powerlevel10k), "The project has very limited support", with "no new features are in the works", "most bugs will go unfixed", and "help requests will be ignored". As a result, I searched for an alternative and found Starship to be a suitable replacement. -Below are the configurations for my `.zshrc` file, divided into two sections: one for macOS and one for Linux. Each section is tailored to its respective operating system. +### Zsh Resource File -You're welcome to use this resource however you like. My intention is to offer it as a guide for structuring your own `.zshrc` file and to present additional configurations not detailed elsewhere in this document. +The `.zshrc` file is where all the configurations for `zsh` are stored. It's the primary resource file for customizing the shell, containing settings, aliases, and other configurations that define its behavior and appearance. -/// details | My ZSH Resource File +Below is the content of my `.zshrc` file, divided into two sections: one for macOS and one for Linux. Each section is tailored to its respective operating system. You're welcome to use this resource however you like. I offer it as a guide for structuring your own `.zshrc` file and to present additional configurations not detailed elsewhere in this document. + +/// details | My Zsh Resource File //// tab | macOS ```bash title=".zshrc" @@ -72,13 +80,17 @@ You're welcome to use this resource however you like. My intention is to offer i #### Oh-my-zsh Plugins -Below is a list of all the oh-my-zsh plugins that I use and find particularly useful. +`oh-my-zsh` provides more than 325 [built-in plugins](https://github.com/ohmyzsh/ohmyzsh#plugins) that are regularly updated and maintained by the community. These plugins offer a wide range of features, from syntax highlighting and auto-completion to git integration and directory navigation. + +Below are all the plugins that I use, along with a brief description of their functionality: {{ read_csv("includes/csv/oh-my-zsh-plugins.csv") }} -#### Custom Aliases +#### Aliases -Below is a list of aliases from my `.zshrc` files, organized into two groups: Group 1 and Group 2. Group 1 contains general aliases, while Group 2 includes aliases for categorized commands. Many of these commands are programs mentioned in the [Useful Programs](#useful-programs) section that I don't use frequently but still want quick access to. +Many frameworks, such as `oh-my-zsh`, provide their own set of aliases to simplify and improve common commands. Any CLI user will tell you that aliases are a powerful tool for increasing productivity and efficiency. They allow you to create shortcuts for frequently used commands, reducing the time and effort required to type them out. + +Below are aliases I've create, organized into two groups: Group 1 and Group 2. Group 1 contains general aliases, while Group 2 includes aliases for displaying useful programs I don't frequently use and often forget about. /// tab | macOS @@ -98,23 +110,28 @@ Below is a list of aliases from my `.zshrc` files, organized into two groups: Gr ### Modifying CLI Colors -You can customize the terminal colors for folders, files, and other items in the terminal by setting the `LS_COLORS` (Linux & macOS) or `LSCOLORS` (macOS) environment variables. To modify these colors, add the appropriate `LS_COLORS` or `LSCOLORS` variable to your `.zshrc` file. + + +You can customize the colors of folders, files, and other items in the terminal by setting the `LS_COLORS` or `LSCOLORS` environment variables.(1) Each variable uses a unique format to specify the colors and styles of different file types and directories. For more information regarding these variables, refer to the "CLI Colors Explained" drop-down. +{ .annotate } -/// details | LS_COLORS & LSCOLORS Explained +1. Linux only requires `LS_COLORS`, while macOS needs both `LS_COLORS` and `LSCOLORS` to be set. -On macOS, both `LSCOLORS` and `LS_COLORS` are necessary for specifying terminal colors. The `LSCOLORS` environment variable is used by commands like `ls` to determine the colors displayed in the terminal, while `LS_COLORS` is used by zsh for similar purposes. In contrast, Linux only requires `LS_COLORS`, which is utilized by both commands like `ls` and zsh. +/// details | CLI Colors Explained -This difference arises from the distinct versions of the `ls` command on macOS and Linux. macOS employs the FreeBSD version of `ls`, which relies on `LSCOLORS` for color settings, whereas Linux uses the GNU version, which depends on `LS_COLORS`. Each variable has its own unique formatting. Additionally, since zsh recognizes only the `LS_COLORS` format, it's important to set this variable on macOS to ensure proper display and functionality of CLI colors. +Between macOS and Linux, there is a slight difference in how CLI colors are configured. macOS requires both `LSCOLORS` and `LS_COLORS` to fully enable and set CLI colors within the terminal. Conversely, Linux only needs `LS_COLORS` to achieve the same. -Included below is a key that explains the values of `LSCOLORS` and `LS_COLORS` in my configurations: +This difference arises from the distinct version of the `ls` command on macOS and Linux. macOS employs the FreeBSD version of `ls`, which relies on `LSCOLORS` to define the color scheme for file and directory listings. In contrast, Linux uses the GNU version, which depends on `LS_COLORS` for the same purpose. On both systems, `LS_COLORS` is also used by shells like `zsh` to colorize other tools and utilities. + +Included below is a key that explains the values of `LSCOLORS` and `LS_COLORS` in my configurations: {{ read_csv("includes/csv/cli-colors-explained.csv") }} -For an in-depth understanding of `LS_COLORS` and `LSCOLORS`, I recommend visiting this [gist](https://gist.github.com/thomd/7667642). +I recommend visiting this [gist](https://gist.github.com/thomd/7667642) for an in-depth understanding of the `LS_COLORS` and `LSCOLORS` values. /// -Below are my configurations for both macOS and Linux systems. To apply these settings, simply add the following code to your `~/.zshrc` file: +The below configurations are my `LS_COLORS` and `LSCOLORS` settings for macOS and Linux. To use them, add the code to your `.zshrc` file: /// tab | macOS @@ -132,70 +149,76 @@ Below are my configurations for both macOS and Linux systems. To apply these set /// -You can further modify the shading and appearance of CLI colors by adjusting the ANSI color scheme in your terminal profile. This can be done manually, with guides available for both [macOS](https://support.apple.com/guide/terminal/change-profiles-text-preferences-trmltxt/mac) and [Linux](https://help.gnome.org/users/gnome-terminal/stable/app-colors.html.en) (specific to GNOME). Alternatively, you can use my custom profile schemes, which are detailed in the [Terminal Profile](#terminal-profile) section. +You can further modify the shading and appearance of CLI colors by adjusting the ANSI color scheme in your terminal profile. This can be done manually, with guides available for [macOS](https://support.apple.com/guide/terminal/change-profiles-text-preferences-trmltxt/mac) and [Linux](https://help.gnome.org/users/gnome-terminal/stable/app-colors.html.en) (specific to GNOME). Alternatively, you can use my custom profile schemes, with instructions detailed in the [Terminal Profile](#terminal-profile) section. -## Neovim Resource File +## Text Editor -Due to Neovim's extensibility and active community, I have chosen it as my primary text editor, preferring it over the traditional Vi or Vim. Below are the configurations for my `init.vim` file. The configurations are organized into two sections: one with plugins and one without. + -### With Plugins +There are many terminal-based text editors to choose from, each with unique features and capabilities. I've found that [Neovim](https://github.com/neovim/neovim) is the most powerful and versatile option for my needs. -The following configurations modify the behavior and appearance of Neovim. To use these settings, you'll first need to install [vim-plug](https://github.com/junegunn/vim-plug#installation), a plugin manager for Vim. While other Vim package managers are available, these configurations are specifically tailored for vim-plug. +Neovim a fork of [Vim](https://github.com/vim/vim) that aims to improve upon Vim's features and performance, with a focus on extensibility and usability. It is designed to be more user-friendly and accessible to new users while still providing the power and flexibility that experienced users expect. -After installing vim-plug, copy the code below into your `~/.config/nvim/init.vim` file. With init.vim open in Neovim, initiate the plugin installation by entering `:source %` followed by `:PlugInstall`. +### Neovim Resource File -/// admonition | Note +Like the `.zshrc` file for `zsh`, Neovim has its own resource file, located at `~/.config/nvim/init.vim`, where all the configurations for the editor are stored. This file contains settings, key mappings, and other configurations that define Neovim's behavior and appearance. -When using `:source %`, you can safely ignore any errors that may appear, as they are most likely caused by Neovim searching for plugins that have not yet been installed. +Below is the content of my `init.vim` file, divided into two sections: with plugins and without plugins. The former includes configurations for various plugins I use, while the latter is a more streamlined setup without any plugins. You can choose the configuration that best suits your needs and add it to your `~/.config/nvim/init.vim` file. -/// +/// tab | With Plugins -/// details | Vim Plugin Information - type: info +I manage all of my Neovim plugins using [vim-plug](https://github.com/junegunn/vim-plug#installation), a self-described minimalist Vim plugin manager. It simplifies the process of installing, updating, and removing plugins, making it easier to manage and maintain a large number of plugins. While other Vim package managers are available, my configurations are specifically tailored to `vim-plug`. -Below is a list of all the plugins included in my `init.vim`, each accompanied by a description of its functionality. - -{{ read_csv("includes/csv/neovim-plugin-info.csv") }} +To use these configurations, you'll need to first [install vim-plug](https://github.com/junegunn/vim-plug?tab=readme-ov-file#installation). Once installed, you can add the below code to your `init.vim` file. With `init.vim` open in Neovim, initiate the plugin installation by entering `:source %` (1) followed by `:PlugInstall`. +{ .annotate } -/// +1. When using `:source %`, you can safely ignore any errors that may appear, as they are most likely caused by Neovim searching for plugins that have not yet been installed. ```vim title="init.vim" --8<-- "includes/neovim-init-files/neovim-init-vim-plug.vim" ``` -### Without Vim-Plug Plugins +#### Syntax Highlighting -If you prefer a simpler setup without all the features provided by plugins, you can add the configurations below to your `init.vim` file. These adjustments tweak Vim's default settings without changing its core functionality, offering a more streamlined experience while preserving Vim's essential behavior. - -```vim title="init.vim" ---8<-- "includes/neovim-init-files/neovim-init-non-vim-plug.vim" -``` - -### Syntax Highlighting - -Neovim leverages [TreeSitter](https://github.com/tree-sitter/tree-sitter) to provide features such as advanced syntax highlighting, offering more precision and speed compared to traditional regex-based methods. However, its default installation includes only a limited set of parsers for programming languages. This is where the [nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter) plugin shines. Acting as an enhanced interface for TreeSitter, `nvim-treesitter` provides: +Neovim leverages [TreeSitter](https://github.com/tree-sitter/tree-sitter) to provide features such as advanced syntax highlighting, offering more precision and speed than traditional regex-based methods. However, its default installation includes only a limited set of parsers for programming languages. This is where the [nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter) plugin shines. Acting as an enhanced interface for TreeSitter, `nvim-treesitter` provides: - **Parser Management**: It automatically handles downloading, installing, and updating TreeSitter parsers for a wide range of languages. - **Enhanced Syntax Highlighting**: With custom configurations, it delivers consistent and accurate syntax highlighting tailored to each language. -- **Advanced Code Features**: In addition to highlighting, it enables and enhances features like structural code navigation, incremental selection, code folding, and extensions like rainbow parentheses. +- **Advanced Code Features**: Besides highlighting, it enables and enhances features like structural code navigation, incremental selection, code folding, and extensions like rainbow parentheses. Below are my configurations for `nvim-treesitter` in Neovim. Currently, they ensure that the specified parsers are automatically installed and loaded. To use these settings, add the following code to `~/.config/nvim/second_init.lua` (1): { .annotate } -1. `nvim-treesitter` requires Lua to function. As a result, the configurations are written in Lua and stored in a separate file, `second_init.lua`. My `init.vim` file, as displayed [above](#with-plugins), sources this Lua file to enable the necessary settings. +1. `nvim-treesitter` requires Lua to function. As a result, the configurations are written in Lua and stored in a separate file, `second_init.lua`. My `init.vim` file, as displayed [above](#__tabbed_5_1), sources this Lua file to enable the necessary settings. ```lua title="second_init.lua" --8<-- "includes/neovim-init-files/neovim-init-lua.lua" ``` -If you're **NOT** using the `init.vim` file that I provided [above](#with-plugins), and your `init` file is written in vimscript, you'll want to add the following code to your `init.vim` file: +If you're **NOT** using the `init.vim` file that I provided [above](#__tabbed_5_1), and your `init` file is written in vimscript, you'll want to add the following code to your `init.vim` file: ```vim title="init.vim" lua dofile(vim.fn.stdpath('config') .. '/second_init.lua') ``` +/// + +/// tab | Without Plugins + +These configurations are designed for users who prefer a more straightforward setup without the features provided by plugins. They tweak Vim's default settings without changing its core functionality, offering a more streamlined experience while preserving Vim's essential behavior. + +```vim title="init.vim" +--8<-- "includes/neovim-init-files/neovim-init-non-vim-plug.vim" +``` + +/// + ## Terminal Profile + + +A terminal profile is the collective configurations that result in the visual appearance of the terminal window, including the color scheme, font style, and other visual elements. Customizing the terminal profile can enhance the overall user experience and make working in the terminal more enjoyable. + /// tab | macOS My custom terminal profile is a modified version of the Basic profile that comes pre-installed on macOS. To add it to your list of profiles, follow these steps: