dotfiles

In Linux configuration files are commonly referred to as dotfiles. I use git bare repository as outlined in this atlassian↗ article which uses only git . This helped me in moving my swaywm desktop from Linux Mint to Arch and later to Alpine Linux reasonably smoothly.

My dotfiles repository is located at sr.ht↗ .

Sometime back, when i moved the repository from github to sr.ht, after proper configuration on the site, it involved just changing the remote.

Initially i maintained both the machine specific configuration and user configuration in a single repository i.e dotfiles. Once i started adding more machines, the need to maintain machine specific configuration arose. Since i wanted to avoid duplication of my user configuration in each machine configuration repository, I used assistance from claude to split the orignal dotfiles repository to two repositories i.e machine-config and dotfiles. Individual machine configurations are kept as branches in the machine-config repository. The machine-config repository is private for security reasons.

Basic git configuration

In every machine, the following basic git configuration has to be done. After transferring both public and private key safely to the .ssh folder, issue the following commands.

git config --global user.name "Your Name"
git config --global user.email "mailid@mailprovider.com"
git config --global user.signingkey ~/.ssh/id_ed25519
ssh -T git@git.sr.ht

For github the last command should be as follows:

ssh -T git@github.com

First time configuration

Repo creation

Create bare repos using init command.

git init --bare $HOME/.dotfiles
git init --bare $HOME/.machine-config

Setup alias

set up aliases, depending on the shell used, add it to shell config file.

alias sysconfig='git --git-dir=$HOME/.machine-config --work-tree=/'
alias dotfiles='git --git-dir=$HOME/.dotfiles --work-tree=$HOME'

Adding alias for fish shell is shown.

echo "alias sysconfig='git --git-dir=\$HOME/.machine-config --work-tree=/'" >> ~/.config/fish/config.fish
echo "alias dotfiles='git --git-dir=\$HOME/.dotfiles --work-tree=$HOME'" >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Basic housekeeping

Perform this basic housekeeping to avoid adding unneeded files to the repos.

sysconfig config status.showUntrackedFiles no
dotfiles config status.showUntrackedFiles no

Configure remotes

Configure the repos after ensuring that the repo exists on the server of your choice. Here https://sr.ht↗ is used.

sysconfig remote add origin git@git.sr.ht:~prabuanand/machine-config
dotfiles remote add origin git@git.sr.ht:~prabuanand/dotfiles

Adding files to repo

Repeat the add command for every file to track. Once all files are added, perform the following steps for committing the pushing the user dotfiles.

dotfiles add /home/prabu/.profile
dotfiles status
dotfiles commit -m "added .profile"
dotfiles push origin master

Changing branch

Note the few additional steps performed to change the branch for the machine specific config files. Additional steps are given to verify the change.

sysconfig checkout -b machine/homepc2
sysconfig branch #verify the correct branch
sysconfig remote show origin # To verify if everything is in order

Repeat the add for every file to track. Perform the following steps similar to what was done for the user dotfiles.

sysconfig add /etc/fstab
sysconfig status
sysconfig commit -m "added /etc/fstab"
sysconfig push origin machine/homepc2

Reusing existing user dotfiles

The below steps explain how to reuse existing user dotfiles on a machine named oci.

Perform the following basic steps to create the bare repo and necessary alias and remotes.

git init --bare $HOME/.dotfiles
git init --bare $HOME/.machine-config
echo "alias dotfiles='git --git-dir=\$HOME/.dotfiles --work-tree=$HOME'" >> ~/.config/fish/config.fish
echo "alias sysconfig='git --git-dir=\$HOME/.machine-config --work-tree=/'" >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish
dotfiles config status.showUntrackedFiles no
sysconfig config status.showUntrackedFiles no
dotfiles remote add origin git@git.sr.ht:~prabuanand/dotfiles
sysconfig remote add origin git@git.sr.ht:~prabuanand/machine-config

Fetch the files from above remote.

dotfiles fetch origin

The below clone command could be used for repos like dotfiles instead of 3 commands to init, remote add and fetch commands shown above. The steps related to alias and housekeeping are still needed.

