]> git.wincent.com - wincent.git/blob - README.md
chore: update typescript from 3.8.3 to 3.9.2
[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 Red Hat-like Linuxes (eg. CentOS).
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     -   Vim, running inside tmux, inside iTerm2, on macOS "High Sierra".
13
14 ## Features
15
16 ### Dotfiles
17
18 [A set of dotfiles](https://github.com/wincent/wincent/tree/master/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/master/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/master/aspects/dotfiles/files/.hammerspoon).
32
33 ### Homebrew
34
35 On macOS, [the "homebrew" aspect](https://github.com/wincent/wincent/tree/master/aspects/homebrew) installs [a bunch of useful software](https://github.com/wincent/wincent/blob/master/aspects/homebrew/templates/Brewfile.erb).
36
37 ### Keyboard customization
38
39 On macOS, [Karabiner-Elements](https://github.com/tekezo/Karabiner-Elements/) is used for the following:
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 MacVim and 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 -   Swap Option and Command keys on my external Realforce keyboard.
47 -   Make the "application" key (extra modifier key on right-hand side) behave as "fn" on Realforce keyboard.
48 -   Make "pause" (at far-right of function key row) behave as "power" (effectively, sleep) on Realforce keyboard.
49 -   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.
50
51 ### Zsh
52
53 #### Functions
54
55 -   `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).
56 -   `bounce`: bounce the macOS Dock icon if the terminal is not in the foreground.
57 -   `color`: change terminal and Vim color scheme.
58 -   `fd`: "find directory" using fast `bfs` and `sk`; automatically `cd`s into the selected directory.
59 -   `fh`: "find [in] history"; selecting a history item inserts it into the command line but does not execute it.
60 -   `history`: overrides the (tiny) default history count.
61 -   `jump` (aliased to `j`): to jump to hashed directories.
62 -   `regmv`: bulk-rename files (eg. `regmv '/\.tif$/.tiff/' *`).
63 -   `scratch`: create a random temporary scratch directory and `cd` into it.
64 -   `tick`: moves an existing time warp (eg. `tick +1h`); see `tw` below for a description of time warp.
65 -   `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).
66 -   `tw` ("time warp"): overrides `GIT_AUTHOR_DATE` and `GIT_COMMITTER_DATE` (eg. `tw -1d`).
67
68 #### Prompt
69
70 Zsh is configured with the following prompt:
71
72 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt.png)
73
74 Visible here are:
75
76 -   Concise left-hand prompt consisting of:
77     -   Last component of current directory (abbreviates `$HOME` to `~` if possible).
78     -   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).
79 -   Extended right-hand size prompt which auto-hides when necessary to make room for long commands and contains:
80     -   Duration of previous command in adaptive units (seconds, minutes, hours, days, depending on duration).
81     -   Current version control branch name.
82     -   Current version control worktree status using colors that match those used in `git status`:
83         -   Green dot indicates staged changes.
84         -   Red dot indicates unstaged changes.
85         -   Blue dot indicates untracked files.
86     -   Full version of current working directory (again, abbreviating `$HOME` to `~`).
87
88 Nested shells are indicated with additional prompt characters. For example, one nested shell:
89
90 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-shlvl-2.png)
91
92 Two nested shells:
93
94 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-shlvl-3.png)
95
96 Root shells are indicated with a different color prompt character and the word "root":
97
98 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-root.png)
99
100 Nesting within a root shell is indicated like this:
101
102 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-root-shlvl-2.png)
103
104 Two nested shells:
105
106 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-root-shlvl-3.png)
107
108 If the last command exited with a non-zero status (usually indicative of an error), a yellow exclamation is shown:
109
110 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-error.png)
111
112 If there are background processes, a yellow asterisk is shown:
113
114 ![](https://raw.githubusercontent.com/wincent/wincent/media/prompt-bg.png)
115
116 ## Dependencies
117
118 -   [tmux](http://tmux.sourceforge.net/) 2.3 or later.
119 -   [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).
120 -   Relatively recent [Zsh](http://www.zsh.org/).
121 -   Relatively recent [Git](http://git-scm.com/).
122 -   [Clipper](https://wincent.com/products/clipper) for transparent access to the local system clipboard.
123 -   On macOS, [iTerm2](http://www.iterm2.com/). Additionally, only the latest version of macOS (although at the time of writing, I'm still on High Sierra) gets actively tested.
124 -   [Ruby](https://www.ruby-lang.org/).
125 -   [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).
126
127 ## Installation
128
129 ### Clone
130
131 ```sh
132 git clone --recursive https://github.com/wincent/wincent.git
133 ```
134
135 ### Install
136
137 > ⚠️ **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).
138
139 At the time of writing, these are the aspects, which you can expect to change over time:
140
141 -   **automator**: Scripts for use with Automator
142 -   **backup**: Backup scripts
143 -   **cron**: Sets up cron files
144 -   **defaults**: Sets up defaults (ie. preferences) on macOS
145 -   **dotfiles**: Creates symlinks in \$HOME to the dotfiles in this repo
146 -   **fonts**: Installs Source Code Pro font files
147 -   **homebrew**: Installs and updates Homebrew
148 -   **iterm**: Dynamic profiles for iTerm
149 -   **karabiner**: Configures Karabiner-Elements
150 -   **launchd**: Configures launchd
151 -   **meta**: Tests the configuration framework
152 -   **node**: Installs Node.js
153 -   **ruby**: Installs Ruby gems
154 -   **shell**: Sets the use shell to zsh
155 -   **ssh**: Manages local SSH config
156 -   **terminfo**: Sets up terminfo database entries for italics and 256-color support
157 -   **vim**: Configures Vim
158
159 #### Examples
160
161 ```sh
162 ./install dotfiles vim      # Just install "dotfiles" and "vim" stuff.
163 ./install dotfiles          # Just install "dotfiles".
164 ./install dotfiles --step   # Prompt for confirmation at each step.
165 ./install dotfiles --check  # Do a dry-run, showing what would be changed.
166 ./install                   # Install everything.
167 ./install --help            # Info on installing specific rol
168 ```
169
170 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.
171
172 **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:
173
174 ```sh
175 git config --file ~/.gitconfig.local user.name "John Doe"
176 git config --file ~/.gitconfig.local user.email johndoe@example.com
177 ```
178
179 ### Troubleshooting
180
181 #### General troubleshooting
182
183 There are a few useful `./install` options:
184
185 ```sh
186 # Run in "check" (dry-run) mode.
187 ./install --check
188
189 # Show debugging information during the run.
190 ./install --debug
191
192 # Confirm each task before running it (--step), and begin
193 # execution from a specific task (--start-at-task) in a
194 # specific aspect ("dotfiles").
195 ./install --step --start='make directories' dotfiles
196 ```
197
198 #### Broken Unicode in Vim (Linux)
199
200 If Unicode symbols appear missing or corrupted in Vim, first ensure that your terminal emulator supports UTF-8. Then, check to see if you've properly configured your system-wide UTF-8 support.
201
202 Issue this test command:
203
204 ```bash
205 export LC_ALL=en_US.UTF-8
206 ```
207
208 Then run `vim`. Unicode in the statusline should be working.
209
210 To persist this `LC_*` variable binding, edit your `locale` accordingly:
211
212 ```bash
213 /etc/locale.conf
214
215 LANG=en_US.UTF-8
216 LC_ALL=en_US.UTF-8
217 ```
218
219 ### License
220
221 Unless otherwise noted, the contents of this repo are in the public domain. See the [LICENSE](LICENSE.md) for details.
222
223 ### Authors
224
225 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:
226
227 -   Joe Lencioni
228 -   Jonathan Wilkins
229 -   Mark Stenglein
230 -   Matthew Byrne
231 -   Stone C. Lasley
232 -   Victor Igor
233 -   Zac Collier
234
235 This list produced with:
236
237     :read !git shortlog -s HEAD | grep -v 'Greg Hurrell' | cut -f 2-3 | sed -e 's/^/- /'