What?

My dotfiles. I am a developer who works primarily on macOS/Darwin. This configuration will allow you to do common things with very few keystrokes. After trying various combinations over the years I settled on zsh/neovim/wezterm and have customized them to work with each other.

Philosophy: "UNIX is an IDE." This setup prioritizes efficiency through minimal keystrokes and seamless integration between terminal, editor, and git workflows.

Left pane active. The results are from executing the alias l, which uses eza under the hood. The third column shows when the file/directory was last modified in the git repo.

Notes:

• Tabs by default are labeled with the git root directory, updating when you change directories
• Inactive panes are dimmed
• Changing panes is done with Shift ⌘ <direction>, where <direction> is a vim-style movement key, i.e.: hjkl. So after pressing Shift ⌘ L to switch to the pane to the right we get this:

Right pane active. Here Neovim is loaded with a Typescript file. An error on line 35 is being reported by the LSP.

This setup is fairly Zen: work is done primarily in the right pane, which means that the code I'm working on is generally centered on the screen.

Prerequisites

• macOS (primary target platform)
• Git (for cloning the repository)
• Make (usually pre-installed on macOS)
• Internet connection (for downloading Homebrew packages)

Installation

> git clone git@github.com:jchilders/dotfiles.git
> cd dotfiles
> make install

The install target will:

1. Set up macOS defalts
2. Link the xdg_config directory to $HOME/.config
3. Install the default Homebrew packages, including Neovim

To undo the above:

> make clean

Try it out without installing

Docker Container

Build and run a containerized version to test the dotfiles:

docker build -t dotfiles-demo .
docker run -it dotfiles-demo

This creates a full Linux environment with most tools installed via Homebrew.

VS Code Devcontainer

Open the project in VS Code and use the devcontainer:

1. Install the "Dev Containers" extension in VS Code
2. Open this repository in VS Code
3. Press Cmd+Shift+P and select "Dev Containers: Reopen in Container"
4. VS Code will build and open the devcontainer

Or use the devcontainer CLI:

# Install devcontainer CLI
npm install -g @devcontainers/cli

# Build and run
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . /bin/zsh

The devcontainer includes most tools and provides a consistent development environment.

Q: lol why are you using Make?

A: Because it works pretty well out of the box and is consistent. I tried nix, and my experience was similar to this: too many moving parts.

Quick Demo

After installation, try these key features:

• ctrl-o + o - Open any file with fuzzy search and preview
• ctrl-o + gs - Open files from git status (modified/staged files)
• l - Enhanced directory listing with git info and icons
• ctrl-o + gb - Switch git branches with fuzzy search
• <leader>z in Neovim - Toggle zen mode (leader = space)

The ctrl-o prefix acts like cmd-p in VS Code - it's your gateway to quickly opening and navigating files.

zsh/neovim: ctrl-o

Once you get everything installed and get a zsh prompt, hit ctrl-o.

ctrl-o acts as an action key prefix for opening files/doing things with them, similar to cmd-p in VSCode. Its primary purpose is to open files in $EDITOR. The full list of ctrl-o commands are given below, but these are a few of the most frequently used:

mapping	description
^oo	Open file. Respects .gitignore
^ogs	Open uncommited changed file ("git status")
^ob	Open buffer (neovim only)

Neovim: Working with REPLs/shells

Text in neovim can be sent to an adjacent pane for execution in the REPL or shell you're currently working in. This allows for testing out either single lines, or entire blocks. Try this:

1. Open nvim in the right pane.

• Hit cmd t to open a new tab if you need to

1. Insert the following into neovim: echo hello
2. Hit esc to exit insert mode
3. Press <space>sh. This will the current line to the pane to the left and execute it.

• Multiple lines can similarly be sent by visually selecting them and hitting <space>sh.

Neovim

The <leader> key is <space>.

Neovim: Zen-ish Mode

Press <leader>z to hide the gutter (current and relative line numbers, git indicators, etc.), indentation helpers, and any inline LSP warnings or errors appearing inline.

zenish-toggle.webm

Mappings

Tabs & Panes

