Maintaining consistent configuration settings across multiple devices can be a hassle, but a personal dotfiles repository is a great solution. By storing your dotfiles in a Git repository, you can easily manage and synchronize your preferred settings, ensuring a seamless experience no matter which computer you’re using.

This post will guide you through setting up a basic dotfiles workflow using Git. I will cover initialization, tracking, pushing, and cloning your configuration, along with some best practices to help you get started.

Why Use Git for Dotfiles?

Git is a powerful version control system, but it’s also a fantastic tool for managing configuration files. Here’s why:

  • Version Control: Track changes to your settings over time. Easily revert to previous configurations if something goes wrong.
  • Synchronization: Keep your settings consistent across all your devices with a simple dotfiles push and dotfiles pull.
  • Backup: Your dotfiles are safely stored in a remote repository (like GitHub, GitLab, or Bitbucket), providing a backup in case of hardware failure.
  • Automation: You can automate the setup of new systems by simply cloning your dotfiles repository and applying the configurations.

Getting Started

Let’s walk through the steps to set up your dotfiles repository.

1. Initialize the Repository:

First, create a bare Git repository in your home directory to store your dotfiles. This “bare” repository won’t have a working directory, as it’s solely meant for version control.

$ git init --bare --initial-branch=main "${HOME}/git/dotfiles"

2. Create an Alias:

To simplify Git commands related to your dotfiles, create a shell alias. This allows you to interact with the repository as if it were a regular working directory.

$ alias dotfiles='git --git-dir="${HOME}/git/dotfiles" --work-tree="${HOME}"'

This alias means you can use commands like dotfiles status, dotfiles add .bashrc, etc. instead of the longer git --git-dir="${HOME}/git/dotfiles" --work-tree="${HOME}" status, etc.

3. Configure Git:

Hide untracked files from git status output. This keeps your status clean.

$ dotfiles config --local status.showUntrackedFiles false

4. Connect to a Remote Repository:

Connect your local dotfiles repository to a remote repository on a platform like GitHub, GitLab, or Bitbucket. Replace git@example.com:user/dotfiles.git with your actual remote repository URL.

$ dotfiles remote add origin git@example.com:user/dotfiles.git

5. Push Your Dotfiles:

Push your initial dotfiles to the remote repository.

dotfiles push --set-upstream origin main

Tracking Your Dotfiles

Now that the repository is set up, it’s time to start tracking your dotfiles.

  1. Identify Your Key Configuration Files:

    Common dotfiles to track include:

    • .bashrc or .zshrc (Shell configuration)
    • .vimrc or .nvimrc (Vim/Neovim configuration)
    • .tmux.conf (Tmux configuration)
    • .editorconfig (Editor configuration)
    • .config/* (Configuration directory for various applications)

  2. Add and Commit Your Files:

    Use the dotfiles add and dotfiles commit commands to add and commit your dotfiles.

     $ dotfiles add .bashrc
 $ dotfiles commit -m "Initial commit of .bashrc"

  3. Regularly Commit Changes:

    Make it a habit to commit your changes whenever you modify a dotfile.

Managing Confidential Data

It’s crucial to avoid committing sensitive information (like API keys, passwords, or SSH private keys) to your dotfiles repository. Never combine sensitive and non-sensitive data in the same repository.

Cloning to a New System

Now, let’s see how to apply your dotfiles to a new system.

  1. Clone the Repository:

    $ git clone --separate-git-dir="${HOME}/git/dotfiles" git@example.com:user/dotfiles.git dotfiles-tmp

    The --separate-git-dir option ensures that the repository’s Git directory remains in ${HOME}/git/dotfiles, keeping things tidy.

  2. Sync Files:

    Use rsync to copy the files from the cloned directory to your home directory.

    $ rsync --recursive --verbose --exclude '.git' dotfiles-tmp/ "${HOME}/"

  3. Clean Up:

    Remove the temporary directory.

    $ rm --recursive dotfiles-tmp

Considerations

  • Ignoring Files: Use a .gitignore file in your dotfiles repository to exclude unnecessary files or directories. I recommend this for confidential data so you never get an accidental commit.
  • Conflict Resolution: Be prepared to handle conflicts if you make changes on multiple devices.

Resources