This Repo makes use of Dotbare (see below) to bootstrap the setup of a new environment with my personal config. Some highlights of what this does, which is not an exhaustive list:
- ZSH shell with Oh-My-Zsh as the baseline, plus several useful plugins
- EverVim as the base Vim configuration (see link below for more info on what this provides)
- Support for NeoVim
- A wide array of customizations that turn Vim into a modern IDE with code completion, LSP support, simple code navigation, etc. across a wide number of languages
- Vimwiki: A wiki built into Vim, using Markdown as the language to write it in. This means you can make your wiki into a Wiki on GitHub just by adding all the files in the wiki directory to a new github repo (or to the wiki section of any existing repo). Now you can write your wikidocs about your project in the same place you write the code!
- Some good html styling for turning your Vimwiki into static HTML if you wish
- FZF integration across both zsh and vim
- A great LS_COLORS scheme to make terminal sessions much easier to read (covers *nix/Mac/PC)
- Using Dotbare allows you to sync changes from any machine that this repo is installed on.
I have tried to make as much of this functionality work out of the box as possible. However, this config requires that you have the following already installed (TBD: a script to automatically install all of these for you). It is important to have these installed before you use dotbare to load the custom configuration files in this repo! If not, the setup scripts for the programs below will overwrite the dotfiles.
- Dotbare: This is used to bootstrap this repo and put everything in the proper place.
- Zsh: ZSH shell (On Mac, this is the default shell so no need to install)
- OhMyZsh: Zsh customization & plugins
- EverVim: Vim distro prepackaged with several customizations & plugins. NOTE: if you get errors installing this with NeoVim, delete .Evervim and .Evervim.vimrc and try reinstalling with Vim. You can then use NeoVim as normal.
- Git: You probably wouldn't be reading this right now if you aren't already using Git.
If using NeoVim, the following NeoVim-only packages will be automatically installed:
- Conqueror of Completion (COC): Code completion & language server
- Vista: Better replacement for TagBar in Vim (this is almost essential for any Typescript development; even with the updated .ctags files in this repo, Tagbar doesn't work well for .ts and .tsx files)
If you can't install/don't want to use NeoVim then instead you will use:
- YouCompleteMe: Code completion engine.
Se installation instructions below for how to switch to YouCompleteMe if using Vim.
In most cases you can install these programs manually either before or after using dotbare to update your dotfiles. However if you plan to use NeoVim (which you probably should), it is strongly recommended to install that now. Vim and NeoVim store things such as edit history differently, so you end up having to do a lot of manual cleanup if you want to switch later on.
- NeoVim. Highly Recommended. A much more modern implementation of
Vim with many more plugins available. If installed, also use the following NeoVim-specific plugins:
- pynvim: Supports many NeoVim-only plugins.
- Vimwiki Markdown: Convert Vimwiki to HTML
- Dark VimWiki Template: Template for Vimwiki HTML formatting. Download the files in the repo - they will be used in the installation below.
- GNU [email protected]:jreichert/dotfiles.gitoreutils: Better version of core Unix utilities.
These are probably pre-installed on Linux machines; on Macs you need to install them with
brew install coreutils. - The Silver Searcher: fast drop-in replacement for ack
- chafa: terminal-based image viewer
- fzf: fuzzy find engine
- fd: fast replacement for find (integrates seamlessly with fzf)
- bat: replacement for cat with code highlighting, integration with fzf, and more
- bat-extras: extend functionality of bat to apply to pdfs, word docs, etc., as well as integration with grep, man, and more
- poppler: pdf rendering tools. Used with bat-extras to display pdfs on the command line. Can be installed via homebrew
- lesspipe: like batpipe this extends the functionality of
less to read different doc types. If bat-extras is installed this is mostly superfluous,
however it does add a useful shell tab completion where you can list all the files inside an
archive as you are typing it (ex:
bat myzipfile.zip<TAB>brings up somebinary.exe and readme.txt; now you can use tab completion to make thatbat myzipfile.zip/readme.txt)) - universal-ctags: creates tags used by vim for code navigation (may work with exuberant ctags but unsure)
- LS COLORS PROFILE: a good set of custom colors for use with LS. Note that these dotfiles will already make ZSH use that color scheme; you only need this repo if you want to modify anything.
- asdf: The best multi-language version manager
- git-delta: easier to understand command line diffs
- DiffMerge: Git diff/merge tool (however see note below if you do not install it)
These programs have shortcuts you can read about in .zshrc. Only install them if you need them (nothing will break if you don't).
-
Install all of the prerequisites above. For now you must do this manually; in the future I hope to have a script to automate the process.
-
Install dotbare according to the way you wish to manage package installation. See (https://github.com/kazhala/dotbare#install) for details.
-
Add the following two variables to your .zshrc file:
export DOTBARE_DIR="$HOME/.dotbare"
export DOTBARE_TREE="$HOME"-
Install everything in this repo to the new environment with:
dotbare finit -u [url of this repo] -
In .zshrc, find the line with all of the plugins it will install. Manually install each one or remove the ones you don't need.
-
Also in .zshrc, replace $HOME and $EMAIL with your information. This is used for Git and elsewhere.
-
EverVim uses Vim Plug as its plugin manager. To install the plugins included here, open a vim session and type the following two commands in normal mode:
:PlugInstall:PlugClean!
- Only needed if using Vim instead of NeoVim: Open .EverVim.bundles and comment or uncomment plugins according to the directions in that file.
After following the instructions above, everything should work out of the box. Any further configuration is optional. Changes to ZSH functionality is controlled through .zshrc as normal.
Vim functionality, however, is controlled by .EverVim.vimrc and .EverVim.vimrc.after (the difference between the two .vimrc files is for things that should load either before or after EverVim sets up all its plugins, key mappings, etc. - basically if you want to override anything in EverVim's settings, put in in the .after file). See the next section for details.
The default setup in .EverVim.bundles assumes that you have installed NeoVim; if you weren't able to do that, you will need to manually edit that file to comment/uncomment code to get rid of plugins that only work with NeoVim and replace them with their Vim equivalents.
With the rare exception of some plugin configuration variables (see next paragraph), all Vim customization should be added to .Evervim.vimrc. Standard .vimrc is not read by EverVim! If using NeoVim then you can make updates as usual to ~/.config/init.vim; however note that installing the files in this repo will overwrite your existing one. So if you wish to keep anything from your existing NeoVim config, copy it before installing this!
Most configuration for Vim can be handled by updating .Evervim.vimrc as you
would normally do with a .vimrc file. However, all of this configuration is
loaded before EverVim performs its own setup - meaning that it may override
some values you have set in .EverVim.vimrc. If setting a variable in that file
doesn't seem to work, that is probably the reason why (you can check for this
explicitly by adding your variable to .EverVim.vimrc and then in a vim session
type :echo <variable> - if the value isn't what you set, then EverVim has
hijacked it).
EverVim does not supply a way to override this behavior, so I have added the file .EverVim.vimrc.after to this project. Any variables added here will take precedence over the values that EverVim has set. In general it's a good idea to keep most of your configuration in .EverVim.vimrc so it's all in one place; only add variables here that need to be here.
The current configuration uses the Dark Vimwiki HTML
Template. In order for
this to work, after the wiki is generated you need to manually copy the
contents of the wiki_html folder to ~/Downloads/vimwiki_html (or wherever
you have configured your vimwiki files to live if you changed that).
Vimwiki is configured in .Evervim.vimrc. If you wish to change the path
where the vimwiki files are located or disable/change this template, you can do
so there.
This config is set up to use DiffMerge as its tool for both Git Diffs and Git merges. If it is installed locally then following the instructions above will configure this as well. If this is not the desired tool, then .gitconfig can be modified accordingly.
Almost everything here should work from a remote terminal session except for
using DiffMerge since it's a graphical tool. In that case, you still have the
option of using vimdiff, which is built in to vim: gdtlvim <file1> <file2>
for diffing, and gmtlvim for merging.
Several customizations have been made to .zshrc and .Evervim.vimrc; those two files are well commented and should indicate all of the existing customizations. Here are a few important ones:
- Vim plus the slew of plugins here add a tremendous number of shortcuts.
Making things more complex, the available shortcuts may change depending on what is going on in your current Vim session. I have added theListShortcutscommand which will open a new vsplit that displays all of the currently available shortcuts plus the location where it is set from (in case you want to make any modifications). For further convenience, you can pull this up at any time by typing<leader>sh. - Vim's built-in pager is terrible, and there isn't a way to change it. When
a Vim command returns a long list, this means there isn't a way to use
lessto search the contents. Instead of running your command directly, you can run:Redir <command>and the output will be displayed in a new vsplit. - The vim-startify plugin adds a
useful start page that is shown when simply typing
vim. In addition to the out-of-the-box functionality, it has been modified to show any files that were bookmarked in NERDTree, and any uncommited/untracked files in the current git project. The docs at the plugin wiki show how to create any other customizations you'd like. - vimwiki files are saved in
$HOME/Documents, as this will automatically sync their contents across all your Macs if you use iCloud sharing (and it's a dir that exists on Linux and Windows as well). You can change this in .Evervim.vimrc. - Support for
.tsxTypescript files has been added to Tagbar. However if NeoVim is available, the Vista plugin is far superior for TS development. - bat is an amazing replacement for cat. It adds line numbering, syntax highlighting, navigation and more.
- fzf is incredibly powerful, both for shell integration as well as inside Vim. There are many tutorials for it available online. It uses bat for file previews if bat is installed.
dotbare automatically tracks any changes to files that are already included in this repo. After you
have made any changes, you can push them using normal git syntax (git add, commit, push, etc.) just
by typing dotbare instead of git (ex: dotbare add .gitconfig). Adding new dotfiles is
usually as simple as doing dotbare add [filename], however see caveats below about adding files
that live inside of their own git repos (such as 3rd party customizations you download).
- Dotbare is a fairly simplistic tool, which is both good and bad. It is very easy to use and manage, but it also does't have a lot of features such as allowing for different dotfile profiles to be conditionally installed. A more complex setup could use a tool like Chezmoi instead.
- Under the hood, Dotbare (and most similar tools) use Github repos for maintaining dotfile versioning and easy deployment to different machiness. This uses a common pattern of creating a 'bare' git repo on your machine that tracks everything under $HOME that you explicitly add (ignoring any other files in your home directory). While this is a great pattern that removes the need to do complex symlinking of files all over the place, it comes with the unfortunate side effect that any files you want to track inside git modules that you have checked out in your $HOME directory can't be easily added to this repo (since git sees them as belonging to a different repo). See below for a workaround.
In some public Git projects, the instructions basically say "check out this module, then modify file XZY to your needs" (EverVim does this all over the place, since you need to customize it the same way you would customize any Vim setup). However this prevents you from checking just those changes into GitHub; git won't allow you to check them in individually (since it sees them as belonging to the repo under which the files exist), and you can't add them as submodules unless you want to add the whole project as a submodule.
While there may be some elegant submodule-based approach for handling this, I haven't yet been able to figure it out. Consequently, the steps below will show you how to check in any such files that aren't already in this repo.
It isn't always obvious that this is the case, as modules contain submodules contain submodules
contain turtles all the way down. What will happen is you will try to add a file to the repo with
dotbare, and then when you run dotbare status you won't see the file show up as staged (you didn't
get any error messages when you tried to add it, though). This most likely means the file is
'protected' by being inside an existing git project.
Before doing this, be aware that the steps below remove any of the git modules in question from being able to track their origins! This means you can't pull updates, nor can you write any changes to the remote repo. If you really need to do this in the future, you can temporarily reverse the steps below, pull changes, and then repeate them.
- Look at every folder in the directory tree leading up to the file in question.
- At each level, move any
.gitfolder to.not-git. - At each level, move any
.gitignoreto.gitignore.old. - Finally, add the file to this repo with
dotbare add [filename]. It should now work.
- Figure out how to automatically export color presets from iTerm
ctags and the Vim Tagbar plugin have poor support for .tsx files. Installing this package should make this work better with no additional configuration required. This gist was used as reference for the ctags customization in /.ctags.d/: https://gist.github.com/romgrk/