Dotfiles

Dotfiles helps you sync and install your POSIX¹ config files with a single command, backed by shared git repositories².

¹e.g. Linux, BSD, macOS

²e.g. hosted on GitHub or GitLab

In brief

1. Edit config files in the posix subdirectory
2. Commit and push with git
3. Sync and install config files by running ./dotfiles sync

A basic understanding of git is strongly recommended.

Why not just sync the home directory?

Dotfiles allow you to automatically apply system-specific configs while syncing the rest.

By editing config files in a separate directory and then installing them, Dotfiles also makes breakages more easily recoverable.

Contents

• Setup
  • Clone this repository
  • Personal remote repository (simple method)
• Usage
  • Adding config files
  • Editing config files
  • Syncing and installing config files
• Advanced usage
  • Install local config files without syncing
  • System-specific configs
  • Linked personal remote repository
  • Backups

All commands shown below should be run in the Dotfiles directory, unless otherwise noted.

Setup

Clone this repository

In a parent directory, run

git clone https://github.com/yushiyangk/dotfiles.git

Note that this setup step does not install any config files. To install files, see the Usage section below.

Set up your personal remote repository by following either the next section or the alternative method under Advanced usage.

Personal remote repository (simple method)

Create a new repository on a git hosting service of your choice (e.g. GitHub or GitLab), and note down its git URL.

Replace the original remote repository with your personal one by running

git remote set-url origin new_remote_url

Usage

Adding config files

User config files are typically found in the home directory ($HOME or ~), with a filename that begins with ..

For each config file that needs to be synced, copy it into the posix subdirectory under the same relative path as it was in ~.

Editing config files

Edit files in the posix subdirectory, then git commit them as normal. For example, to commit all modified files,

git commit -a -m commit_message

Update your personal remote repository by running

git push

If using a linked repository, first ensure that you are on your personal branch by running git checkout your_branch_name.

Syncing and installing config files

Run the command

./dotfiles sync

This will pull the config files from your personal remote repository, then automatically install them into ~.

Advanced usage

Install local config files without syncing

Run

./dotfiles install

This will install the files currently in the posix subdirectory without pulling from any remote repository.

System-specific configs

System-specific configs can be applied using local patches and local appends.

For each config file with system-specific tweaks, create either filename.local.patch or filename.local.append (or both) in the same directory that the file is installed to. For example, in order to tweak ~/.bashrc, create either ~/.bashrc.local.patch or ~/.bashrc.local.append.

If filename.local.patch exists, Dotfiles will attempt to patch the installed config file with the patch file. If filename.local.append exists, Dotfiles will append it to the installed config file. If both exist, the patch will be applied first, then the append.

Creating patch files

One way of creating the patch file would be to first edit the installed config file directly in ~, then run the following in the Dotfiles directory

diff -U3 posix/config_file ~/config_file > ~/config_file.local.patch
./install_dotfiles.sh

Linked personal remote repository

This method for setting up your personal remote repository is more complicated, but has the advantage of continuing to receive updates to Dotfiles from this repository.

Create a new repository on a git hosting service of your choice (e.g. GitHub or GitLab), and note down its git URL.

Make a new branch for your personal config files:

git checkout -b your_branch_name

Add your personal remote repository and set your personal branch to track your personal remote:

git remote add your_remote_name your_remote_url
git push --set-upstream your_remote_name your_branch_name

Thereafter, add or edit your personal config files as before, but only commit them to your personal branch and push them to your personal remote.

Warning: Do not use GitHub's "fork repository" function as that will make your personal config files accessible to everyone else.

Updating Dotfiles

If using a linked repository, remain on your personal branch (or run git checkout your_branch_name), and run the following:

git fetch origin public:public
git merge public

This will fetch the updated version of Dotfiles and merge it into your personal branch.

Backups

When installing a config file, if a file of the same name already exists, the previously existing file will be backed up to the .backup subdirectory, under a subdirectory corresponding to the current timestamp.

In-situ backup

In addition, if a file of the same name already exists, the original version will be renamed to filename~ (i.e. a tilde will be appended to the filename) in the same directory. However, if such a file already exists, no further copy will be made.

This is intended to provide a quick reference for the default config files distributed with the operating system (or possibly the state of the config files before they were managed by Dotfiles, if different).