Skip to content

Latest commit

 

History

History
88 lines (53 loc) · 4.46 KB

.README.md

File metadata and controls

88 lines (53 loc) · 4.46 KB
Raw

Simple configuration files management

This repository is inspired by other "dotfiles" repos, particularly this one by @kalkayan. It does not contain any top-level non-hidden files like README.md or LICENSE to ensure that it can be cloned as a bare repo in your home directory to track all your desired config, without cluttering your home directory with extraneous files.

Start using these dotfiles

First, fork this repository to your personal github account.

You should review the resulting fork and remove any code you don't want or neeed. This repo contains my configuration files, and you are welcome to use it as a starting point, but you are likely to prefer something else.

Note that you can conveniently use GitHub's web editor, accessed via the . (dot/period) key, to edit the repo on the web before you make a local clone. Alternatively, first make a local clone in a throw-away location, do your preferred cleanup there, and then proceed with the next section where you'll make a bare repo clone for actual usage.

Clone your fork as a bare repository

The main advantage of this setup, and the reason this repository doesn't have any non-dot files, is that you can directly clone its contents into your $HOME directory and have your dotfiles version-controlled without further effort, without having to use either symlinks or manual synchronization scripts. For that to work, you need to do something sligthly unusual: to clone the repo as a bare repo and set your working directory to be $HOME:

⚠️ In the below, replace fperez with your github handle (this assumes you forked the repository as indicated above)

git clone --bare https://github.com/fperez/dotfiles.git $HOME/.dotfiles

Bare repositories do not have a working tree in their normal directory, instead they only contain the raw data, and we'll be using as our working tree $HOME itself. For this to work, whenever operating on this repo, your git call must always include these two flags:

  • --work-tree - this can be your home directory, i.e., $HOME or ~.
  • --git-dir - where the repository is cloned - $HOME/.dotfiles.

For convenience, we will alias this in our .bashrc file as:

alias gdot='git --git-dir=$HOME/.dotfiles --work-tree=$HOME'

From now on, instead of typing git you will type gdot to operate on this special repo.

Once cloned, check out the main branch into $HOME

You can now checkout the main branch into $HOME, to get the working copy of your files

gdot switch main

or if you didn't add the gdot alias as above, using the long form:

git --git-dir=$HOME/.dotfiles --work-tree=$HOME switch main

If you get a warning about files that might be overwritten, check first whether you're OK with that. If not, move the conflicting files out of the way first, otherwise you can force the switch with

gdot switch -f main

⚠️ The command gdot status will show all the untracked files, which in your home directory is likely a lot. To disable this behavior, use the following, which tells git to remove all untracked files and directories from status listings

gdot config --local status.showUntrackedFiles no

That's it, enjoy git-managed configuration files!

Benefits of this setup

  1. Easy setup on new machines of all your default configuration preferences.

  2. Use all git commands (via the gdot alias) like status, log, diff, etc., to track the status of your config files.

  3. Use git features like branches to maintain specific sets of configuration that you may want to use in certain machines or scenarios, easily switching between them. You can basically use named branches as system profiles that are readily available and centrally managed.

Usage notes

  • For some reason I don't fully understand, fetching remote branches does not work as expected with a bare repo. In order to get all remote branches (in case a new one was created and pushed to github), use dotfiles fetch origin '*:*' instead of simply fetch --all, as the latter will not fetch new branches.

Summary boostrap

The following has all the steps above in a single block for convenient copy/paste when setting up a new machine:

git clone --bare https://github.com/fperez/dotfiles.git $HOME/.dotfiles
alias gdot='git --git-dir=$HOME/.dotfiles --work-tree=$HOME'
gdot switch -f main
gdot config --local status.showUntrackedFiles no