# How to Sync Dotfiles Across Multiple Machines Using Git and Dotbot

> Sync dotfiles across multiple machines with Git and Dotbot. Effortlessly manage configurations and apply them automatically with Git hooks for seamless updates on all your devices.

- Repository: [Ivan Smirnov/dotfiles](https://github.com/issmirnov/dotfiles)
- Tags: how-to-guide
- Published: 2026-03-04

---

**You can sync dotfiles across multiple machines by storing configurations in a Git repository, using Dotbot to create symbolic links, and leveraging Git hooks to automatically reapply changes whenever you pull updates.**

The **issmirnov/dotfiles** repository demonstrates a robust pattern to sync dotfiles across multiple machines using a combination of Git version control and the Dotbot symlink manager. This approach treats your home directory configuration as source code, enabling consistent environments across macOS and Linux with minimal manual intervention.

## Bootstrap a New Machine

To establish your dotfiles on a fresh system, clone the repository into `~/.dotfiles` and execute the installer:

```bash
git clone https://github.com/issmirnov/dotfiles.git ~/.dotfiles
~/.dotfiles/install

```

The `install` script bootstraps Dotbot and executes the appropriate configuration for your operating system. As shown in lines 10-22 of the script, it initializes submodules and invokes Dotbot with the correct config file:

```bash
git submodule update --init --recursive "$DOTBOT_DIR"
"${BASEDIR}/${DOTBOT_DIR}/${DOTBOT_BIN}" -d "${BASEDIR}" -c "default${CONFIG_SUFFIX}"

# OS-specific configuration

if [[ $OSTYPE == 'linux-gnu' ]]; then
    "${BASEDIR}/${DOTBOT_DIR}/${DOTBOT_BIN}" -d "${BASEDIR}" -c "ubuntu${CONFIG_SUFFIX}"
elif [[ $OSTYPE == darwin* ]]; then
    "${BASEDIR}/${DOTBOT_DIR}/${DOTBOT_BIN}" -d "${BASEDIR}" -c "osx${CONFIG_SUFFIX}"
fi

```

## How Dotbot Manages Cross-Machine Consistency

Dotbot reads [`default.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/default.conf.yaml) to create symbolic links from your home directory to the repository files. This ensures that every machine maintains the exact same file structure without duplicating configuration data.

The `link:` section in [`default.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/default.conf.yaml) defines how files like `.zshrc` or `.vimrc` map to their counterparts in `~/.dotfiles/`. When you run the installer, Dotbot idempotently creates these symlinks, making it safe to re-run the script after pulling updates.

## Automated Synchronization with Git Hooks

The repository includes a `post-checkout` hook at `git/hooks/post-checkout` that detects changes to any `*.conf.yaml` file or other tracked configurations. When you pull updates that modify these files, the hook automatically executes `~/.dotfiles/install` to re-link dotfiles and apply changes immediately.

This hook also handles auxiliary tasks such as updating Vim plugins, rebuilding the bat cache, and regenerating i3 configuration files. The relevant logic uses a `check_run` function to monitor specific file patterns and trigger the appropriate actions.

## The One-Command Update Workflow

For daily synchronization, the `gld` alias defined in [`zsh/aliases/utilities.zsh`](https://github.com/issmirnov/dotfiles/blob/main/zsh/aliases/utilities.zsh) (lines 29-30) combines pulling, submodule updates, and environment reloading:

```bash
alias gld='cd ~/.dotfiles && git pull && \
           git submodule update --init --recursive && \
           zgen update && popd'

```

Running `gld` on any machine fetches the latest changes and triggers the `post-checkout` hook, which automatically re-runs the installer if configuration files changed. This single command keeps your entire fleet of machines synchronized without manual linking.

## Making Changes on Any Machine

To propagate configuration changes across your machines:

- Edit the relevant file in `~/.dotfiles` (e.g., [`zsh/config/aliases.zsh`](https://github.com/issmirnov/dotfiles/blob/main/zsh/config/aliases.zsh)).
- Commit and push your changes:
  ```bash
  cd ~/.dotfiles
  git add zsh/config/aliases.zsh
  git commit -m "Add new alias for git status"
  git push
  ```

- On other machines, run `gld` to pull and automatically apply the updates.

Because the `post-checkout` hook monitors `*.conf.yaml` files, any structural changes to your dotfile layout are immediately re-linked without additional commands.

## OS-Specific Configurations

The `install` script automatically detects the operating system via `$OSTYPE` and loads additional Dotbot configurations. Linux systems process [`ubuntu.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/ubuntu.conf.yaml) while macOS systems process [`osx.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/osx.conf.yaml), allowing you to maintain platform-specific settings alongside your common base configuration.

This detection happens within the main `install` script, ensuring that cross-platform differences in paths or package managers are handled transparently during the sync process.

## Minimal Installation for Zsh Only

If you only need the shell environment on a temporary or lightweight machine, use the minimal installation path:

```bash
git clone https://github.com/issmirnov/dotfiles.git ~/.dotfiles
~/.dotfiles/minstall

```

The `minstall` script reads [`minimal.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/minimal.conf.yaml), which contains only essential `link:` entries for Zsh and Git hooks, skipping window manager and editor configurations.

## Summary

- Clone the repository to `~/.dotfiles` and run `./install` to bootstrap any new machine with your complete environment.
- Dotbot creates idempotent symbolic links defined in [`default.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/default.conf.yaml), ensuring consistent file layouts across hosts.
- The Git `post-checkout` hook at `git/hooks/post-checkout` automatically re-runs the installer when you pull changes that affect configuration files.
- Use the `gld` alias from [`zsh/aliases/utilities.zsh`](https://github.com/issmirnov/dotfiles/blob/main/zsh/aliases/utilities.zsh) to pull updates, refresh submodules, and trigger automatic re-linking in one command.
- OS-specific branches in the `install` script handle platform differences between macOS and Linux automatically.

## Frequently Asked Questions

### What is Dotbot and why use it for dotfiles?

Dotbot is a lightweight tool that automates the creation of symbolic links and execution of shell commands based on YAML configuration files. According to the issmirnov/dotfiles source code, using Dotbot ensures that symlinks from your home directory to the repository are created consistently and idempotently across every machine, eliminating manual copying or path management errors.

### How do Git hooks automate dotfile synchronization?

The `post-checkout` hook in `git/hooks/post-checkout` monitors for changes to `*.conf.yaml` files and other tracked configurations after every Git operation that updates the working directory. When detected, the hook automatically executes `~/.dotfiles/install`, ensuring that pulled changes are immediately reflected in your home directory without requiring manual intervention.

### Can I use this setup on macOS and Linux simultaneously?

Yes, the `install` script detects the operating system via the `$OSTYPE` environment variable and automatically applies OS-specific configurations. Linux systems load [`ubuntu.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/ubuntu.conf.yaml) while macOS loads [`osx.conf.yaml`](https://github.com/issmirnov/dotfiles/blob/main/osx.conf.yaml), allowing the same repository to support divergent platform requirements while maintaining a synchronized core configuration.

### What happens if I forget to run the install script after pulling?

If you use the `gld` alias or standard `git pull` commands, you do not need to remember to run the install script manually. The `post-checkout` Git hook automatically detects when configuration files change and re-runs the installer for you. However, if you disable hooks or use `git pull --no-verify`, you can manually execute `~/.dotfiles/install` at any time to re-apply your configuration.