git clone --bare git@git.sr.ht:~prabuanand/dotfiles $HOME/.dotfiles

Backup existing conflicting files. Without this step, checkout will error on existing files.

mkdir -p $HOME/.dotfiles-backup
sh -c '
tab=$(printf "\t")
git --git-dir=$HOME/.dotfiles --work-tree=$HOME checkout master 2>&1 | while IFS= read -r line; do
    case "$line" in
        "${tab}"*)
            file=${line#?}
            mkdir -p "$HOME/.dotfiles-backup/$(dirname "$file")"
            mv "$HOME/$file" "$HOME/.dotfiles-backup/$file"
            ;;
    esac
done
'

To checkout the entire dotfiles repo, issue the command.

dotfiles checkout master

Machine-config files on new machines

The following steps are carried out in a machine named “oci”

Initial configuration

Complete the steps detailed in the Basic git configuration and appropriate steps from the First time configuration section.

Fix the permission before proceeding further, if security is paramount.

doas chmod 700 /home/prabu/.machine-config

For machine config file management, Create new machine branch for oci.

sysconfig checkout -b machine/oci

The machine config files can either differ totally from existing machines or based on an existing one.

Creating new machine-config files

The following steps are for the case where machine-config files differ totally from other machines. Repeat the add for every file that needs tracking on the oci machine.

sysconfig add /etc/fstab
sysconfig commit -m "initial commit: oci"
sysconfig push origin machine/oci

Reusing existing machine-config files

To use machine-config file from another machine’s configuration fetch + cherry-pick to use latest version of a file

sysconfig fetch origin
doas git --git-dir=$HOME/.machine-config --work-tree=/ checkout origin/machine/homepc2 -- /etc/resolvconf.conf

Commonly used commands

Handling systemfiles using doas

To remove system files use doas with full git command as alias won’t work in such cases.

doas git --git-dir=$HOME/.machine-config --work-tree=/ rm /usr/local/bin/current_song.sh

If the repository includes files that are readable only by root, then the same approach has to be used for other commands like shown below. Running cd / ensures a clean, predictable relative path.

cd / && doas git --git-dir=$HOME/.machine-config --work-tree=/ ls-files
cd / && doas git --git-dir=$HOME/.machine-config --work-tree=/ status

Verification commands:

Verify the config file of any git:

doas cat /home/prabu/.machine-config/config

Verify the identity shown in commit:

sysconfig log -1

Correction commands

Use these commands to fix ownership or author mismatches.

Rewrite the last commit with the correct author:

sysconfig commit --amend --reset-author --no-edit

“do-over” last commit:

sysconfig commit --amend --no-edit

Migration steps

As mentioned earlier i migrated from combined user + machine config. If you are starting new, this section can be ignored.

Initially i kept my bare git in $HOME/.systemfiles folder. For my case i need to carve user config out of what is currently a machine repo. So i copied over my existing bare git repo from ‘.systemfiles’ to ‘.machine-config’.

cd /
sysconfig ls-files / > /home/prabu/test #cleanup the file to remove machine-config files
head -n 5 /home/prabu/test
# Sample output:
# home/prabu/.ash_aliases
# home/prabu/.ashrc
# home/prabu/.bash_profile
# home/prabu/.bashrc
# home/prabu/.config/chrome-flags.conf
sed 's|^home/prabu|/home/prabu|' /home/prabu/test | xargs git --git-dir=$HOME/.dotfiles --work-tree=$HOME add
dotfiles commit -m "initial commit: user dotfiles migrated from https://git.sr.ht/~prabuanand/machine-config"
dotfiles push --force origin master
sysconfig ls-files / > /home/prabu/test #cleanup the file to keep unwanted user dotfiles
sed 's|^home/prabu|/home/prabu|' /home/prabu/test | xargs git --git-dir=$HOME/.machine-config --work-tree=/ rm --cached
sysconfig commit -m "removed dotfiles, now tracked in https://git.sr.ht/~prabuanand/dotfiles repo"