Git Sync

Git Sync

Keep your dotfiles synchronized across multiple machines using Git with Heimdal.

Heimdal provides dotfiles-specific Git workflows. All Git operations shell out to the system git binary. For general Git operations (push, pull, branch, remote), use native Git commands directly.

Table of Contents

• Overview
• Setup
• Heimdal Git Commands
• Sync Workflow
• Auto-Sync
• Rollback
• Best Practices
• Troubleshooting

Overview

Heimdal uses Git to version control and sync your dotfiles across machines.

Machine A                    Machine B
~/.dotfiles/ ──git push──> GitHub/GitLab/Gitea <──git pull── ~/.dotfiles/
                            git@github.com:user/dotfiles

What Heimdal provides:

• heimdal commit — stage all changes and commit (with optional push)
• heimdal sync — pull from remote and apply configs in one command
• heimdal status — dotfiles-aware status
• heimdal diff — show uncommitted changes
• heimdal rollback — revert to a previous configuration

Use native Git for: push, pull, branch management, remote configuration.

Setup

On Your First Machine

1. Create a Git repository in your dotfiles directory:

cd ~/.dotfiles
git init
git add .
git commit -m "Initial dotfiles"

2. Add a remote and push:

git remote add origin git@github.com:yourusername/dotfiles.git
git push -u origin main

3. Add the repo URL to heimdal.yaml (optional, used by heimdal init):

heimdal:
  version: "1"
  repo: "git@github.com:yourusername/dotfiles.git"

On a New Machine

Use heimdal init to clone and configure in one step:

heimdal init --repo git@github.com:yourusername/dotfiles.git --profile default
heimdal apply

Or clone manually:

git clone git@github.com:yourusername/dotfiles.git ~/.dotfiles
cd ~/.dotfiles
heimdal profile switch default
heimdal apply

Heimdal Git Commands

heimdal status

Show what has changed in the dotfiles repository:

heimdal status

Output includes: repository path, current branch, modified files, untracked files, symlink status.

heimdal diff

Show uncommitted changes:

heimdal diff

heimdal commit

Stage all changes and commit. Optionally push to the remote:

# Commit with auto-generated message
heimdal commit

# Commit with a custom message
heimdal commit -m "Update vim configuration"

# Commit and push in one step
heimdal commit -m "Add zsh plugins" --push

After committing without --push, push with native Git:

git push

heimdal sync

Pull from the remote and apply configuration in one step:

heimdal sync

With dry-run preview:

heimdal sync --dry-run

Steps:

1. Pull from remote using git pull
2. Resolve conflicts (manual intervention required for merge conflicts)
3. Flush and encrypt any pending shell history entries (if bifrost key is configured and history.sync: true)
4. Rebuild the local history cache from all machines' encrypted history files
5. Run heimdal apply

To disable history sync during heimdal sync, set history.sync: false in heimdal.yaml. See History Sync for details.

Sync Workflow

Daily Workflow

# Morning: pull and apply latest changes from other machines
heimdal sync

# Make changes during the day
vim ~/.dotfiles/.vimrc

# Evening: commit and push
heimdal commit -m "Update vimrc colorscheme" --push

New Machine Setup

heimdal init --repo git@github.com:user/dotfiles.git --profile personal
heimdal apply

# Set machine-specific secrets
heimdal secret add github_token --value "ghp_..."

Multi-Machine Sync

# Machine A: make changes and push
heimdal commit -m "Add tmux config" --push

# Machine B: pull and apply
heimdal sync

Auto-Sync

Enable automatic background synchronization:

# Enable hourly sync
heimdal autosync enable --interval 1h

# Enable every 30 minutes
heimdal autosync enable --interval 30m

# Check status
heimdal autosync status

# Disable
heimdal autosync disable

Rollback

Revert to a previous configuration state:

# Roll back to the previous commit
heimdal rollback

# Preview what rollback would do
heimdal rollback --dry-run

# Roll back to a specific commit
heimdal rollback abc1234

# Roll back to a tagged version
heimdal rollback v1.0

View state history:

heimdal state history
heimdal state history --limit 20

Create Git tags for stable configurations:

git tag -a v1.0 -m "Stable configuration"
git push --tags

Best Practices

Commit Often

# After making a change
heimdal commit -m "Add Nord colorscheme to vim"

# Push at the end of a session
git push

Write Descriptive Commit Messages

# Good
heimdal commit -m "Configure tmux mouse support"
heimdal commit -m "Fix zsh completion path on macOS"

# Avoid
heimdal commit -m "update"
heimdal commit -m "changes"

Keep Secrets Out of Git

Secrets belong in the OS keychain, not in dotfiles:

heimdal secret add api_key --value "sk-..."
# Reference in templates as {{ secret:api_key }}

Add generated files with secret values to .gitignore:

.env
.aws/credentials
.ssh/config

Use Branches for Experiments

git checkout -b try-starship-prompt
vim ~/.dotfiles/.zshrc
heimdal commit -m "Switch to Starship prompt"
heimdal apply

# If it works, merge
git checkout main
git merge try-starship-prompt
git push

# If not, discard
git branch -D try-starship-prompt
git checkout main

Troubleshooting

Authentication Failed

# Test SSH connection
ssh -T git@github.com

# Generate a new SSH key if needed
ssh-keygen -t ed25519 -C "your_email@example.com"
# Add the public key at https://github.com/settings/keys

Merge Conflicts

When heimdal sync (or git pull) encounters a conflict:

# Find the conflicted file
git status

# Open and resolve the conflict markers
vim .vimrc
# Remove <<<<<<, =======, >>>>>>> markers

# Mark as resolved
git add .vimrc
git commit

# Then apply
heimdal apply

Keep local version:

git checkout --ours .vimrc
git add .vimrc
git commit

Keep remote version:

git checkout --theirs .vimrc
git add .vimrc
git commit

Push Rejected

# Pull first, then push
git pull
git push

# Or rebase
git pull --rebase
git push

Detached HEAD State

# Create a branch to save your position
git checkout -b recovery-branch

# Or return to main
git checkout main

Related Commands

# Heimdal-specific
heimdal sync                     # pull + apply
heimdal commit -m "message"      # stage all + commit
heimdal commit -m "message" --push  # stage all + commit + push
heimdal status                   # dotfiles-aware status
heimdal diff                     # uncommitted changes
heimdal rollback                 # revert to previous state
heimdal autosync enable --interval 1h

# Use native Git for these
git push
git pull
git branch
git remote -v
git log

Next Steps

• Dotfile Management - Manage dotfiles
• Profile System - Multiple configurations
• Configuration - Configuration reference