From ef5a97eb61cf38426390789eb550a0854f04f438 Mon Sep 17 00:00:00 2001
From: ignuki <inakidomoc@gmail.com>
Date: Tue, 1 Apr 2025 20:21:25 +0200
Subject: [PATCH] Improve README

---
 README.md                    | 196 ++++++++++++++++++++++++++---------
 git/.gitconfig.local.example |   5 +
 zsh/.zshrc                   |   6 +-
 3 files changed, 156 insertions(+), 51 deletions(-)
 create mode 100644 git/.gitconfig.local.example

diff --git a/README.md b/README.md
index 1a4f1be..fd0116d 100644
--- a/README.md
+++ b/README.md
@@ -1,66 +1,162 @@
-# DOTFILES
+# Dotfiles
+
+A cross-platform dotfiles repository managed with GNU Stow, compatible with both
+Debian Trixie and macOS. This repository contains configuration files for
+various development tools and applications to create a consistent environment
+across different systems.
+
+## Overview
+
+This dotfiles repository uses [GNU Stow](https://www.gnu.org/software/stow/) to
+manage symlinks.
+
+## Directory Structure
+
+```
+dotfiles/
+├── alacritty/     # Alacritty terminal emulator config
+├── curl/          # curl configuration
+├── git/           # Git configuration
+├── nvim/          # Neovim configuration
+├── scripts/       # Utility scripts
+├── tmux/          # tmux configuration
+└── zsh/           # ZSH shell configuration
+```
 
 ## Dependencies
 
-- alacritty
-- zsh
-- zsh-autosuggestions
-- zsh-completions
-- homebrew/linuxbrew
-- stow
-- rust toolchain
-- starship
-- tmux
-- tmux-plugin-manager
-- reattach-to-user-namespace (MacOS)
+### Core Tools
+
+- **Terminal**: [Alacritty](https://github.com/alacritty/alacritty)
+- **Shell**: [ZSH](https://www.zsh.org/)
+    - [zsh-syntax-highlighting](https://github.com/zsh-users/zsh-syntax-highlighting)
+    - [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions)
+      (submodule)
+    - [zsh-completions](https://github.com/zsh-users/zsh-completions)
+      (submodule)
+- **Package Manager**: [Homebrew/Linuxbrew](https://brew.sh/)
+- **Dotfile Management**: [GNU Stow](https://www.gnu.org/software/stow/)
+
+### Development Tools
+
+- [Rust](https://www.rust-lang.org/) toolchain (including rust-analyzer)
+- [Neovim](https://neovim.io/)
+- [tmux](https://github.com/tmux/tmux) +
+  [tmux-plugin-manager](https://github.com/tmux-plugins/tpm)
+- [Terraform](https://www.terraform.io/)
 - python3-libtmux
-- neovim
-- lua-language-server
-- stylua
-- luacheck
-- prettier
-- prettier-plugin-go-template
-- rust-analyzer
-- shfmt
-- shellcheck
-- bash-language-server
-- terraform
-- terraform-ls
-- tflint
-- ruff
+    - Installed via `apt` in Debian. Remember to run `brew unlink python3` to
+      prevent conflicting Python environments.
+- reattach-to-user-namespace (macOS only)
+
+### Language Servers & Linters
+
+- Lua: lua-language-server, stylua, luacheck
+- JavaScript/TypeScript: prettier, prettier-plugin-go-template
+- Shell: shfmt, shellcheck, bash-language-server
+- Terraform: terraform-ls, tflint
+- Python: ruff
+
+### Extras
+
+- lesspipe
 - cbonsai
 
-# Git Configuration
+## Installation
 
-This directory contains Git configuration files that can be safely shared in a
-public repository.
+### Prerequisites
 
-## Setup Instructions
+1. **Install Rust**
 
-1. Create a symbolic link for the main Git config:
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+rustup component add rust-analyzer
+```
 
-    ```
-    ln -sf ~/dotfiles/git/.gitconfig ~/.gitconfig
-    ```
+2. **Install Homebrew**
 
-2. Create your personal Git configuration:
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
 
-    ```
-    cp ~/dotfiles/git/.gitconfig.local.example ~/.gitconfig.local
-    ```
+3. **Install tmux-plugin-manager**
 
-3. Edit `~/.gitconfig.local` with your personal information:
-    ```
-    [user]
-        name = Your Name
-        email = your.email@example.com
-    ```
+```bash
+mkdir -p ~/.tmux/plugins
+git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
+```
 
-## Structure
+### Platform-Specific Setup
 
-- `.gitconfig`: Main configuration file with shareable settings
-- `.gitconfig.local.example`: Template for personal/private Git settings
-- `~/.gitconfig.local`: (Not tracked) Your personal Git configuration
+#### Debian Trixie
 
-This approach keeps your personal information out of the public repository while
-still allowing you to manage and version your Git configuration.
+1. **Install Terraform**
+
+```bash
+wget -O - https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com bookworm main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
+sudo apt update && sudo apt install terraform
+```
+
+2. **Install Dependencies**
+
+```bash
+# System packages
+sudo apt install alacritty zsh tmux stow zsh-syntax-highlighting less python3-libtmux cbonsai shfmt shellcheck lua-check
+
+# Homebrew packages
+brew install neovim stylua lua-language-server bash-language-server prettier terraform-ls tflint ruff
+
+# Node packages
+npm install --save-dev prettier prettier-plugin-go-template
+
+# Prevent Python conflicts
+brew unlink python3
+```
+
+#### macOS
+
+```bash
+# Core tools
+brew install curl git alacritty zsh tmux stow zsh-syntax-highlighting lesspipe cbonsai reattach-to-user-namespace
+
+# Development tools
+brew install neovim stylua lua-language-server bash-language-server prettier terraform-ls tflint ruff
+
+# Node packages
+npm install --save-dev prettier prettier-plugin-go-template
+```
+
+### Setup
+
+1. **Clone this repository**:
+
+```bash
+git clone --recurse-submodules https://github.com/yourusername/dotfiles.git ~/dotfiles
+cd ~/dotfiles
+```
+
+2. **Deploy configurations using Stow**:
+
+```bash
+stow zsh tmux git nvim curl alacritty
+```
+
+3. **Set up tmux plugins**:
+
+    - Start a tmux session
+    - Press `C-b I` to install plugins
+
+4. **Git configuration**:
+    - Create a `~/.gitconfig.local` file with personal config
+    - See `~/.gitconfig.local.example` for reference
+
+## Updating
+
+To update the dotfiles repository and all submodules:
+
+```bash
+cd ~/dotfiles
+git pull
+git submodule update --init --recursive
+```
diff --git a/git/.gitconfig.local.example b/git/.gitconfig.local.example
new file mode 100644
index 0000000..cec7aa6
--- /dev/null
+++ b/git/.gitconfig.local.example
@@ -0,0 +1,5 @@
+# This is Git's per-user configuration file.
+[user]
+# Please adapt and uncomment the following lines:
+	name = Full Name
+	email = user.name@email.com
diff --git a/zsh/.zshrc b/zsh/.zshrc
index 13a0630..039e892 100644
--- a/zsh/.zshrc
+++ b/zsh/.zshrc
@@ -29,7 +29,11 @@ case "$(uname -s)" in
     Linux*) {
         source /usr/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
         # make less more friendly for non-text input files, see lesspipe(1)
-        [ -x /usr/bin/lesspipe ] && eval "$(lesspipe)"
+        local lesspipe_bin_location
+        lesspipe_bin_location=$(which lesspipe)
+        if [ $? -eq 0 ]; then
+            [ -x $lesspipe_bin_location ] && eval "$(lesspipe)"
+        fi
     } ;;
     Darwin*) {
         source "$(brew --prefix)/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh"