~/.* managed with xadf

Welcome to my dotfiles repository! Managed with bare git and alias method, implemented as a custom controller script (xadf) that also functions as a standalone installation script to replicate my dotfiles configuration to any unix home directory with bash. Also features a number of custom bash functions (the $xadfmods) either for my use or just for fun.

[TOC]

Dotfiles Management 101

There are myriads of way to manage dotfiles, either using just a handful of general tools such as git and stow, or a set of specialized wrapper tools. In this section, I will provide a brief summary of how to manage dotfiles with stow, and with bare git and alias. Following that is an alternative wrapper script I created for my own use.

Stow method

Stow allows one to collect a group of files in 'packages', that can be installed to any location via symlinking (for managing dotfiles, the installation directory is usually $HOME). A package consists of a package directory that contain files and directories mirroring the target install location up to the root of installation directory. Consider you have program alpha, beta, and gamma, each having their own set of files and directories where they will look for configuration files:

~/
  .config/
    alpha/
      config
  .local/
    share/
      beta/
        clutter
    bin/
      beta
  .gamma/
    settings.xml
  .gammarc

All you need to do is to move them into a stow directory, and recreate the entire directory tree inside that stow directory. Alternatively, you can group them into per-program basis:

~/.dotfiles/
  alpha/
    .config/
      alpha/
        config
  beta/
    .local/
      share/
        beta/
          clutter
      bin/
        beta
  gamma/
    .gamma/
      settings.xml
    .gammarc

Then all we have to do is:

# navigate to the stow directory
cd ~/.dotfiles

# manually select each packages for installation to ~/
stow alpha
stow beta
stow gamma

# alternatively, install all packages to ~/
for pkg in */ ; do stow $pkg ; done

Note that stow's default behavior is to install the packages inside a stow directory (here it is ~/.dotfiles) to the parent directory of the stow directory (in this case we want it to be ~/).

If you want to delete them, you will need to do:

# navigate to the stow directory
cd ~/.dotfiles

# You can select which package to delete
stow -D alpha
stow -D beta
stow -D gamma

# Or delete all packages present here simultaneously
for pkg in */ ; do stow -D $pkg ; done

It is also possible that a collision occur (when the file stow is trying to 'install' is already present in the install directory). In that case, you can use --adopt option:

stow --adopt alpha

What it does is that the existing file in the install directory (in this case ~/) will be moved inside our stow directory (in this example ~/.dotfiles), and a symlink to the file will instead be created at the install directory.

After everything is configured to your liking, you can just turn the stow directory (~/.dotfiles) into a git repository to sync with your preferred remote.

Further reading on the stow method can be found here and here.

Bare git and alias method

Basically, to manage dotfiles with git bare methods, we have to set up a bare repository, and use a different work-tree. Then to replicate it, we clone with --separate-git-dir argument to a temporary directory. Then we rsync (except for .git folder) to home directory, and later remove the temporary directory.

Siilwyn made a very brief guide on how to set up and manage such setup. Furthermore there is also this article, and the method is popularized here.

In the next subsections, I will take the liberty to briefly demonstrate such setup. If you want more explanation to follow along, you may consider reading this article.

Setup

git init --bare $HOME/xadf
alias xadf='git --git-dir=$HOME/xadf/ --work-tree=$HOME'
xadf remote add origin [email protected]:heno72/xadf.git

Replication

git clone --separate-git-dir=$HOME/xadf https://gitlab.com/heno72/xadf.git .xadf-tmp
rsync --recursive --verbose --exclude '.git' .xadf-tmp/ $HOME/
rm --recursive .xadf-tmp

Configuration

xadf config status.showUntrackedFiles no
xadf remote set-url origin [email protected]:heno72/xadf-gb.git

Usage

xadf status
xadf add .gitconfig
xadf commit -m 'Add gitconfig'
xadf push

xadf: a custom implementation of bare git and alias methods

After trying both methods outlined above, I find myself liking the bare git and alias method. However I wanted more: a way to perform all of the steps outlined in the previous section from just a single wrapper script. I also want the file to be the one that will also manage the dotfiles after everything is set up. One of the requirement of such script is that it can be minimally invasive to existing setup. You may want to read more to read how I implement the script here.

All I need is to obtain the script and place it somewhere in my PATH. Then I can have a minimal installation with:

# Make directory, if it isn't present already
mkdir -p ~/.local/bin

# Download the executable into your local bin directory
wget -O ~/.local/bin/xadf https://gitlab.com/heno72/xadf/-/raw/master/.local/bin/xadf

# Make it executable
chmod +x ~/.local/bin/xadf

# Export path to local bin if it isn't set up already
PATH=~/.local/bin:$PATH

# Install xadf minimally
xadf --minimal-install

Afterwards, I can configure it into anyway I like. To demonstrate the prowess of my implementation, here's how I can rapidly set up a new empty bare git repository:

# initialize, configure, load, and manage
xadf --init-bare --seat ~/.dotfiles
xadf --custom-install --seat ~/.dotfiles
. ~/.bashrc
xadf config status.showUntrackedFiles no

You can read more about this from my minimal installation guide.

I might also have already a custom dotfiles repository meant to be managed by bare git and alias method, and I want xadf to clone and manage them.

# Clone and configure from a custom url, load, and manage
xadf -i -s [email protected]:heno72/xadf-gb.git --seat ~/.dotfiles
. ~/.bashrc
xadf status -sb

Suppose, you already have one existing bare git repository at ~/.dotfiles managed with an alias as in vanilla bare git and alias method. Now you want to manage your existing bare git repository with xadf instead of your own alias. In that case, you can configure xadf to manage the custom git directory with:

xadf --custom-install --seat ~/.dotfiles
. ~/.bashrc