Management and Back-Up of dotfiles with GitHub

dotfiles_to_github.md

The most elegant and native way to manage dotfiles across your home directory and subdirectories is using a bare Git repository.

While you could move all your configs into a single folder and create symlinks (the traditional approach), a bare Git repository allows you to leave all your files exactly where they are. It requires zero extra software—just Git—and prevents your home directory from becoming a cluttered mess of symlinks.

Here is exactly how to set it up.

The Bare Repository Setup

A bare repository separates the Git database from your working tree. The database will live in a hidden folder, but Git will treat your entire home directory as the working tree.

1. Create the bare repository: Open your terminal and initialize a bare repository. This folder will hold your Git database (the commits and history).

git init --bare $HOME/.dotfiles

2. Create a shell alias: To interact with this repository without affecting other normal Git projects on your machine, create an alias. Add this line to your ~/.bashrc or ~/.zshrc:

alias config='/usr/bin/git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'

Note: Reload your shell (source ~/.bashrc) or open a new terminal window before moving to the next step.

3. Hide untracked files: Crucial for a clean status. Because your working tree is your entire home directory, Git will initially see every single file you own as an "untracked file." You must tell this specific repository to ignore anything you haven't explicitly added:

config config --local status.showUntrackedFiles no

4. Connect to GitHub: Create an empty, private repository on GitHub (e.g., named dotfiles). Then link your local bare repository to it:

config remote add origin git@github.com:YOUR_USERNAME/dotfiles.git
config branch -M main

---

Daily Usage

From now on, you will use the config alias instead of git whenever you want to manage your dotfiles. It behaves exactly like standard Git.

To back up a file in your home directory or any subdirectory:

1. Add the file:

config add ~/.bashrc
config add ~/.config/htop/htoprc

2. Commit your changes:

config commit -m "Add bash and htop configs"

3. Push to GitHub:

config push -u origin main

Because of the showUntrackedFiles setting you applied earlier, running config status will only show changes to the files you have explicitly added using the config add command. The rest of your home directory remains safely ignored.

Restoring on a New Machine

When you get a new computer, restoring your setup is a breeze. You just clone the bare repository, set the alias, and check out the files:

git clone --bare git@github.com:YOUR_USERNAME/dotfiles.git $HOME/.dotfiles
alias config='/usr/bin/git --git-dir=$HOME/.dotfiles/ --work-tree=$HOME'
config config --local status.showUntrackedFiles no
config checkout

(If the checkout fails because default files like .bashrc already exist on the new system, you simply delete or move the default ones and run config checkout again).

Alternative Approaches

If you find that your dotfiles are highly complex (e.g., you need different configurations for a work laptop vs. a personal desktop), you might outgrow the bare Git method. In that case, look into:

• GNU Stow: A symlink manager that lets you keep all your configs in one folder and symlinks them to their correct locations automatically.
• Chezmoi: A dedicated dotfile manager that supports templating, allowing you to inject machine-specific variables into your config files before they are applied.