weikinhuang's dotfiles

My $SHELL, mostly bash, works everywhere, *nix, osx, wsl.

Installation

The bootstrap script will create symlinks in the home directory to the proper files. The script will also create *.bak files for backups of existing files.

Install dotfiles with auto bootstrap

This will by default install dotfiles in the home directory with all options enabled

curl https://raw.githubusercontent.com/weikinhuang/dotfiles/master/bootstrap.sh | bash

# Additional arguments can be passed to the bootstrap script
curl https://raw.github...master/bootstrap.sh | bash -s -- [args]

Install dotfiles with Git

You can clone the repository wherever you want, the home (~/) directory is recommended.

When the git repo is updated, the files will be automatically updated when the session is restarted.

# args can be passed to the bootstrap script
git clone https://github.com/weikinhuang/dotfiles.git ~/.dotfiles && ~/.dotfiles/bootstrap.sh

To update later on, just run git pull in ~/.dotfiles.

Install dotfiles without Git

To install or update without git installed, run:

cd; mkdir -p ~/.dotfiles \
  && curl -#L https://github.com/weikinhuang/dotfiles/tarball/master \
    | tar -C ~/.dotfiles -xzv --strip-components 1 \
  && ~/.dotfiles/bootstrap.sh

bootstrap.sh args

| Arg | Description | | ------------ | ----------------------------------- | | --dir PATH | Change the install directory | | --no-git | Skip setting up .gitconfig | | --no-vim | Skip setting up .vimrc and .vim |

Reference for aliases, functions, and changes

See REFERENCE.md for all added commands, overrides, and changes to built-ins.

High level overview

• cd -- list last 10 traversed directories
• chpwd, precmd, and preexec hooks with similar behavior to Zsh
• sudo works on aliases
• rm cp mv are always interactive -i (use -f to override)
• ls and grep always has color (use --color=never to override)
• which command expands full path when possible
• less does not clear the screen upon exit and process colors (with options -XR)
• gdiff uses git's diff command with color when possible
• pbcopy and pbpaste for cross-platform copy/paste from cli, and optionally over ssh
• open for cross-platform open in native application
• chattr, mklink, is-elevated-session, winstart, winsudo WSL tools

The Bash Prompt

See PROMPT.md for configuration options.

Configuration Options

To use these variables, export them to ~/.bash_local.

# EXAMPLE
export DOT_AUTOLOAD_SSH_AGENT=1

| exported ENV var | Default | Description | | ---------------------------------- | ------: | ------------------------------------------------------------------------------------------------------------------------------------------------ | | DOT_AUTOLOAD_SSH_AGENT | UNSET | Automatically start up ssh-agent when starting a new shell, or reuse any existing agent instances | | DOT_BASH_RESOLVE_PATHS | UNSET | Set bash option set -o physical to not resolve symlink paths | | DOT_DISABLE_PREEXEC | UNSET | Disables loading bash-preexec.sh functionality. This is needed for some bash prompt functionality. | | DOT_DISABLE_PS1 | UNSET | Disables the custom bash prompt | | DOT_INCLUDE_BREW_PATH | UNSET | Use to homebrew utilities without the g prefix (OSX) | | DOT_INCLUDE_BUILTIN_PLUGINS | UNSET | Loads files in dotfiles/plugins. This is needed for some bash prompt functionality. | | DOT_SOLARIZED_DARK | UNSET | Use to tell common commands to use solarized dark (ex. LS_COLORS, vim) colors | | DOT_SOLARIZED_LIGHT | UNSET | Use to tell common commands to use solarized light (ex. LS_COLORS, vim) colors | | DOT_GIT_PROMPT_CACHE_TTL_MS | 1000 | Milliseconds to serve a cached git prompt without re-checking (per-PWD TTL) | | DOT_GIT_PROMPT_CACHE_MAX_AGE_MS | 10000 | Maximum milliseconds to serve a stale git prompt cache before forcing a refresh | | DOT_GIT_PROMPT_INVALIDATE_ON_GIT | 1 | Set to 0 to disable automatic cache invalidation after git commands |

Custom hook points

~/.bash_local

If ~/.bash_local exists, it will be sourced before the built-ins are sourced. Env vars, configuration vars, and hooks can be placed in this file.

~/.bash_local.d/*.sh

All files ending with .sh located in ~/.bash_local.d will be loaded right after ~/.bash_local, this is a good place to put include scripts that setup additional environments in separate files.

.gitconfig.local

If a file ~/.gitconfig.local exists, it will be sourced in addition to the built in git settings. Configurations in this file will be set with the highest priority.

Plugins

Plugins are scripts that are loaded near the end of the dotfiles initialization process. They usually contain hooks, setup, or configuration for external programs.

See the plugins/ directory for the built-in examples.

Plugins are also loaded from ~/.bash_local.d/ with any file ending in .plugin. Sorting is preserved via the combination of both directories.

Example plugin for direnv:

# check if direnv exists
if ! command -v direnv &>/dev/null; then
  return
fi
# load direnv program hook
source <(direnv hook bash 2>/dev/null)

Specific plugins can be disabled with an environment variable: DOT_PLUGIN_DISABLE_${PLUGIN_FILE_NAME}.

Example disable direnv hook:

export DOT_PLUGIN_DISABLE_direnv=1

Hooks

Hooks are available before and after each part of the dotfiles repo is loaded. This allows for customization between steps or overrides at point in time loading. They should be declared in ~/.bash_local or ~/.bash_local.d/*.sh so that they are available by the time the dotfiles are loaded.

Hook points are available before and after the following steps:

• aliases
• completion
• env
• exports
• extra
• functions
• plugins
• prompt

They can be declared as either a single function dotfiles_hook_${HOOK}_{pre,post} or pushed into the arrays dotfiles_hook_${HOOK}_{pre,post}_functions.

Example

# add a hook to run before the "functions" segment is loaded
function dotfiles_hook_functions_pre() {
    echo "I'm loading before functions"
    export FOO=123
}

# add a hook to run after the "alias" segment is loaded
function foobar() {
    echo "I'm loading after aliases"
    alias curl-help="curl --help"
}
# append to array
dotfiles_hook_alias_post_functions+=(foobar)

WSL configuration

Setup and configuration of Window's WSL is documented in utils/wsl/README.md.

Development

You can try out this repo in docker easily to test your plugins or hooks.

$ docker run -it --rm -v "$(pwd):/root/.dotfiles:ro" -v "$HOME/.bash_local:/root/.bash_local:ro" -v "$HOME/.bash_local.d:/root/.bash_local.d:ro" -v "$(pwd)/dev/docker-entrypoint.sh:/docker-entrypoint.sh:ro" --entrypoint /docker-entrypoint.sh bash:latest bash
# OR with overrides set locally in the dotfiles repo
mkdir -p bash_local_d_sample
touch bash_local_d_sample/bash_local
$ docker run -it --rm -v "$(pwd):/root/.dotfiles:ro" -v "$(pwd)/bash_local_d_sample/bash_local:/root/.bash_local:ro" -v "$(pwd)/bash_local_d_sample:/root/.bash_local.d:ro" -v "$(pwd)/dev/docker-entrypoint.sh:/docker-entrypoint.sh:ro" -v "$(pwd)/bash_local_d_sample/.bash_history:/root/.bash_history" --entrypoint /docker-entrypoint.sh bash:latest bash

# in the docker shell
$ (cd ~ && .dotfiles/bootstrap.sh)
# install any dependencies you might need, ex.
$ apk add --no-cache coreutils curl git tar nodejs

# start a new shell with the dotfiles loaded, to reload, exit this shell and run this command again
$ env -i PS1=1 TERM="$TERM" PATH="$PATH" HOME="$HOME" SHELL="$SHELL" bash -l
$ CTRL+d
$ env -i PS1=1 TERM="$TERM" PATH="$PATH" HOME="$HOME" SHELL="$SHELL" bash -l
...

Brewfile

A Brewfile is included for declaratively managing core Homebrew packages on macOS. Install with:

brew bundle --file=~/.dotfiles/Brewfile

Linting

shellcheck and shfmt are used to ensure consistency of the scripts in this repo. Files in external/ are excluded since they are third-party. .bats tests are also checked with ShellCheck using its Bats parser.

Validate the codebase locally:

$ ./dev/lint.sh
OK

Layout

Each layout folder contains the following files

| File | Description | | ------------ | ---------------------------------