Dotfiles (Tom Ryder)
This is my personal repository of configuration files and scripts for $HOME
,
including most of the settings that migrate well between machines.
This repository began as a simple way to share Vim and tmux configuration, but a lot of scripts and shell configuration have been added over time, making it into a personal suite of custom Unix tools.
Installation
$ mkdir -p ~/.local/src
$ git clone https://dev.sanctum.geek.nz/code/dotfiles.git ~/.local/src/dotfiles
$ cd ~/.local/src/dotfiles
$ git submodule init
$ git submodule update
$ make
$ make -n install # Check output carefully
$ make install
For the default all
target, you'll need a POSIX-fearing userland, including
make(1)
and m4(1)
.
The installation Makefile
overwrites things standing in the way of its
installed files without backing them up, so read the output of make -n
install
before running make install
carefully, to make sure you aren't going
to lose anything unexpected. If you're still not sure, install it in
a temporary directory first, so you can explore:
$ tmpdir=$(mktemp -d)
$ make install HOME="$tmpdir"
$ env -i HOME="$tmpdir" TERM="$TERM" "$SHELL" -l
The default install
target will install these targets and all their
dependencies:
install-bin
install-curl
install-ex
install-git
install-gnupg
install-less
install-login-shell
install-man
install-readline
install-vim
The install-login-shell
target looks at your SHELL
environment variable,
and tries to figure out which shell's configuration files to install, falling
back on install-sh
.
The remaining files can be installed with the other install-*
targets. Try
awk -f bin/mftl.awk Makefile
in the project's root directory to see a list.
Configuration
To keep a set of make
targets useful for a specific user or host, you can
list them in a newline-separated file ~/.config/dotfiles/config
, and install
using that with the special install-conf
target. This can include macro
settings for the Makefile
, too:
$ cd
$ cat .config/dotfiles/config
install-bash
install-bin
EMAIL=you@example.com
$ make -C .local/src/dotfiles install-conf
Tools
Configuration is included for:
- Bourne-style POSIX shells, sharing a
.profile
, anENV
file, and some helper functions:- GNU Bash (v3.0 or newer)
- Korn shell (
ksh93
,pdksh
,mksh
) - Z shell
- Abook---curses address book program
- cURL---Command-line tool for transferring data with URL syntax
- Dillo---A lightweight web browser
finger(1)
---User information lookup program- Git---Distributed version control system
- GNU Emacs---Extensible text editor
- GnuPG---GNU Privacy Guard, for private communication and file encryption
- i3---Tiling window manager
- less---Terminal pager
- mpv---Media player
- Mutt---Terminal mail user agent
mysql(1)
---Command-line MySQL client- ncmpcpp---ncurses based MPD client inspired by ncmpc
- Newsboat---Terminal RSS/Atom feed reader
psql(1)
---Command-line PostgreSQL client- Parcellite---clipboard manager for X
- Perl::Critic---static source code analysis engine for Perl
- Perl::Tidy---reformats Perl source code
- Readline---GNU library for user input used by Bash, MySQL, and others
- Subversion---Apache Subversion, a version control system
- tidy---HTML/XHTML linter and tidier
- tmux---Terminal multiplexer similar to GNU Screen
- Vim---Vi IMproved, a text editor
- X11---Windowing system with network transparency for Unix
There is also some slightly customized support for multi-version environment management for three major scripting languages:
The configurations for shells, Mutt, tmux, and Vim are the most likely to be of interest. The i3 configuration is limited mainly to changing window switching key bindings to match Vim's.
Shell
On GNU/Linux, I use Bash; on *BSD, I use some variant of Korn Shell,
preferably ksh93
if it's available.
POSIX core
My ~/.profile
and other files in sh
are written in POSIX shell script, so
they should work in most POSIX-conforming sh(1)
implementations. Please
email me if you find a case where they don't!
Further shell snippets to run on login are sourced from ~/.profile.d
by
~/.profile
. Most of these boil down to exporting variables appropriate to
the system and the software it has available.
Configuration that should be sourced for all conforming interactive shells is
kept in ~/.shrc
, with subscripts read from ~/.shrc.d
. There's
a ~/.shinit
shim to act as ENV
.
GNU Bash
My Bash scripts are written to work with GNU Bash v3.0 or newer. This is why I use older syntax for certain things such as appending items to arrays:
array[${#array[@]}]=$item
This doesn't work for arrays with sparse indices; compare this to the much nicer syntax available since 3.1-alpha1, which does:
array+=("$item")
I do use some features that are only available in versions after v3.0, such as
newer shopt
options like dirspell
, or variables like PROMPT_DIRTRIM
.
These are set only after testing BASH_VERSINFO
appropriately.
Prompt
A terminal session with my prompt looks something like this:
~$ ssh remote
remote:~$ cd .local/src/dotfiles
remote:~/.local/src/dotfiles(master+!)$ git status
M README.md
M bash/bashrc.d/prompt.bash
A init
remote:~/.local/src/dotfiles(master+!)$ foobar
foobar: command not found
remote:~/.local/src/dotfiles(master+!)<127>$ sleep 5 &
[1] 28937
remote:~/.local/src/dotfiles(master+!){1}$
The hostname is elided if not connected via SSH. The working directory with
tilde abbreviation for $HOME
is always shown. The rest of the prompt expands
based on context to include these elements, in this order:
-
Whether in a Git repository if applicable,
-
The current version control branch, tag, or commit/revision if applicable, and punctuation to show repository status including reference to upstreams at a glance. Subversion support can also be enabled, in which case a
git:
orsvn:
prefix is added appropriately for disambiguation. - The number of running background jobs, if non-zero.
- The exit status of the last command, if non-zero.
You can set PROMPT_COLOR
, PROMPT_PREFIX
, and PROMPT_SUFFIX
too, which all
do about what you'd expect.
If you start up GNU Bash, Korn shell, or Z shell, and that doesn't match your login shell, the prompt should display an appropriate prefix.
This is all managed within the prompt
function. There's some mildly hacky
logic on tput
codes included such that it should work correctly for most
common terminals using both termcap(5)
and terminfo(5)
, including *BSD
systems. It's also designed to degrade gracefully for eight-color and no-color
terminals.
Functions
If a function can be written in POSIX sh
without too much hackery, I put it
in sh/shrc.d
to be loaded by any POSIX interactive shell. Those include:
- Four functions for using a "marked" directory, which I find a more manageable
concept than the
pushd
/popd
directory stack:md()
marks a given (or the current) directory.gd()
goes to the marked directory.pmd()
prints the marked directory.xd()
swaps the current and marked directories.
- Ten other directory management and navigation functions:
bd()
changes into a named ancestor of the current directory.gt()
changes into a directory or into a file's directory.lgt()
runsgt()
on the first result from aloc(1df)
search.mkcd()
creates a directory and changes into it.pd()
changes to the argument's parent directory.rd()
replaces the first instance of its first argument with its second argument in$PWD
, emulating a feature of the Zshcd
builtin that I like.scr()
creates a temporary directory and changes into it.sd()
changes into a sibling of the current directory.ud()
changes into an indexed ancestor of a directory.vr()
tries to change to the root directory of a source control repository.
- Two editor wrapper functions:
e()
invokes$EDITOR
, ored(1)
if not set.v()
invokes$VISUAL
, orvi(1)
if not set.
bc()
silences startup messages from GNUbc(1)
.ed()
tries to get verbose error messages, a prompt, and a Readline environment fored(1)
.gdb()
silences startup messages fromgdb(1)
.grep()
tries to apply color and other options good for interactive use if available.hgrep()
allows searching$HISTFILE
.ls()
tries to apply color and other options good for interactive use if available.la()
runsls -A
if it can, orls -a
otherwise.ll()
runsls -Al
if it can, orls -al
otherwise.
path()
manages the contents ofPATH
conveniently.scp()
tries to detect forgotten hostnames inscp(1)
command calls.tor()
is just a terse shortcut for using Torsocks to anonymize TCP connections from the current shell.tree()
colorizes GNUtree(1)
output if possible (without havingLS_COLORS
set).x()
is a one-key shortcut forexec startx
.
There are a few other little tricks defined for other shells providing non-POSIX features, as compatibility allows:
keep()
stores ad-hoc shell functions and variables (Bash, Korn Shell 93, Z shell).prompt()
sets up my interactive prompt (Bash, Korn Shell, Z shell).pushd()
adds a default destination of$HOME
to thepushd
builtin (Bash).vared()
allows interactively editing a variable with Readline, emulating a Z shell function I like by the same name (Bash).ver()
prints the current shell's version information (Bash, Korn Shell, Z shell).
Completion
I find the bash-completion
package a bit too heavy for my tastes, and turn it
off using a stub file installed in ~/.config/bash_completion
. The majority
of the time I just want to complete paths anyway, and this makes for a quicker
startup without a lot of junk functions in my Bash namespace.
I do make some exceptions with completions defined in files in
~/.bash_completion.d
for things I really do get tired of typing repeatedly:
- Bash builtins: commands, help topics, shell options, variables, etc.
find(1)
's more portable optionsgpg(1)
long optionsmake(1)
targets read from aMakefile
man(1)
page titlespass(1)
entriesssh(1)
hostnames from~/.ssh/config
For commands that pretty much always want to operate on text, such as text file or stream editors, I exclude special file types and extensions I know are binary. I don't actually read the file, so this is more of a heuristic thing, and sometimes it will get things wrong.
I also add completions for my own scripts and functions where useful. The completions are dynamically loaded if Bash is version 4.0 or greater. Otherwise, they're all loaded on startup.
Korn shell
These are experimental; they are mostly used to tinker with MirBSD mksh
, AT&T
ksh93
, and OpenBSD pdksh
. All shells in this family default to a yellow
prompt if detected.
Z shell
These are experimental; I do not like Z shell much at the moment. The files
started as a joke (exec bash
). zsh
shells default to having a prompt
colored cyan.
Mutt
My mail is kept in individual Maildir-format directories under ~/mail
, with
the system mail spool in e.g. /var/mail/tejr
being where most unfiltered new
mail is spooled. I use Getmail,
maildrop, and
msmtp; the configurations for these are not
included here. I sign whenever I have some indication that the recipient might
be using a PGP implementation, and I encrypt whenever I have a public key
available for them. The GnuPG and S/MIME interfacing is done with
GPGme, rather than defining
commands for each crypto operation. I wrote an article about this
setup if it sounds
appealing.
You'll need Abook installed if you want to use the query_command
I have
defined, and msmtp for the sendmail
command.
tmux
These are just generally vi-friendly settings, and there isn't much out of the ordinary. Note that the configuration presently uses a hard-coded 256-color color scheme, and uses non-login shells, with an attempt to control the environment to stop shells thinking they have access to an X display.
The shell scripts in bin
include tm(1df)
, a shortcut to make attach
into
the default command if no arguments are given and sessions do already exist.
My ~/.inputrc
file binds Alt+M to run that, and Tmux in turn binds the same
key combination to detach.
Vim
The majority of the Vim configuration is just setting options, with a fair few mappings and remappings, both global and buffer-local. It's extensively commented.
XDG Basedirs
The XDG Base Directory
Specification's
environment variables are checked on startup, and appropriate directories are
added to the start and end of 'runtimepath'
. I use these separate
directories for machine-local configuration, usually in ~/.config/vim
, while
all the files that this suite installs land in ~/.vim
. Backups, swap files,
persistent undo data, saved views, and the viminfo
file all live under
XDG_CACHE_HOME
, normally ~/.cache/vim
.
Filetypes
I define my own filetype.vim
and scripts.vim
, so that filetype detection
works in a way I like, and loads quickly. They are unlikely to suit you as
they are, but if you want to use it, you can extend them with your favorite
filetypes in custom ftdetect
rules.
Plugins
If the logic for doing something involves more than a few lines or any
structures like functions that can be decoupled from $MYVIMRC
, I like to
implement it as a plugin in ~/.vim/plugin
and/or ~/.vim/autoload
, with
documentation for each in ~/.vim/doc
.
They eventually get either discarded if I stop using them, or spun off into
their own repositories and added to this repository as submodules under
vim/bundle
if I don't. Some of them I upload to
vim.org.
Filetype plugins
I apply some replacement or supplementary configuration specific to file types
I often edit in ~/.vim
and ~/.vim/after
, in the ftplugin
, indent
, and
syntax
subdirectories. Some of these filetype plugins or extensions may also
eventually be removed to be separately distributed, and installed via
submodules instead.
Compilers
I define a few of my own :compiler
scripts for ~/.vim/compiler
to check and
lint appropriate filetypes. I bind checking---"does it run?"---and linting---"is
it good?"---with separate local leader maps; for example, for perl
filetypes,
<LocalLeader>c
switches makeprg
to perl -c
for checking, and
<LocalLeader>l
to perlcritic
for linting.
No Neovim support
The configuration doesn't explicitly support Neovim, although most of it will probably work; you would probably just comment out the settings for a few of the removed options.
Scripts
Where practical, I make short scripts into POSIX (but not Bourne) sh(1)
,
awk(1)
, or sed(1)
scripts in ~/.local/bin
. I try to use shell functions
only when I actually need to, which tends to be when I need to change the state
of the user's current shell, or to limit a change in behavior only to
interactive shells.
These scripts are installed by the install-bin
target:
- Three SSH-related scripts:
sls(1df)
prints hostnames read fromssh_config(5)
files. It usesslsf(1df)
to read each one.sra(1df)
runs a command on multiple hosts read fromsls(1df)
and prints output.sta(1df)
runs a command on multiple hosts read fromsls(1df)
and prints the hostname if the command returns zero.
- Five URL-related shortcut scripts:
hurl(1df)
extracts values ofhref
attributes of<a>
tags, sorts them uniquely, and writes them tostdout
; it requires pup.murl(1df)
converts Markdown documents to HTML withpandoc(1)
and runs the output throughhurl(1df)
.urlc(1df)
accepts a list of URLs onstdin
and writes error messages tostderr
if any of the URLs are broken, redirecting, or are insecure and have working secure versions; requirescurl(1)
.urlh(1df)
prints the values for a given HTTP header from a HEAD response.urlmt(1df)
prints the MIME type from theContent-Type
header as retrieved byurlh(1df)
.
- Three RFC-related shortcut scripts:
rfcf(1df)
fetches ASCII RFCs from the IETF website.rfct(1df)
formats ASCII RFCs.rfcr(1df)
does both, displaying in a pager if appropriate, like aman(1)
reader for RFCs.
- Five toy random-number scripts (not for sensitive/dead-serious use):
rndi(1df)
gets a random integer within two bounds.rnds(1df)
attempts to get an optional random seed forrndi(1df)
.rnda(1df)
usesrndi(1df)
to choose a random argument.rndf(1df)
usesrnda(1df)
to choose a random file from a directory.rndl(1df)
usesrndi(1df)
to choose a random line from files.
- Four file formatting scripts:
d2u(1df)
converts DOS line endings in files to UNIX ones.u2d(1df)
converts UNIX line endings in files to DOS ones.stbl(1df)
strips a trailing blank line from the files in its arguments.stws(1df)
strips trailing spaces from the ends of lines of the files in its arguments.
- Seven stream formatting scripts:
sd2u(1df)
converts DOS line endings in streams to UNIX ones.su2d(1df)
converts UNIX line endings in streams to DOS ones.slow(1df)
converts uppercase to lowercase.supp(1df)
converts lowercase to uppercase.tl(1df)
tags input lines with a prefix or suffix, basically ased(1)
shortcut.tlcs(1df)
executes a command and usestl(1df)
to tag standard output and standard error lines, and color them if you want.unf(1df)
joins lines with leading spaces to the previous line. Intended for unfolding HTTP headers, but it should work for most RFC 822 formats.
- Six simple aggregate scripts for numbers:
max(1df)
prints the maximum.mean(1df)
prints the mean.med(1df)
prints the median.min(1df)
prints the minimum.mode(1df)
prints the first encountered mode.tot(1df)
totals the set.
- Three quick-and-dirty HTML tools:
htenc(1df)
encodes.htdec(1df)
decodes.htrec(1df)
wrapsa
tags around URLs.
- Two internet message quoting tools:
quo(1df)
indents with quoting right angle-brackets.wro(1df)
adds a quote attribution header to its input.
- Six Git-related tools:
fgscr(1df)
finds Git repositories in a directory root and scrubs them withgscr(1df)
.grc(1df)
quietly tests whether the given directory appears to be a Git repository with pending changes.gscr(1df)
scrubs Git repositories.isgr(1df)
quietly tests whether the given directory appears to be a Git repository.jfc(1df)
adds and commits lazily to a Git repository.jfcd(1df)
watches a directory for changes and runsjfc(1df)
if it sees any.
- Two time duration functions:
hms(1df)
converts seconds tohh:mm:ss
ormm:ss
timestamps.sec(1df)
convertshh:mm:ss
ormm:ss
timestamps to seconds.
- Three pipe interaction tools:
pst(1df)
runs an interactive program on data before passing it along a pipeline.ped(1df)
runspst(1df)
with$EDITOR
ored(1)
.pvi(1df)
runspvi(1df)
with$VISUAL
orvi(1)
.
- Two editor wrapper tools:
mked(1df)
creates paths to all its arguments before invoking$EDITOR
.mkvi(1df)
creates paths to all its arguments before invoking$VISUAL
.
ap(1df)
reads arguments for a given command from the standard input, prompting if appropriate.apf(1df)
inserts arguments to a command with ones read from a file, intended as a framework for shell wrappers or functions.ax(1df)
evaluates an AWK expression given on the command line; this is intended as a quick way to test how AWK would interpret a given expression.bcq(1df)
runsbc(1)
, quieting it down if need be.bel(1df)
prints a terminal bell character.bl(1df)
generates a given number of blank lines.bp(1df)
runsbr(1df)
after prompting for an URL.br(1df)
launches$BROWSER
.ca(1df)
prints a count of its given arguments.cf(1df)
prints a count of entries in a given directory.cfr(1df)
does the same ascf(1df)
, but recurses into subdirectories as well.chc(1df)
caches the output of a command.chn(1df)
runs a filter over its input a given number of times.clog(1df)
is a tiny timestamped log system.clrd(1df)
sets up a per-line file read, clearing the screen first.clwr(1df)
sets up a per-line file write, clearing the screen before each line.csmw(1df)
prints an English list of monospace-quoted words read from the input.dam(1df)
buffers all its input before emitting it as output.ddup(1df)
removes duplicate lines from unsorted input.defang(1df)
prevents dangerous URLs from being made into clickable links.dub(1df)
lists the biggest entries in a directory.edda(1df)
provides a means to runed(1)
over a set of files preserving any options, mostly useful for scripts.eds(1df)
edits executable script files inEDSPATH
, defaulting to~/.local/bin
, for personal scripting snippets.exm(1df)
works around a screen-clearing quirk of Vim'sex
mode.finc(1df)
counts the number of results returned from a set of givenfind(1)
conditions.fnl(1df)
runs a command and saves its output and error into temporary files, printing their paths and line counts.fnp(1df)
prints the given files to standard output, each with a plain text heading with the filename in it.gms(1df)
runs a set ofgetmailrc
files; does much the same thing as the scriptgetmails
in thegetmail
suite, but runs the requests in parallel and does up to three silent retries usingtry(1df)
.grec(1df)
is a more logically-namedgrep -c
.gred(1df)
is a more logically-namedgrep -v
.gwp(1df)
searches for alphanumeric words in a similar way togrep(1)
.han(1df)
provides akeywordprg
for Vim's Bash script file type that will look forhelp
topics. You could use it from the shell too.igex(1df)
wraps around a command to allow you to ignore error conditions that don't actually worry you, exiting with 0 anyway.jfp(1df)
prints its input, excluding any shebang on the first line only.loc(1df)
is a quick-search wrapped aroundfind(1)
.maybe(1df)
is liketrue(1)
orfalse(1)
; given a probability of success, it exits with success or failure. Good for quick tests.mex(1df)
makes given filenames in$PATH
executable.mi5(1df)
is a crude preprocessor form4
.mim(1df)
starts an interactive Mutt message with its input.mftl(1df)
finds usable-looking targets in Makefiles.mkcp(1df)
creates a directory and copies preceding arguments into it.mkmv(1df)
creates a directory and moves preceding arguments into it.motd(1df)
shows the system MOTD.msc(1df)
crudely counts messages in an mbox.mw(1df)
prints alphabetic space-delimited words from the input one per line.oii(1df)
runs a command on input only if there is any.onl(1df)
crunches input down to one printable line.osc(1df)
implements anetcat(1)
-like wrapper foropenssl(1)
'ss_client
sub-command.p(1df)
prints concatenated standard input;cat(1)
as it should always have been.pa(1df)
prints its arguments, one per line.phpcsff(1df)
wraps around PHP-CS-Fixer to make it a source code filter suitable for use as anequalprg
in Vim.pp(1df)
prints the full path of each argument using$PWD
.pph(1df)
runspp(1df)
and includes a leading$HOSTNAME:
.paz(1df)
print its arguments terminated by NULL chars.pit(1df)
runs its input through a pager if its standard output looks like a terminal.pwg(1df)
generates just one decent password withpwgen(1)
.qat(1df)
disablesstty echo
for the duration of a paste.rep(1df)
repeats a command a given number of times.rgl(1df)
is a very crude interactivegrep(1)
loop.shb(1df)
attempts to build shebang lines for scripts from the system paths.sqs(1df)
chops off query strings from filenames, usually downloads.sshi(1df)
prints human-readable SSH connection details.stex(1df)
strips extensions from filenames.sue(8df)
execssudoedit(8)
as the owner of all the file arguments given, perhaps in cases where you may not necessarily haveroot
sudo(8)
privileges.swr(1df)
allows you to run commands locally specifying remote files inscp(1)
's HOST:PATH format.td(1df)
manages a to-do file for you with$EDITOR
andgit(1)
; I used to use Taskwarrior, but found it too complex and buggy.tm(1df)
runstmux(1)
withattach-session -d
if a session exists, andnew-session
if it doesn't.trs(1df)
replaces strings (not regular expression) in its input.try(1df)
repeats a command up to a given number of times until it succeeds, only printing error output if all three attempts failed. Good for tolerating blips or temporary failures incron(8)
scripts.umake(1df)
iterates upwards through the directory tree from$PWD
until it finds a Makefile for which to runmake(1)
with the given arguments.uts(1df)
gets the current UNIX timestamp in an unorthodox way that should work on all POSIX-compliant operating systems.vest(1df)
runstest(1)
but fails with explicit output viavex(1df)
.vex(1df)
runs a command and printstrue
orfalse
explicitly tostdout
based on the exit value.vic(1df)
tries to run a POSIX-compliantvi(1)
.xrbg(1df)
applies the same randomly-selected background to each X screen.xrq(1df)
gets the values of specific resources out ofxrdb -query
output.
There's some silly stuff in install-games
:
aaf(6df)
gets a random ASCII Art Farts comic.acq(6df)
allows you to interrogate AC, the interplanetary computer.aesth(6df)
converts English letters to their full width CJK analogues, for aesthetic purposes.squ(6df)
makes a reduced Latin square out of each line of input.kvlt(6df)
translates input to emulate a style of typing unique to black metal communities on the internet.philsay(6df)
shows a picture to accompanypks(6df)
output.pks(6df)
laughs at a randomly selected word.rndn(6df)
implements an esoteric random number generation algorithm.strik(6df)
outputs s̶t̶r̶i̶k̶e̶d̶ ̶o̶u̶t̶ struck out text.rot13(6df)
rotates the Latin letters in its input.uuu(6df)
uuuuu uuuu uu uuuuuu uuuuuuu u uuu uuuuu.xyzzy(6df)
teleports to a marked location on the filesystem.zs(6df)
prefixes "z" case-appropriately to every occurrence of "s" in the text on its standard input.
Manuals
The install-bin
and install-games
targets install manuals for each script.
If you want to read the manuals, you may need to add ~/.local/share/man
to
your ~/.manpath
or /etc/manpath
configuration, depending on your system.
Testing
You can check that both sets of shell scripts are syntactically correct with
make check-bash
or make check-sh
, or make check
for everything including
the scripts in bin
and games
. There's no proper test suite for the actual
functionality (yet).
There are also optional lint
targets, if you have the appropriate tools
available to run them:
- ShellCheck:
lint-bash
lint-bin
lint-games
lint-ksh
lint-sh
lint-x
- Vint:
lint-vim
Future development
See IDEAS.md.
Known issues
See ISSUES.md.
License
Public domain; see the included UNLICENSE
file. It's just configuration and
simple scripts, so do whatever you like with it if any of it's useful to you.
If you're feeling generous, please join and/or donate to a free software
advocacy group, and let me know you did it because of this project: