]> git.wincent.com - wincent.git/blob - README.md
feat: add bin/git-cipher symlink as a convenience
[wincent.git] / README.md
1 # "dotfiles" and system configuration
2
3 ![](https://github.com/wincent/wincent/workflows/ci/badge.svg)
4
5 ![](https://raw.githubusercontent.com/wincent/wincent/media/screenshot.png)
6
7 - Target platforms: macOS and Linux (see [Platform status](#platform-status) below).
8 - Set-up method: ~~Beautiful and intricate snowflake~~ an incredibly over-engineered custom configuration framework called [Fig](./fig/README.md).
9 - Visible in the screenshot:
10   - [default-dark Base16](http://chriskempson.com/projects/base16/) color scheme (see [screenshots of other colorschemes](https://github.com/wincent/wincent/blob/media/colorschemes/README.md)).
11   - [Adobe Source Code Pro](https://github.com/adobe-fonts/source-code-pro) (Light) font.
12   - [Neovim](https://neovim.io), running inside [tmux](https://github.com/tmux/tmux), inside [iTerm2](http://www.iterm2.com/), on macOS "High Sierra".
13
14 ## Features
15
16 ### Dotfiles
17
18 [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:
19
20 - Sane Vim pasting via bracketed paste mode.
21 - Write access to local clipboard from local and remote hosts, inside and outside of tmux (via [Clipper](https://github.com/wincent/clipper)).
22 - Full mouse support (pane/split resizing, scrolling, text selection) in Vim and tmux.
23 - Focus/lost events for Vim inside tmux.
24 - Cursor shape toggles on entering Vim.
25 - Italics in the terminal.
26 - Bundles a (not-excessive) number of [useful Vim plug-ins](https://github.com/wincent/wincent/tree/main/aspects/vim/files/.vim/pack).
27 - Conservative Vim configuration (very few overrides of core functionality; most changes are unobtrusive enhancements; some additional functionality exposed via `<Leader>` and `<LocalLeader>` mappings.
28 - 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.
29 - Unified color-handling (across iTerm2 and Vim) via [Base16 Shell](https://github.com/chriskempson/base16-shell).
30 - Encrypted versioning of files with sensitive content (via [git-cipher](https://github.com/wincent/git-cipher)).
31 - Comprehensive [Hammerspoon](http://www.hammerspoon.org/) [config](https://github.com/wincent/wincent/tree/main/aspects/dotfiles/files/.hammerspoon).
32
33 ### Homebrew
34
35 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).
36
37 ### Keyboard customization
38
39 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:
40
41 - 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.
42 - Make Return serve as Return (when tapped) and Right Control (when chorded with another key). When held down alone, Return fires repeated Return events.
43 - Maps Control-I to F6 (only in the terminal) so that it can be mapped independently from Tab in Vim.
44 - Toggle Caps Lock on by tapping both Shift keys simultaneously.
45 - Makes the function keys on my external Realforce keyboard behave like the "media" keys on Apple's keyboards.
46
47 And these only on macOS:
48
49 - Swap Option and Command keys on my external Realforce keyboard.
50 - Make the "application" key (extra modifier key on right-hand side) behave as "fn" on Realforce keyboard.
51 - Make "pause" (at far-right of function key row) behave as "power" (effectively, sleep) on Realforce keyboard.
52 - 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.
53
54 ### Zsh
55
56 #### Functions
57
58 - `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).
59 - `bounce`: bounce the macOS Dock icon if the terminal is not in the foreground.
60 - `color`: change terminal and Vim color scheme.
61 - `fd`: "find directory" using fast `bfs` and `sk`; automatically `cd`s into the selected directory.
62 - `fh`: "find [in] history"; selecting a history item inserts it into the command line but does not execute it.
63 - `history`: overrides the (tiny) default history count.
64 - `jump` (aliased to `j`): to jump to hashed directories.
65 - `regmv`: bulk-rename files (eg. `regmv '/\.tif$/.tiff/' *`).
66 - `scratch`: create a random temporary scratch directory and `cd` into it.
67 - `tick`: moves an existing time warp (eg. `tick +1h`); see `tw` below for a description of time warp.
68 - `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).
69 - `tw` ("time warp"): overrides `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` (eg. `tw -1d`).
70
71 #### Prompt
72
73 Zsh is configured with the following prompt:
74
75 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt.png)
76
77 Visible here are:
78
79 - Concise left-hand prompt consisting of:
80   - Last component of current directory (abbreviates `$HOME` to `~` if possible).
81   - 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).
82 - Extended right-hand size prompt which auto-hides when necessary to make room for long commands and contains:
83   - Duration of previous command in adaptive units (seconds, minutes, hours, days, depending on duration).
84   - Current version control branch name.
85   - Current version control worktree status using colors that match those used in `git status`:
86     - Green dot indicates staged changes.
87     - Red dot indicates unstaged changes.
88     - Blue dot indicates untracked files.
89   - Full version of current working directory (again, abbreviating `$HOME` to `~`).
90
91 Nested shells are indicated with additional prompt characters. For example, one nested shell:
92
93 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-shlvl-2.png)
94
95 Two nested shells:
96
97 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-shlvl-3.png)
98
99 Root shells are indicated with a different color prompt character and the word "root":
100
101 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-root.png)
102
103 Nesting within a root shell is indicated like this:
104
105 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-root-shlvl-2.png)
106
107 Two nested shells:
108
109 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-root-shlvl-3.png)
110
111 If the last command exited with a non-zero status (usually indicative of an error), a yellow exclamation is shown:
112
113 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-error.png)
114
115 If there are background processes, a yellow asterisk is shown:
116
117 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-bg.png)
118
119 ## Dependencies
120
121 - [tmux](https://github.com/tmux/tmux) 3.2 or later.
122 - [Neovim](https://neovim.io) or [Vim](http://www.vim.org/) 8.0 or later with Ruby and Python support (although there's a reasonable amount of feature detection in order to degrade gracefully).
123 - Relatively recent [Zsh](http://www.zsh.org/).
124 - Relatively recent [Git](http://git-scm.com/).
125 - [Clipper](https://wincent.com/products/clipper) for transparent access to the local system clipboard.
126 - On macOS, [iTerm2](http://www.iterm2.com/). Additionally, only the latest version of macOS (at the time of writing, Big Sur) gets actively tested.
127 - [Ruby](https://www.ruby-lang.org/).
128 - [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).
129
130 ## Platform status
131
132 | Platform                               | Status                                                                                                                                                                     |
133 | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
134 | macOS                                  | :1st_place_medal: Currently the most tested platform, as well as the one with most aspects (because macOS 10.13 "High Sierra" is my daily driver both at home and at work) |
135 | Arch Linux                             | :2nd_place_medal: Less tested, fewer aspects involved, but likely to evolve in the future as I experiment with moving, at least partially, to Arch Linux                   |
136 | Red Hat Linux and related (eg. CentOS) | :3rd_place_medal: Less tested, fewer aspects involved, but in the past this was the distro I used full-time at work                                                        |
137
138 ## Installation
139
140 ### Clone
141
142 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).
143
144 #### macOS
145
146 ```sh
147 git clone --recursive https://github.com/wincent/wincent.git
148 ```
149
150 #### Arch Linux
151
152 ```sh
153 sudo pacman -Syu
154 sudo pacman -S git ruby tmux vim
155 git clone --recursive https://github.com/wincent/wincent.git
156 ```
157
158 - `git`: In order to clone the repo.
159 - `ruby`: So that git-cipher can run (also used to build Command-T).
160 - `tmux`: Just for comfort (eg. so you can see scrollback).
161 - `vim`: Because the Vim aspect needs Vim (it runs `vim` to do a `:helptags` update).
162
163 ### Install
164
165 > ⚠️ **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 ["vim"](./aspects/vim) 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).
166
167 At the time of writing, these are the aspects, which you can expect to change over time:
168
169 - On macOS only:
170   - **automator**: Scripts for use with Automator
171   - **automount**: Sets up macOS's automount facility
172   - **backup**: Backup scripts
173   - **cron**: Sets up cron files
174   - **defaults**: Sets up defaults (ie. preferences) on macOS
175   - **fonts**: Installs Source Code Pro font files
176   - **homebrew**: Installs and updates Homebrew
177   - **iterm**: Dynamic profiles for iTerm
178   - **karabiner**: Configures Karabiner-Elements (keyboard customization).
179   - **launchd**: Configures launchd
180   - **node**: Installs Node.js
181   - **ruby**: Installs Ruby gems
182   - **ssh**: Manages local SSH config
183   - **tampermonkey**: Sets up UserScripts
184 - On Linux only:
185   - **aur**: Installs packages from the Arch User Repository.
186   - **interception**: Sets up Interceptions Tools (keyboard customization).
187   - **locale**: Sets up /etc/locale.conf
188   - **pacman**: Installs packages via the Pacman package manager
189   - **systemd**: Set up services that run from systemd
190 - On both macOS and Linux:
191   - **dotfiles**: Creates symlinks in \$HOME to the dotfiles in this repo
192   - **meta**: Tests the configuration framework
193   - **shell**: Sets the use shell to zsh
194   - **terminfo**: Sets up terminfo database entries for italics and 256-color support
195   - **vim**: Configures Vim
196
197 #### Examples
198
199 ```sh
200 ./install dotfiles vim      # Just install "dotfiles" and "vim" stuff.
201 ./install dotfiles          # Just install "dotfiles".
202 ./install dotfiles --step   # Prompt for confirmation at each step.
203 ./install dotfiles --check  # Do a dry-run, showing what would be changed.
204 ./install                   # Install everything.
205 ./install --help            # Info on installing specific rol
206 ```
207
208 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.
209
210 **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:
211
212 ```sh
213 git config --file ~/.gitconfig.local user.name "John Doe"
214 git config --file ~/.gitconfig.local user.email johndoe@example.com
215 ```
216
217 #### Manual steps
218
219 As much as I would love this thing to be entirely automated, there are some manual steps that must typically be performed.
220
221 ##### macOS
222
223 - **In iTerm, mark the "Wincent" dynamic profile as the default:** _Preferences_ → _Profiles_ → _Other actions..._ → _Set as Default_
224 - **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).
225
226 ### Troubleshooting
227
228 #### General troubleshooting
229
230 There are a few useful `./install` options:
231
232 ```sh
233 # Run in "check" (dry-run) mode.
234 ./install --check
235
236 # Show debugging information during the run.
237 ./install --debug
238
239 # Confirm each task before running it (--step), and begin
240 # execution from a specific task (--start-at-task) in a
241 # specific aspect ("dotfiles").
242 ./install --step --start='make directories' dotfiles
243 ```
244
245 ### License
246
247 Unless otherwise noted, the contents of this repo are in the public domain. See the [LICENSE](LICENSE.md) for details.
248
249 ### Authors
250
251 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:
252
253 - Anton Kastritskiy
254 - Joe Lencioni
255 - Jonathan Wilkins
256 - Keng Kiat Lim
257 - Mark Stenglein
258 - Matthew Byrne
259 - Michael Lohmann
260 - Stone C. Lasley
261 - Victor Igor
262 - Zac Collier
263
264 This list produced with:
265
266     :read !git shortlog -s HEAD | grep -v 'Greg Hurrell' | cut -f 2-3 | sed -e 's/^/- /'