How to Back Up and Restore Dotfiles Using Git and Dotbot

Back up your dotfiles by committing changes to a Git repository and restore them on any machine using a single curl command that clones the repo and runs the Dotbot installer.

The issmirnov/dotfiles repository demonstrates a robust, version-controlled approach to managing configuration files. By combining Git for version history and Dotbot for automated symlink management, you can back up and restore your entire development environment in minutes. This workflow ensures every alias, shell configuration, and editor setting is preserved and portable across machines.

Why Git and Dotbot Form the Ideal Backup Foundation

All configuration files live under the repository’s tree (for example, zsh/zshrc, vim/vimrc, and nano/nanorc). Because the repository is a standard Git project, every change is recorded in commit history and can be pushed to any remote such as GitHub or GitLab.

The Dotbot submodule located in dotbot/ drives the installation process. It creates appropriate symlinks on the target machine according to the YAML configuration in [default.conf.yaml](https://github.com/issmirnov/dotfiles/blob/master/default.conf.yaml). Because the active configuration files are symlinks pointing to the repository, the original copies remain safe in the repo; reinstalling on a new machine simply recreates these links without duplicating files.

Backing Up Your Dotfiles Repository

Committing Local Changes

When you modify any configuration file, commit those changes to preserve them in version control. From within your ~/.dotfiles directory:

git add -A
git commit -m "Add custom aliases and vim plugins"

This stores any tweaks you made to the files, such as custom shell aliases or editor settings, ensuring they are tracked for future restoration.

Pushing to Remote Storage

To maintain an off-site backup, push your repository to a remote. This allows restoration from any machine with internet access:

git remote add origin <your-repo-url>
git push -u origin master

Regular pushes ensure your latest configurations are safe even if your local machine fails.

Automating Periodic Snapshots

For automated peace of mind, schedule periodic backups using cron. The repository includes a stub in cheat/personal/cron demonstrating a monthly backup schedule:

0 0 1 * * /bin/monthly_backup

Replace /bin/monthly_backup with a script that archives ~/.dotfiles and pushes it to your preferred backup service or remote repository.

Restoring Dotfiles on a New System

One-Line Bootstrap with the d Script

The fastest way to restore your environment is using the d bootstrap script hosted at https://smirnov.link/d. Execute it with:

curl -sSL https://smirnov.link/d | bash

This script, defined in the repository’s d file, performs three critical actions:

1. Clones the repository to ~/.dotfiles
2. Executes ./install to trigger Dotbot
3. Creates a history file at ~/.zsh_history_ext for Zsh continuity

Manual Installation Workflow

If you already have the repository cloned locally or prefer manual control, run the installer directly:

cd ~/.dotfiles
./install

The install script initializes the Dotbot submodule and executes it with the base configuration. It then detects your operating system and applies OS-specific settings using either ubuntu.conf.yaml (for Linux) or osx.conf.yaml (for macOS). The script logic explicitly checks $OSTYPE to determine which configuration to apply.

Selective Zsh Environment Setup

If you only need to restore the Zsh shell environment without other configurations, run the dedicated setup script:

~/.dotfiles/zsh/setup

This sources the zshrc configuration and installs Oh-My-Zsh plugins, bypassing the full Dotbot installation.

Handling Nano Editor Backups

The nano editor has its own backup semantics configured via nano/nanorc:

# Create backup files in "filename~"

unset backup

# Set the directory where nano puts unique backup files if file backups

# set backupdir "~/.backup/nano"

With unset backup active, nano automatically creates a filename~ copy each time you save a file. To restore from such a backup, simply remove the ~ suffix or copy the backup file over the original.

Complete Backup and Restore Workflow Example

The following workflow demonstrates the complete lifecycle from initial setup through backup to restoration:

# 1. Clone the repository (first time setup)

git clone https://github.com/issmirnov/dotfiles.git ~/.dotfiles
cd ~/.dotfiles

# 2. Make a configuration change

echo "alias ll='ls -alF'" >> zsh/zshrc

# 3. Commit and push (backup)

git add -A
git commit -m "Add ll alias"
git push origin master

# 4. Restore on a fresh machine

curl -sSL https://smirnov.link/d | bash

# Or manually:

# cd ~/.dotfiles && ./install

Summary

• Git version control tracks every change to your configuration files, providing a complete history and remote backup capability.
• Dotbot automates the creation of symlinks from the repository to your home directory, making restoration a non-destructive, idempotent process.
• The d script provides a one-line bootstrap (curl -sSL https://smirnov.link/d | bash) that clones and installs everything automatically.
• The install script handles OS-specific configurations for both Ubuntu and macOS by selecting the appropriate .conf.yaml file.
• Nano editor backups are handled separately through nano/nanorc settings that create filename~ automatic backups.

Frequently Asked Questions

How does the dotfiles backup system handle file conflicts?

Dotbot checks existing files before creating symlinks. If a file already exists at the target location, Dotbot skips the link creation to prevent overwriting your existing data. You can manually remove or backup the conflicting file, then rerun ./install to complete the symlink creation.

Can I use this backup method on both macOS and Linux?

Yes. The install script automatically detects your operating system by checking the $OSTYPE environment variable. It applies ubuntu.conf.yaml for Linux systems and osx.conf.yaml for macOS, ensuring appropriate paths and packages for each platform.

What happens to my existing dotfiles when I run the restore script?

When you run the d script or ./install, Dotbot attempts to create symlinks from ~/.dotfiles/ to your home directory. Existing regular files are not deleted but are bypassed during installation. The repository stores the master copies, while your home directory contains only symlinks (or untouched original files if conflicts exist).

How do I schedule automatic backups of my dotfiles?

Edit your crontab to include a scheduled task referencing the example in cheat/personal/cron. A typical entry runs at midnight on the first of each month: 0 0 1 * * /path/to/backup_script. Your backup script should commit any local changes, pull the latest remote updates, and push the repository to your backup remote or archive service.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}