Start here

A couple of preliminary things to get out of the way:

  • Everything is driven by setup.sh. When in doubt, consult that file.

  • Everything here is simply a convenience to make life easier setting up a new machine. Since I spent the work figuring this out, I might as well make it available to others.

  • All steps are optional though there are some dependencies and assumptions which are noted as they come up.

Details

For example:

  • There are some common fixes for things like backspace in vim not working in tmux, spaces instead of tabs for Python code, getting the mouse to work in vim and tmux, and so on.

  • To avoid visiting each tool’s homepage, downloading for Linux or Mac, and following the particular installation instructions, you can instead use the --install-<toolname> commands.

  • The --vim-diffs commands help figure out if all your dotfiles on a particular machine are up-to-date with this repo.

  • A centrally available resource for setup and configuration means there’s only one place to look for updates.

0: Download and check

  • Download the latest zip file

  • Unzip it and go to the unzipped directory in your terminal

  • Run ./setup.sh to see the help.

Tip

Are you setting up a recent Mac? The default shell is zsh which may cause issues. See zsh to bash for how to change it back to bash.

1. Copy over dotfiles

There are two paths to take here:

Option 1: start fresh

  • Are you setting up a new machine?

  • Have you made a backup of your files and want to try these out?

  • Do you want the “batteries included” experience?

Then you should probably start fresh. Do this to create or overwrite existing files, and then close your terminal and reopen it to use the new configuration:

# START FRESH....

./setup.sh --dotfiles

# then close your terminal and re-open
Details

Details

The ./setup.sh --dotfiles command copies all dotfiles over to your home directory, making a backup of any existing files in case you want to roll back. The list of files copied can be found in include.file.

It’s important to close and then reopen your terminal so that your terminal will load all the new configuration.

Option 2: update existing

Do this if you already have your own files.

# UPDATE EXISTING...

./setup.sh --vim-diffs

# use standard vim diff operations, e.g.
# ]c, do, dp, :qa

The remainder of this documentation will assume you’re starting fresh.

2: Setup vim & conda

2a: Set a patched terminal font

  • Manually download and install your favorite font from nerdfonts.com. This needs to be done on your local machine.

  • Install by double-clicking the .ttf files. On Mac, for example, this will open the font manager, where you can click the “Install” button.

  • Change your terminal program’s preferences to use the new font. You’re looking for a font that includes “Nerd Font”. Using Terminal on Mac? You’ll also need to set the same font for non-ASCII characters.

Details

Without a patched font, you’ll get question mark symbols showing up in many places in nvim. That’s because many of the plugins expect fonts with additional glyphs.

Do this on the machine running the terminal app because that’s the program displaying all the text. This is almost always your local machine. For example, even if you’re setting up dotfiles on a remote cluster, the font should not be installed there. It should be installed on the laptop you’re using to connect to that cluster.

In this gif, you can see arrow shapes for buffers, line number glyphs, and so on. To get these, you need a patched font, and your terminal needs to be set to use the font.

Skip this step if you don’t want those.

2b: neovim

Do this if you want to use neovim. See Why? for more help on deciding.

./setup.sh --install-neovim

# then close and reopen your terminal
Details

This installs Neovim to ~/opt/bin, and then creates an alias vim=nvim in the ~/.aliases file (which is sourced by ~/.bashrc). This way, whenever you call vim, the alias will redirect it to nvim.

However it’s important to close and reopen your terminal, because this alias is conditional on finding nvim, and the alias is only created upon first starting bash.

If you want to use actual vim, provide the full path when calling it. For example, on many machines it’s at /usr/bin/vim.

2c: neovim plugin setup

Note

Have you used these dotfiles before? In Oct 2023, the nvim configuration changed. Please see Migrating to Neovim Lua config for more context, rationale, and details on migrating to this new config method.

Plugins are managed via the lazy.nvim manager. Simply opening neovim should be sufficient to trigger lazy.nvim to bootstrap itself and then download, install, and configure plugins automatically.

Or you can run this command to have it quit automatically when it’s done:

# this will open nvim, install plugins, and quit when done
nvim +"lua require('lazy').restore({wait=true})" +q
Details

lazy.nvim will show progress downloading plugins. Treesitter will also automatically install parsers, so you should watch the log on the bottom and wait until everything settles down. Then you can quit as normal with <Esc>:q.

If running nvim didn’t work, check that it’s on your path. Close and then reopen your terminal just to make sure. If you installed with ./.setup.sh --install-neovim, it put it in ~/opt/bin/nvim. Make sure that directory is on your PATH by checking:

echo $PATH

2d: conda

conda is a cross-platform, language-agnostic package manager. It’s by far the best way to get set up with Python, but it also works for many other languages. See conda for some details on how to activate environments.

./setup.sh --install-conda
./setup.sh --set-up-bioconda

Warning

Are you on a Mac with an M1 or M2 chip? You will not be able to install packages from Bioconda because packages are not built yet for the Apple Silicon architecture.

Details

First, this downloads the latest version of Mambaforge, and installs conda and mamba into ~/mambaforge/condabin.

Then it adds the line export PATH="$PATH:~/mambaforge/condabin" to the ~/.path (which you can read more about at Bash dotfiles).

If you happen to be on NIH’s Biowulf cluster where the home directory is too small to support the installation, this will auto-detect that and install instead to /data/$USER/mambaforge/condabin and add the line export PATH="$PATH:~/data/$USER/mambaforge/condabin to the ~/.path

Finally, ./setup.sh --set-up-bioconda sets up the bioconda and conda-forge channels in the right way as documented by Bioconda.

3: Installing programs

The setup.sh script has many commands for installing various tools I find useful. These warrant their own section, so continue to Additional tool installations for descriptions of tools and the commands to install them.