|
| 1 | +# Usage |
| 2 | + |
| 3 | +### Organization |
| 4 | + |
| 5 | +Dotfiles are split up into folders called _topics_. Each topic folder has as _topics.yaml_ file which has details about the configuration. A topics will specify a list of symlinks and scripts. Here's an example of the VS Code (`editors/vscode`) topic. |
| 6 | + |
| 7 | +```yaml |
| 8 | +name: Visual Studio Code |
| 9 | +scripts: |
| 10 | + - name: Backup extensions |
| 11 | + file: backup-extensions.sh |
| 12 | + - name: Install extensions |
| 13 | + file: install-extensions.sh |
| 14 | + bootstrap: true |
| 15 | +symlinks: |
| 16 | + - src: keybindings.json |
| 17 | + path: ~/Library/Application Support/Code/User/keybindings.json |
| 18 | + - src: settings.json |
| 19 | + path: ~/Library/Application Support/Code/User/settings.json |
| 20 | + - src: snippets |
| 21 | + path: ~/Library/Application Support/Code/User/snippets |
| 22 | +``` |
| 23 | +
|
| 24 | +It has two scripts, backup extensions and install extensions. You'll notice install extensions has `bootstrap: true`, which means that this script will be run while bootstrapping the dotfiles! There are also a handful of symlinks, which will also be created when bootstrapping. |
| 25 | + |
| 26 | +### Setup |
| 27 | + |
| 28 | +```bash |
| 29 | +# Grab the dotfiles. |
| 30 | +$ git clone [email protected]:lgo/dotfiles.git ~/.dotfiles && ~/.dotfiles |
| 31 | +# Make the dotfiles more accessible to Finder. |
| 32 | +$ ln -s ~/.dotfiles ~/dotfiles |
| 33 | +
|
| 34 | +# (one-time prep, because the dotfiles manager is Ruby) |
| 35 | +$ bundle install |
| 36 | +
|
| 37 | +$ ./dotfiles.rb |
| 38 | +Usage: ./dotfiles.rb <subcommand> [options] |
| 39 | +
|
| 40 | +Commands: |
| 41 | + bootstrap - sets up symlinks and executes all installation scripts |
| 42 | + info - get information on topic(s) or script(s) |
| 43 | +
|
| 44 | +See 'dotfiles COMMAND --help' for more information on a specific command. |
| 45 | +``` |
| 46 | + |
| 47 | +### Usage |
| 48 | + |
| 49 | +```bash |
| 50 | +# You can view all of the available topics of dotfiles. |
| 51 | +$ ./dotfiles.rb info |
| 52 | +Available topics |
| 53 | +iterm: iTerm2 |
| 54 | +macos: macos |
| 55 | +editors/vscode: Visual Studio Code |
| 56 | +... |
| 57 | +
|
| 58 | +# You can view the specific details about a topic, including |
| 59 | +# 1. The state of the symlinks (✅-> installed, ❌ not installed) |
| 60 | +# 2. All of the scripts (⚙ -> bootstrap script) |
| 61 | +$ ./dotfiles.rb info editors/vscode |
| 62 | +Visual Studio Code (editors/vscode) |
| 63 | +
|
| 64 | + [✅] keybindings.json -> ~/Library/Application Support/Code/User/keybindings.json |
| 65 | + [✅] settings.json -> ~/Library/Application Support/Code/User/settings.json |
| 66 | + [❌] snippets -> ~/Library/Application Support/Code/User/snippets |
| 67 | +
|
| 68 | +Scripts |
| 69 | + Backup extensions (/Users/joey/.dotfiles/editors/vscode/backup-extensions.sh) |
| 70 | + [⚙ ] Install extensions (/Users/joey/.dotfiles/editors/vscode/install-extensions.sh) |
| 71 | +
|
| 72 | +(from /Users/joey/.dotfiles/editors/vscode) |
| 73 | +
|
| 74 | +# Bootstrap the dotfiles for editors/vscode, only making symlinks. |
| 75 | +$ ./dotfiles.rb bootstrap editors/vscode --only-symlinks |
| 76 | + [ ⚙ ] bootstrapping Visual Studio Code (editors/vscode) |
| 77 | + [ OK ] keybindings.json already linked |
| 78 | + [ OK ] settings.json already linked |
| 79 | + [ OK ] snippets linked |
| 80 | + [ ✅ ] completed Visual Studio Code (editors/vscode) |
| 81 | +
|
| 82 | +# Or, we can just run everything including the installation scripts. |
| 83 | +# --only-scripts can be provided to only run the bootstrap scripts. |
| 84 | +$ ./dotfiles.rb bootstrap editors/vscode |
| 85 | + [ ⚙ ] bootstrapping Visual Studio Code (editors/vscode) |
| 86 | + [ OK ] keybindings.json already linked |
| 87 | + [ OK ] settings.json already linked |
| 88 | + [ OK ] snippets already linked |
| 89 | + [ .. ] running script: Install extensions |
| 90 | + [ OK ] finished script |
| 91 | + [ ✅ ] completed Visual Studio Code (editors/vscode) |
| 92 | +``` |
| 93 | + |
| 94 | +# What's provided |
| 95 | + |
| 96 | +- zsh and an oh-my-zsh configuration |
| 97 | +- macos configurations. using the `defaults` command on macos, there are plenty of power-user system configuration that is set, such speeding up UI animations, disabling features that are commonly unused or slow (dashboard, launchpad), preventing chrome's gesture swipe to go forward/backward in history, and plenty more. This is all in the `macos/set-defaults.sh` script. |
| 98 | +- basic configurations for vscode, vim, and spacemacs & symlinking for them. |
| 99 | +- ... (probably lots more!) |
| 100 | + |
| 101 | +--- |
| 102 | + |
| 103 | +# dotfiles (old readme, from the holman/dotfiles base) |
| 104 | + |
| 105 | +Adopted from holman dotfiles. |
| 106 | + |
| 107 | +As with holman dotfiles, these are topic-centric which helps split |
| 108 | +things up to concerns of including software packages. |
| 109 | + |
| 110 | +## topical |
| 111 | + |
| 112 | +Everything's built around topic areas. If you're adding a new area to |
| 113 | +your forked dotfiles — say, "Java" — you can simply add a `java` |
| 114 | +directory and put files in there. Anything with an extension of `.zsh` |
| 115 | +will get automatically included into your shell. Anything with an |
| 116 | +extension of `.symlink` will get symlinked without extension into |
| 117 | +`$HOME` when you run `script/bootstrap`. |
| 118 | + |
| 119 | +## what's inside |
| 120 | + |
| 121 | +- homebrew setup |
| 122 | +- macOS configuration. this includes lots of system defaults |
| 123 | +- ... |
| 124 | + |
| 125 | +## components |
| 126 | + |
| 127 | +There's a few special files in the hierarchy. |
| 128 | + |
| 129 | +- **bin/**: Anything in `bin/` will get added to your `$PATH` and be made |
| 130 | + available everywhere. |
| 131 | +- **Brewfile**: This is a list of applications for |
| 132 | + [Homebrew Cask](http://caskroom.io) to install: things like Chrome and |
| 133 | + 1Password and Adium and stuff. Might want to edit this file before |
| 134 | + running any initial setup. |
| 135 | +- **topic/\*.zsh**: configuration files |
| 136 | + - Environment configuration (i.e., `.zshenv`) |
| 137 | + - **topic/\*env.zsh**: Any file ending with `env.zsh` is loaded |
| 138 | + second and is expected to setup any additional environment |
| 139 | + (e.g., shell options). |
| 140 | + - Interactive configuration (i.e., `.zshrc`) |
| 141 | + - **topic/\*path.zsh**: Any file ending with `path.zsh` (except |
| 142 | + those ending with `fpath.zsh`) is loaded first and is expected |
| 143 | + to setup `$PATH` or similar. |
| 144 | + - **topic/\*fpath.zsh**: Any file ending with `fpath.zsh` is |
| 145 | + loaded for interactive shells only. They are expected to |
| 146 | + populate `$fpath`. |
| 147 | + - **topic/\*.zsh**: Any files ending in `.zsh` (except those |
| 148 | + specified elsewhere) are loaded for interactive shells only. |
| 149 | + Interactive configuration can include aliases, color output, |
| 150 | + prompt configuration, or anything else that should only be |
| 151 | + loaded when a user is interacting with Zsh. |
| 152 | + - **topic/\*completion.zsh**: Any file ending with |
| 153 | + `completion.zsh` is loaded last for interactive shells only. |
| 154 | + They are expected to setup autocomplete. |
| 155 | + - Login configuration (i.e., `.zprofile`, `.zlogin`, `.zlogout`) |
| 156 | + - **topic/\*profile.zsh**: Any file ending with `profile.zsh` is |
| 157 | + loaded for login shells only. Unlike `.zlogin`, these files |
| 158 | + are loaded before the interactive files above are loaded. |
| 159 | + - **topic/\*login.zsh**: Any file ending in `login.zsh` is |
| 160 | + loaded for login shells only. Unlike `.zprofile`, they are |
| 161 | + loaded after your interactive files are loaded above. This is |
| 162 | + the ideal place to put anything you want to see when you start |
| 163 | + up a new login shell (e.g., cowsay, date, todo, fortune). |
| 164 | + - **topic/\*logout.zsh**: Any file ending in `logout.zsh` is |
| 165 | + loaded for login shells only and only when you exit/logout the |
| 166 | + shell. |
| 167 | +- **topic/\*.symlink**: Any files ending in `*.symlink` get symlinked into |
| 168 | + your `$HOME`. This is so you can keep all of those versioned in your dotfiles |
| 169 | + but still keep those autoloaded files in your home directory. These get |
| 170 | + symlinked in when you run `script/bootstrap`. |
| 171 | + |
| 172 | +## install |
| 173 | + |
| 174 | +Run this: |
| 175 | + |
| 176 | +```sh |
| 177 | +git clone https://github.com/lego/dotfiles.git ~/.dotfiles |
| 178 | +cd ~/.dotfiles |
| 179 | +script/bootstrap |
| 180 | +``` |
| 181 | + |
| 182 | +This will symlink the appropriate files in `.dotfiles` to your home directory. |
| 183 | +Everything is configured and tweaked within `~/.dotfiles`. |
| 184 | + |
| 185 | +The main file you'll want to change right off the bat is |
| 186 | +`zsh/zshenv.symlink`, which sets up a few paths that'll be different on |
| 187 | +your particular machine. |
| 188 | + |
| 189 | +`dot` is a simple script that installs some dependencies, sets sane macOS |
| 190 | +defaults, and so on. Tweak this script, and occasionally run `dot` from |
| 191 | +time to time to keep your environment fresh and up-to-date. You can find |
| 192 | +this script in `bin/`. |
| 193 | + |
| 194 | +## test |
| 195 | + |
| 196 | +Because you don't want to necessarily ruin your local environment |
| 197 | +everytime you make a change, let's use Docker. |
| 198 | + |
| 199 | +**Note:** you can only test the pieces of your dotfiles that will work |
| 200 | +in a Linux environment. macOS specifics cannot be tested. |
| 201 | + |
| 202 | +### dependencies |
| 203 | + |
| 204 | +#### docker |
| 205 | + |
| 206 | +Be sure Docker is installed. |
| 207 | + |
| 208 | +##### macOS |
| 209 | + |
| 210 | + brew cask install docker |
| 211 | + |
| 212 | +### run |
| 213 | + |
| 214 | + ./test/run.sh |
| 215 | + |
| 216 | +## bugs |
| 217 | + |
| 218 | +I want this to work for everyone; that means when you clone it down it should |
| 219 | +work for you even though you may not have `rbenv` installed, for example. That |
| 220 | +said, I do use this as _my_ dotfiles, so there's a good chance I may break |
| 221 | +something if I forget to make a check for a dependency. |
| 222 | + |
| 223 | +If you're brand-new to the project and run into any blockers, please |
| 224 | +[open an issue](https://github.com/holman/dotfiles/issues) on this repository |
| 225 | +and I'd love to get it fixed for you! |
| 226 | + |
| 227 | +## thanks |
| 228 | + |
| 229 | +I forked [Ryan Bates](http://github.com/ryanb)' excellent |
| 230 | +[dotfiles](http://github.com/ryanb/dotfiles) for a couple years before the |
| 231 | +weight of my changes and tweaks inspired me to finally roll my own. But Ryan's |
| 232 | +dotfiles were an easy way to get into bash customization, and then to jump ship |
| 233 | +to zsh a bit later. A decent amount of the code in these dotfiles stem or are |
| 234 | +inspired from Ryan's original project. |
0 commit comments