Underdose (WIP)

Dotfile overdosers' ideal companion. It's recommended to alias the binary underdose to ud. Distribution through cargo, AUR and homebrew are planned.

WIP Warning

This artifact is still under construction. The declared features have not been fully implemented yet.

Motivation and Philosophy

Three assertions for our potential users:

• Produce dotfiles from day to day and want to backup them up or synchronize them between machines.
• Consider a centralized git repository as a feasible way of managing dotfiles.
• Can do git, and expect the toolchain to be simple and surprise-free.

I hope underdose can be a powerful candidate as a tool that meets the said demands.

User Interface

Prerequisite

A git repository with two requirements is needed:

1. has a valid Drugstore.toml file;
2. has sub-directories that follows the rules listed in Drugstore.toml.

The git repository can be ready at any moment. The branches don't matter; the history doesn't matter; just make sure that the work tree is clean, i.e. nothing untracked, nothing staged, everything is managed by git.

underdose only cares about syncing the dotfiles on the machine and the local repository; the remote repository remains intact in any underdose operation, which means:

Thee shall set up the git repository and pledge to maintain it by yourself.

The bright side is you are free to use any combination of toolchains that is comfortable for you.

Drugstore Lifespan

Prepare a local git repo. Retrive it if it's remote. Anywhere you would like is fine. From now on we call it drugstore.

Run ud init under drugstore. Then you'll be directed to the Underdose.toml setting on your machine if you have $EDITOR ENVVAR, effectively running ud config.

Don't feel lost if you forget where the repo is! ud where will back you up.

Drugstore.toml Setup

Contains two parts.

1. env information to decide whether some pills need to be synced on the particular machine;
2. pills for each collection of drips to be managed.

# A simple pill about the nvim configuration. All machines follow the same
# configuration, and under the same path, so there is no subtlety.
[[pill]]
name = "nvim"
[[pill.drip]]
site = "~/.config/nvim"
[[pill.drip.arrow]]
site = "."
src.link = "."

The drips can be viewed as task groups and arrows can be viewed as tasks. For more examples, check templates/Drugstore.toml.

The configuration file for local underdose, named Underdose.toml, can be accessed through CLI (ud config, see below). A sample (and detailed tutorial) can be found in template/Drugstore.toml.

Daily Usage

ud sync (poor choice of word) ensures that your machine is in sync with your local repo. It can be treated as an install of a drugstore to your machine or an update to the drugstore. underdose will try to do the following step by step, and will abort on error, which requires your manual fix before another round of ud sync:

1. If the drugstore doesn't have a clean work tree, abort and prompt the user to stage and commit.
2. Forall pills, underdose observes all drips on the machine and see whether it's not in sync, fixably not in sync, or in sync.
   1. For links, not in sync means it's not correctly pointing to the location inside drugstore.
   2. For git, not in sync means it's not the right repo; and fixably not in sync means it's the correct repo but not pulled.
   3. For collector, // Todo: ..
3. After all the preparations, underdose prompts you that local sync is done and you should run remote sync.

Note that these commands come at pill-level granularity, so you can operate on one specific pill:

ud sync nvim

After ud sync, you should consider a repo level sync with remote by git pull and git push to keep your machine drips up-to-date.

And that's it! Enjoy.

Disclaimer

This software is at alpha stage and may contain unforeseen bugs. Ironically, even though it's a backup toolchain, please back things up by yourself. Luckily, underdose doesn't litter in your system so other backup tools can easily manage things as before.