mapping	description
cmd-t	New tab
cmd-w	Close tab
shift-cmd-[	Previous tab
shift-cmd-]	Next tab
shift-cmd-f	Toggle full screen
shift-cmd-n	Rotate panes
shift-cmd-<dir>	Go to pane in <dir> (hjkl)
cmd-<num>	Goto tab <num>
^ar	Rename tab
^a%	Horizontally split pane (left/right)
^a-	Vertically split pane (top/bottom)
^az	Zoom/unzoom pane.
^a[	Enter copy mode. Use hjkl to nav, then v to select, then y
to copy selected text to clipboard

ctrl-o

As mentioned above, ctrl-o acts as an action prefix similar to cmd-p/shift-cmd-p in VSCode. It's original purpose is to open files (hence the o prefix).

ctrl-o file mappings

These work in both zsh and nvim.

mapping	description
^oo	Open file. Respects .gitignore
^oO	Open any file. Ignores .gitignore

ctrl-o git mappings

mapping	description
^ogb	Switch git branch
^ogs	Open file ("git status")
^ogd	Show file diff (zsh only)
^oga	Add file to git staging area (zsh only)

The last two allow you to diff/add files extremely quickly. Say you just did ^gd (git diff) for README.md. Pressing ^oga after doing so will prompt you:

Add README.md to the git staging area? [Y/n/d/c]

Y will add it, n will abort, d will let you do a diff, and c will check it out, overwriting your changes. So if you do a ^ogd and realize you want to abandon the changes made to that file, just do ^oga then c and voila.

The mappings are built to allow for quickly doing diff/add operations. You are encouraged to try this until your muscle memory gets familiar with it. This flow works particularly well when there are multiple files that need to be reviewed and added to the commit (or reverted).

Neovim specific ctrl-o mappings

mapping	description
^ob	Switch buffer by filename
^or	go to symbol (method name, etc.) for current buffer

Other Noteworthy Neovim Mappings

The leader key is currently <space>.

mapping	description
Enter	Clear highlighted search
<Leader><Leader>	Switch between next/previous buffers
<Leader>z	Toggle Zen-ish mode
<Leader>]]	Go to next error/warning
<Leader>[[	Go to previous error/warning

Editing and Running Tests

mapping	description
<Leader>et	Edit the recently modified test
<Leader>rt	Run most recently modified test in left pane
<Leader>rT	Run most recently modified test for current line/test case in left pane

I use these very frequently.

Sending to panes

In my workflow I have wezterm open with two panes (left/right). The left pane is for a terminal or repl, the right pane is neovim. Keep this in mind for the below.

mapping	description
<Leader>s[dir]	Send current line/visual selection to the dir pane (hjkl)

This lets you quickly run individual lines (or blocks) in an adjacent repl. Hitting <Leader>sh sends the current line to the pane to the left (h direction). This works with visual blocks as well.

Opening localhost in browser (neovim)

mapping	description
<Leader>ol	Switches to browser, then to the tab w/ localhost, & reloads

zsh

Mappings

Additional zsh mappings:

mapping	description
^t	Find file and append to current cursor position
^r	Search command history

Aliases

alias	description
gcb	Copies current branch name to pasteboard (clipboard)
gd	git diff
gst	git status -sb
r	Rerun previous command

Ruby/Rails

ruby/rails zsh/neovim

These are available in both zsh and neovim.

mapping	description
^orc	Find & edit Rails controller
^orm	Find & edit Rails model
^orv	Find & edit Rails view

ruby/rails neovim

These are available in neovim.

mapping	description
<Leader>bp	Insert binding.pry below current line
<Leader>bP	Insert binding.pry above current line
<Leader>rp	Insert puts below current line
<Leader>rP	Insert puts above current line

ruby/rails zsh

These are available in zsh.

alias	description
bi	bundle install
cdgem <gem>	cd to the directory for the given gem
rc	bin/rails console, or bin/console if in a Gem directory
rs	rails server
rdbm	rake db:migrate
rdbms	rake db:migrate:status
rdbmt	rake db:migrate RAILS_ENV=test
rdbmst	rake db:migrate:status RAILS_ENV=test

Directory Navigation

After using cd once you should be ablet to use z (zoxide) thereafter. z lets you cd to directories given just a partial path. Example:

➜ cd ~/work/proj1
➜ cd
➜ z pro # takes you to ~/work/proj1

Using a devcontainer

Work in progress.

devcontainer build --workspace-folder . --image-name jc_dotfiles:latest
docker ps -a
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . /bin/zsh

To stop/rebuild/restart the devcontainer:

docker ps -a
docker rm jc_dotfiles
devcontainer build --workspace-folder . --image-name jc_dotfiles:latest
devcontainer up --workspace-folder .

Troubleshooting

Common Issues

Homebrew installation fails

• Ensure you have Xcode command line tools: xcode-select --install
• Check internet connection and try again
• On Apple Silicon, ensure Rosetta 2 is installed if needed

Permission denied errors

• Make sure you have write access to your home directory
• Try running with sudo if needed for system-level installations
• Check that /usr/local is writable or use Homebrew's recommended permissions

Shell doesn't switch to zsh

• Manually change shell: chsh -s $(which zsh)
• Restart your terminal application
• Check that zsh is in /etc/shells

Tools not found after installation

• Restart your terminal to reload PATH
• Source your shell config: source ~/.zshenv
• Check Homebrew PATH: echo $PATH | grep brew

Neovim plugins not working

• Run :Lazy sync inside Neovim to update plugins
• Check for LSP errors with :LspInfo
• Ensure required language servers are installed via Mason