Sharingan #1: Tim Pope's Dotfiles - Scripts Organization

Tim Pope is nothing less than a hero in the Vim community. He has authored many revered Vim plugins which can be found on his GitHub page. On GitHub he also has a repository to house his dotfiles (linux hidden configuration files, e.g., ~/.bashrc). The description of the repository reads, "tpope's dotfiles. here be dragons" and indeed there are. This is the first post in a series where I will go over some of the interesting code in this repository to give an idea of how it works and try to highlight useful features, workflows, programs, etc. therein. Each post will be given a descriptive subtitle so that readers can skip over content they're not interested in. I recommend cloning the repository to follow along.

The Motherfile

In .local/bin/tpope there is a file which houses functions for various utilites and, in some cases, kicks off other subscripts. The result is a command with subcommands that can be called like git subcommands, e.g. git commit vs tpope config. This structure is handy because it effectively allows us to namespace all of our custom scripts, in this case under the name 'tpope', so we don't have to worry about conflicting with other programs in the $PATH and can therefore freely add our own custom stuff as needed.

The guts of the file are basically what you would expect. There is a big case statement that starts on line 104 and that decides what subcommand to run and how to run it. In some cases a script or function is immediately run for the subcommand. In many other cases a bit of custom logic is applied for preference or cross platform compatability.


Here's a description of most of the subcommands:

vimclone: Install or update a Vim plugin from GitHub by providing user/plugin or just the plugin name from Tim Pope's plugins. Finds local Vim instances which are running as a server and does a refresh to load in the new plugin thereby making it possible to load a new plugin without a Vim restart.

chat: Launch an irssi client over ssh and pass it the name of the current host.

clean: Delete old files, swap files, etc. from the current directory. Command is passed a number between 1 and four which is used to determine the age at which files are deleted. Excludes certain folders in the home directory.

cron: Does cleanup (more aggressively on directories over 90% full), kicks off setup which creates "$HOME/. tpope" to mark that setup has been performed, and pulls the config (update dotfiles from the web) when an update hasn't occurred in the last 30 days, as determined by the modification time of the .autodl file which is touched after an update finishes.

There is also a --login flag which is passed when a login shell starts (because .profile and .login call tpope cron --login). When the flag is passed, cron checks to see if it has run within the last week and if it hasn't then it kicks off a proper cron without the flag. The effect is that tpope cron will run on its own once per week upon running a login shell and it will update the configuration, rerun setup and remove temporary files.

It might seem like there's a lot going on here but the gist of it is that this is run as a general hygiene thing periodically to keep configuration updated, clean out old files, and rerun setup.

Note: The cron command lowers its priority when running using renice which is likely to move its activities out of the way for other things that might be in more immediate need of the CPU.

logview: View logs (in /var/logs) and automatically view as root if necessary. Also, automatically scroll to the end of the file.

pg: Invoke pager (e.g., less) with some highlighting and automatic formatting. Defers to tpope sensible-pager

ps-grep: Run the ps program and grep for a given pattern while omitting the ps-grep or gp itself and pipe the results into a pager. Makes it easy to examine a particular process.

tail: Custom tail command that uses LESSOPEN filter lesspipe and some custom options.

dl: Download files using whatever tool is available (wget, curl, or lynx) and save them in the downloads directory. There is also a convention for setting a filename when one isn't given.

url: Open a local file, site url, or search term in the browser (executes tpope-browser for the browser).

whois: Run output from the whois program through a pager.

config: Used for managing (syncing, updating, pulling, etc.) configurations on different machines. This is very interesting and pretty large so it's going to get its own post next time.

Interesting Tools

There are a couple of interesting tools lurking in the depths:

rmtrash: Like the rm program but move files to the trash instead.

xvncviewer: An X based VNC client.


Though I was careful when reading this stuff, I wouldn't be surprised if there are a few mistakes lurking in this post. Please let me know if you notice anything and I'll update it and make a note of it here.

Next Time

This post only covered the "motherfile" that contains a few utilities and kicks off subcommands. Next time I'll continue unearthing this project by discussing the setup and config subcommands which allow us to push, pull, tar, sync, clone, and prune dotfiles, for easy management across machines, as well as do some basic setup for cron, the shell, and the web browser.