1 # Emacs Configuration

     2 

     3 Personal Emacs configuration focused on simplicity and modern tooling while respecting default Emacs keybindings.

     4 

     5 ## Philosophy

     6 

     7 - Clean and minimal configuration

     8 - Prefer built-in Emacs functionality when possible

     9 - Use modern, actively maintained packages

    10 - Respect default Emacs keybindings

    11 - Single `init.el` file for simplicity

    12 

    13 ## Structure

    14 

    15 ```

    16 ~/.emacs.d/

    17 ├── init.el           # Main configuration file

    18 ├── elisp/            # Custom configuration modules

    19 │   ├── c-init.el     # C/C++ configuration

    20 │   └── ansible-init.el # Ansible/YAML configuration

    21 └── README.md         # This file

    22 ```

    23 

    24 ## Key Packages

    25 

    26 ### Completion Framework

    27 - **vertico** - Vertical completion UI

    28 - **orderless** - Flexible completion style (space-separated patterns)

    29 - **consult** - Enhanced commands (buffer switching, search, etc.)

    30 - **marginalia** - Helpful annotations in completion candidates

    31 

    32 ### Development

    33 - **company** - Auto-completion

    34 - **flycheck** - Syntax checking

    35 - **treesit-auto** - Tree-sitter modes with automatic grammar installation

    36 - **magit** - Git interface

    37 - **forge** - GitHub/GitLab integration for magit

    38 - **magit-todos** - Show TODO/FIXME comments in magit status

    39 

    40 ### Editing

    41 - **paredit** - Structured editing for Lisp

    42 - **expand-region** - Smart region expansion

    43 - **move-text** - Move lines/regions up and down

    44 - **visual-regexp** - Visual feedback for regexp replace

    45 - **yasnippet** - Snippet expansion

    46 - **emmet-mode** - HTML/CSS abbreviation expansion

    47 - **rainbow-delimiters** - Colorize nested delimiters

    48 

    49 ### Modes

    50 - **markdown-mode** - Markdown editing

    51 - **terraform-mode** - Terraform configuration files

    52 - **yaml-mode** - YAML files

    53 - **json-mode** - JSON files

    54 - **hgignore-mode** - Mercurial ignore files

    55 

    56 ### Utilities

    57 - **ibuffer-project** - Group buffers by project

    58 - **exec-path-from-shell** - Import shell environment variables

    59 - **rg** - ripgrep integration

    60 

    61 ## Key Bindings

    62 

    63 ### Custom Bindings

    64 - `C-c c` - Compile

    65 - `C-c r` - Recompile

    66 - `C-c a` - Align regexp

    67 - `C-c g` - Consult ripgrep (search with preview)

    68 - `C-c s` - Launch eshell

    69 - `C-x g` - Magit status

    70 - `C-x C-b` - ibuffer (better buffer list)

    71 - `C-=` - Expand region

    72 - `M-p` / `M-n` - Move text up/down

    73 - `M-%` - Visual regexp replace

    74 - `C-M-%` - Visual regexp query replace

    75 

    76 ### Enhanced Default Bindings

    77 - `M-x` - Command execution (enhanced with vertico)

    78 - `C-x b` - Switch buffer (enhanced with consult)

    79 - `M-y` - Yank from kill ring (enhanced with consult)

    80 - `M-/` - Company completion

    81 

    82 ## Installation

    83 

    84 1. Clone this repository:

    85    ```bash

    86    git clone [email protected]:lukehoersten/emacs.d.git ~/.emacs.d

    87    ```

    88 

    89 2. Launch Emacs - packages will auto-install on first run

    90 

    91 3. For tree-sitter modes, grammars install automatically when first opening a file

    92 

    93 ## Tree-sitter Support

    94 

    95 Tree-sitter provides faster, more accurate syntax highlighting and parsing. Enabled automatically for:

    96 - JavaScript/TypeScript

    97 - JSON

    98 - Python

    99 - And many more (via `treesit-auto`)

   100 

   101 Grammars install automatically on first use.

   102 

   103 ## Customizations

   104 

   105 Emacs customizations are redirected to `custom.el` (gitignored) to keep `init.el` clean.

   106 The configuration uses `package-require` for explicit package management.

   107 

   108 ## Updating Packages

   109 

   110 ```elisp

   111 M-x package-refresh-contents

   112 M-x package-update-all

   113 ```

   114 

   115 ## Notes

   116 

   117 - Theme: Solarized Light (GUI only)

   118 - Font: Inconsolata-12 (GUI only)

   119 - Shell: eshell (launched automatically on startup)

   120 - Whitespace cleanup on save enabled globally