chore(nvim): update Corpus plug-in
[wincent.git] / README.md
1 # "dotfiles" and system configuration
2
3 ![](https://github.com/wincent/wincent/workflows/ci/badge.svg)
4
5 > These dotfiles are affectionately dedicated to the vi editor originally created by Bill Joy, with whom I have spent many pleasant evenings[^1]
6
7 — Greg Hurrell, [paraphrasing Donald Knuth](https://en.wikipedia.org/wiki/The_Art_of_Computer_Programming)
8
9 ## Overview
10
11 ![](https://raw.githubusercontent.com/wincent/wincent/media/screenshot.png)
12
13 - Target platforms: macOS and Linux (see [Platform status](#platform-status) below).
14 - Set-up method: ~~Beautiful and intricate snowflake~~ an incredibly over-engineered custom configuration framework called [Fig](./fig/README.md).
15 - Visible in the screenshot:
16   - [The "bright" Base16](http://chriskempson.com/projects/base16/) color scheme (see [screenshots of other colorschemes](https://github.com/wincent/wincent/blob/media/colorschemes/README.md)).
17   - [Adobe Source Code Pro](https://github.com/adobe-fonts/source-code-pro) (Light) font.
18   - [Neovim](https://neovim.io), running inside [tmux](https://github.com/tmux/tmux), inside [iTerm2](http://www.iterm2.com/), on macOS "Big Sur"[^monterey].
19
20 [^monterey]: I'm currently running Monterey, but haven't taken a new screenshot yet.
21
22 ## Features
23
24 ### Dotfiles
25
26 [A set of dotfiles](https://github.com/wincent/wincent/tree/main/aspects/dotfiles/files) that I've been tweaking and twiddling since the early 2000s ([under version control](https://github.com/wincent/wincent/commit/61a7e2a830edb7) since 2009). Characteristics include:
27
28 - Sane Vim pasting via bracketed paste mode.
29 - Write access to local clipboard from local and remote hosts, inside and outside of tmux (via [Clipper](https://github.com/wincent/clipper)).
30 - Full mouse support (pane/split resizing, scrolling, text selection) in Vim and tmux.
31 - Focus/lost events for Vim inside tmux.
32 - Cursor shape toggles on entering Vim.
33 - Italics in the terminal.
34 - Bundles a (not-excessive) number of [useful Vim plug-ins](https://github.com/wincent/wincent/tree/main/aspects/nvim/files/.config/nvim/pack/bundle/opt).
35 - Conservative Vim configuration (very few overrides of core functionality; most changes are unobtrusive enhancements; some additional functionality exposed via `<Leader>` and `<LocalLeader>` mappings.
36 - Relatively restrained Zsh config, Bash-like but with a few Zsh perks, such as right-side prompt, auto-cd hooks, command elapsed time printing and such.
37 - Unified color-handling (across iTerm2 and Vim) via [Base16 Shell](https://github.com/chriskempson/base16-shell).
38 - Encrypted versioning of files with sensitive content (via [git-cipher](https://github.com/wincent/git-cipher)).
39 - Comprehensive [Hammerspoon](http://www.hammerspoon.org/) [config](https://github.com/wincent/wincent/tree/main/aspects/dotfiles/files/.hammerspoon).
40
41 ### Homebrew
42
43 On macOS, [the "homebrew" aspect](https://github.com/wincent/wincent/tree/main/aspects/homebrew) installs [a bunch of useful software](https://github.com/wincent/wincent/blob/main/aspects/homebrew/templates/Brewfile.erb).
44
45 ### Keyboard customization
46
47 On macOS, we use [Karabiner-Elements](https://github.com/tekezo/Karabiner-Elements/), and on Linux, we use [Interception Tools](https://gitlab.com/interception/linux/tools) and a few other pieces to make the following changes:
48
49 - Make Caps Lock serve as Backspace (when tapped) and Left Control (when chorded with another key). When held down alone, Caps Lock fires repeated Backspace events.
50 - Make Return serve as Return (when tapped) and Right Control (when chorded with another key). When held down alone, Return fires repeated Return events.
51 - Maps Control-I to F6 (only in the terminal) so that it can be mapped independently from Tab in Vim.
52 - Toggle Caps Lock on by tapping both Shift keys simultaneously.
53 - Makes the function keys on my external Realforce keyboard behave like the "media" keys on Apple's keyboards.
54
55 And these only on macOS:
56
57 - Swap Option and Command keys on my external Realforce keyboard.
58 - Make the "application" key (extra modifier key on right-hand side) behave as "fn" on Realforce keyboard.
59 - Make "pause" (at far-right of function key row) behave as "power" (effectively, sleep) on Realforce keyboard.
60 - Adds a "SpaceFN" layer that can be activated by holding down Space while hitting other keys; I use this to make the cursor keys available on or near the home row in any app.
61
62 ### Zsh
63
64 #### Functions
65
66 - `ag`: Transparently wraps the `ag` executable so as to provide a centralized place to set defaults for that command (seeing as it has no "rc" file).
67 - `bounce`: bounce the macOS Dock icon if the terminal is not in the foreground.
68 - `color`: change terminal and Vim color scheme.
69 - `fd`: "find directory" using fast `bfs` and `sk`; automatically `cd`s into the selected directory.
70 - `fh`: "find [in] history"; selecting a history item inserts it into the command line but does not execute it.
71 - `history`: overrides the (tiny) default history count.
72 - `jump` (aliased to `j`): to jump to hashed directories.
73 - `regmv`: bulk-rename files (eg. `regmv '/\.tif$/.tiff/' *`).
74 - `scratch`: create a random temporary scratch directory and `cd` into it.
75 - `tick`: moves an existing time warp (eg. `tick +1h`); see `tw` below for a description of time warp.
76 - `tmux`: wrapper that reattches to pre-existing sessions, or creates new ones based on the current directory name; additionally, looks for a `.tmux` file to set up windows and panes (note that the first time a given `.tmux` file is encountered the wrapper asks the user whether to trust or skip it).
77 - `tw` ("time warp"): overrides `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` (eg. `tw -1d`).
78
79 #### Prompt
80
81 Zsh is configured with the following prompt:
82
83 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt.png)
84
85 Visible here are:
86
87 - Concise left-hand prompt consisting of:
88   - Last component of current directory (abbreviates `$HOME` to `~` if possible).
89   - Prompt marker, `❯`, the "[HEAVY RIGHT-POINTING ANGLE QUOTATION MARK ORNAMENT](https://codepoints.net/U+276F)" (that's `\u276f`, or `e2 9d af` in UTF-8).
90 - Extended right-hand size prompt which auto-hides when necessary to make room for long commands and contains:
91   - Duration of previous command in adaptive units (seconds, minutes, hours, days, depending on duration).
92   - Current version control branch name.
93   - Current version control worktree status using colors that match those used in `git status`:
94     - Green dot indicates staged changes.
95     - Red dot indicates unstaged changes.
96     - Blue dot indicates untracked files.
97   - Full version of current working directory (again, abbreviating `$HOME` to `~`).
98
99 Nested shells are indicated with additional prompt characters. For example, one nested shell:
100
101 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-shlvl-2.png)
102
103 Two nested shells:
104
105 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-shlvl-3.png)
106
107 Root shells are indicated with a different color prompt character and the word "root":
108
109 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-root.png)
110
111 Nesting within a root shell is indicated like this:
112
113 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-root-shlvl-2.png)
114
115 Two nested shells:
116
117 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-root-shlvl-3.png)
118
119 If the last command exited with a non-zero status (usually indicative of an error), a yellow exclamation is shown:
120
121 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-error.png)
122
123 If there are background processes, a yellow asterisk is shown:
124
125 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-bg.png)
126
127 ## Dependencies
128
129 - [tmux](https://github.com/tmux/tmux) 3.2 or later.
130 - [Neovim](https://neovim.io) v0.5.0 or later.
131 - Relatively recent [Zsh](http://www.zsh.org/).
132 - Relatively recent [Git](http://git-scm.com/).
133 - [Clipper](https://wincent.com/products/clipper) for transparent access to the local system clipboard.
134 - On macOS, [iTerm2](http://www.iterm2.com/). Additionally, only the latest version of macOS (at the time of writing, Monterey) gets actively tested.
135 - [Ruby](https://www.ruby-lang.org/).
136 - [Adobe Source Code Pro](https://github.com/adobe-fonts/source-code-pro) or any other fixed-width font that includes the [Powerline glyphs](http://powerline.readthedocs.io/en/master/installation.html#fonts-installation).
137
138 ## Platform status
139
140 | Platform                               | Status                                                                                                                                                               |
141 | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
142 | macOS                                  | :1st_place_medal: Currently the most tested platform, as well as the one with most aspects (because macOS 12 "Monterey" is my daily driver both at home and at work) |
143 | Debian(-ish) Linux                     | :2nd_place_medal: I use this heavily at work, but in the somewhat odd Codespaces VM environment, so there are some weird assumptions at play                         |
144 | Arch Linux                             | :3rd_place_medal: Less tested, fewer aspects involved, but likely to evolve in the future as I'm using Arch Linux on my "leisure" desktop machine                    |
145 | Red Hat Linux and related (eg. CentOS) | :skull: Abandoned, but in the past (2011-2018) this was the distro I used full-time at work                                                                          |
146
147 ## Installation
148
149 ### Clone
150
151 Development occurs on the `main` branch, but to avoid inconvenience for people who previously cloned the repo when the `master` branch was the main line, the legacy branch _is_ kept up-to-date via [a pre-push hook](./support/hooks/pre-push) (which updates the local branch) and [a post-receive hook](./support/hooks/post-receive) (which updates the remote).
152
153 #### macOS
154
155 ```sh
156 git clone --recursive https://github.com/wincent/wincent.git
157 ```
158
159 #### Arch Linux
160
161 ```sh
162 sudo pacman -Syu
163 sudo pacman -S git ruby tmux vim
164 git clone --recursive https://github.com/wincent/wincent.git
165 ```
166
167 - `git`: In order to clone the repo.
168 - `ruby`: So that git-cipher can run (also used to build Command-T).
169 - `tmux`: Just for comfort (eg. so you can see scrollback).
170 - `vim`: Because the `nvim` aspect needs Vim (it runs `vim` to do a `:helptags` update).
171
172 ### Install
173
174 > ⚠️ **WARNING:** There are _lots_ of different things that can be installed or configured (see [the `aspects/` directory](./aspects)). Unless you want your machine to be exactly like mine — which is unlikely — you probably don't want to install _everything_. Maybe you don't even want everything in the ["dotfiles"](./aspects/dotfiles) and ["nvim"](./aspects/nvim) aspects. Please inspect the contents of each aspect before proceeding to install it; you may even be better off just looking at the configuration files and stealing the bits that you find interesting or useful (everything is [in the public domain](./LICENSE.md), unless otherwise indicated).
175
176 At the time of writing, these are the aspects, which you can expect to change over time (see [the `aspects/` directory](./aspects) for an up-to-date listing):
177
178 - On macOS only:
179   - **automator**: Scripts for use with Automator
180   - **automount**: Sets up macOS's automount facility
181   - **backup**: Backup scripts
182   - **cron**: Sets up cron files
183   - **defaults**: Sets up defaults (ie. preferences) on macOS
184   - **fonts**: Installs Source Code Pro font files
185   - **homebrew**: Installs and updates Homebrew
186   - **iterm**: Dynamic profiles for iTerm
187   - **karabiner**: Configures Karabiner-Elements (keyboard customization).
188   - **launchd**: Configures launchd
189   - **node**: Installs Node.js
190   - **ruby**: Installs Ruby gems
191   - **ssh**: Manages local SSH config
192   - **tampermonkey**: Sets up UserScripts
193 - On Linux only:
194   - **apt**: Installs packages using `apt-get`.
195   - **aur**: Installs packages from the Arch User Repository.
196   - **avahi**: Manages the Avahi zeroconf ("Bonjour") networking daemon.
197   - **codespaces**: Custom tweaks for GitHub Codespaces environments.
198   - **interception**: Sets up Interceptions Tools (keyboard customization).
199   - **locale**: Sets up /etc/locale.conf
200   - **pacman**: Installs packages via the Pacman package manager
201   - **sshd**: Manages sshd.
202   - **systemd**: Set up services that run from systemd
203 - On both macOS and Linux:
204   - **dotfiles**: Creates symlinks in \$HOME to the dotfiles in this repo
205   - **meta**: Tests the configuration framework
206   - **shell**: Sets the use shell to zsh
207   - **terminfo**: Sets up terminfo database entries for italics and 256-color support
208   - **nvim**: Configures Neovim and Vim
209
210 #### Examples
211
212 ```sh
213 ./install dotfiles nvim     # Just install "dotfiles" and "nvim" stuff.
214 ./install dotfiles          # Just install "dotfiles".
215 ./install dotfiles --step   # Prompt for confirmation at each step.
216 ./install dotfiles --check  # Do a dry-run, showing what would be changed.
217 ./install                   # Install everything.
218 ./install --help            # Info on installing specific rol
219 ```
220
221 This sets up a local Node environment using [n](https://github.com/tj/n), and then uses [Fig](./fig/README.md) to copy the dotfiles and configure the machine.
222
223 **Note:** Given that `~/.gitconfig` is included with these dotfiles, any local modifications or overrides that you apply should be added to `~/.gitconfig.local` instead; for example:
224
225 ```sh
226 git config --file ~/.gitconfig.local user.name "John Doe"
227 git config --file ~/.gitconfig.local user.email johndoe@example.com
228 ```
229
230 #### Manual steps
231
232 As much as I would love this thing to be entirely automated, there are some manual steps that must typically be performed.
233
234 ##### macOS
235
236 - **In iTerm, mark the "Wincent" dynamic profile as the default:** _Preferences_ → _Profiles_ → _Other actions..._ → _Set as Default_
237 - **Set up full-disk access for iTerm:** [As described here](https://gitlab.com/gnachman/iterm2/-/wikis/Fulldiskaccess), _System Preferences_ → _Security &amp; Privacy_ → _Privacy_ → _Full Disk Access_ (and make sure that iTerm.app is in the list with the checkbox checked).
238
239 ### Troubleshooting
240
241 #### General troubleshooting
242
243 There are a few useful `./install` options:
244
245 ```sh
246 # Run in "check" (dry-run) mode.
247 ./install --check
248
249 # Show debugging information during the run.
250 ./install --debug
251
252 # Confirm each task before running it (--step), and begin
253 # execution from a specific task (--start-at-task) in a
254 # specific aspect ("dotfiles").
255 ./install --step --start='make directories' dotfiles
256 ```
257
258 ### License
259
260 Unless otherwise noted, the contents of this repo are in the public domain. See the [LICENSE](LICENSE.md) for details.
261
262 ### Authors
263
264 The repo is written and maintained by Greg Hurrell &lt;[greg@hurrell.net](mailto:greg@hurrell.net)&gt;. Other contributors that have submitted patches include, in alphabetical order:
265
266 - Anton Kastritskiy
267 - Joe Lencioni
268 - Jonathan Wilkins
269 - Keng Kiat Lim
270 - Mark Stenglein
271 - Matthew Byrne
272 - Michael Lohmann
273 - Stone C. Lasley
274 - Victor Igor
275 - Zac Collier
276
277 This list produced with:
278
279     :read !git shortlog -s HEAD | grep -v 'Greg Hurrell' | cut -f 2-3 | sed -e 's/^/- /'
280
281 [^1]: The evenings were spent with [vi](https://en.wikipedia.org/wiki/Vi) derivatives, not with Bill Joy.