DotFiles Sync (dfsync)

A powerful Go CLI tool for backing up and restoring project dotfiles with Google Drive synchronization support.

Overview

dfsync helps you manage project-specific configuration files (dotfiles) by creating centralized backups in ~/dotfiles/ and maintaining symlinks in your projects. This approach enables seamless synchronization across multiple machines via Google Drive while keeping your projects clean and organized.

Features

• 🔄 Smart Backup: Automatically detects and backs up common dotfiles
• 🔗 Symlink Management: Creates and manages symlinks transparently
• 📁 Project Organization: Each project gets its own backup folder
• ☁️ Cloud Sync Ready: Designed for Google Drive synchronization
• ⚙️ Configurable: Customizable file patterns and backup rules
• 🛡️ Safe Operations: Validates operations and prevents data loss

Installation

From Source

git clone https://github.com/heytonyne/dfsync.git
cd dfsync
make install

Using Go

go install github.com/heytonyne/dfsync/cmd/dfsync@latest

Quick Start

1. Initialize dfsync (first time only):

   dfsync init

2. Navigate to your project directory:

   cd /path/to/your-project

3. Backup your dotfiles:

   dfsync backup

4. On another machine, restore the dotfiles:

   dfsync init  # Setup config on new machine
   cd /path/to/your-project
   dfsync restore your-project-name

Usage

Commands

dfsync init

Initialize dfsync configuration (run once per machine)

# Initialize with default settings
dfsync init

# Initialize with custom dotfiles directory
dfsync init --dotfiles-path ~/my-dotfiles

dfsync backup

Backup current project's dotfiles to ~/dotfiles/

# Basic backup (uses current directory name)
dfsync backup

# Custom backup name
dfsync backup --name my-special-project

# Include additional files
dfsync backup --include "*.secret" --include "custom-config/"

# Force overwrite existing backup
dfsync backup --force

dfsync restore <folder-name>

Restore dotfiles from backup to current directory

# Restore specific backup
dfsync restore my-project

# List available backups first
dfsync list
dfsync restore my-project

dfsync list

List all available backups

dfsync list

dfsync status

Show current project's backup status

dfsync status

Default Files Backed Up

By default, dfsync backs up these common dotfiles:

• .env, .env.local
• .notes.local, .data.local
• .augment
• .vscode/settings.json
• .idea/ (IntelliJ IDEA settings)
• docker-compose.override.yml
• *.local.* (any local configuration files)

How It Works

Backup Process

1. Detection: Scans current directory for configured file patterns
2. Organization: Creates ~/dotfiles/{project-name}/ directory
3. Migration: Moves detected files to backup location
4. Linking: Creates symlinks from backup to original locations
5. Metadata: Saves configuration in .config/config.yml

Restore Process

1. Configuration: Reads backup metadata from .config/config.yml
2. Validation: Ensures target directory and backup exist
3. Cleanup: Removes existing symlinks safely
4. Recreation: Creates new symlinks from backup to target
5. Update: Records restore timestamp

Directory Structure

~/dotfiles/
├── project-a/
│   ├── .config/
│   │   └── config.yml          # Backup metadata
│   ├── .env
│   ├── .notes.local
│   └── .vscode/
│       └── settings.json
├── project-b/
│   ├── .config/
│   │   └── config.yml
│   ├── .env.local
│   └── docker-compose.override.yml
└── ...

Configuration

Global Configuration

Create ~/.config/dfsync/config.yml:

dotfiles_path: "~/dotfiles"
default_includes:
  - ".env"
  - ".env.local"
  - ".notes.local"
  - ".data.local"
  - ".augment"
  - ".vscode/settings.json"
  - ".idea"
  - "docker-compose.override.yml"
  - "*.local.*"

Project Configuration

Each backup includes a .config/config.yml file:

name: "my-project"
source_path: "/Users/username/projects/my-project"
backup_path: "/Users/username/dotfiles/my-project"
backup_date: "2024-01-15T10:30:00Z"
files:
  - ".env"
  - ".notes.local"
directories:
  - ".vscode"
symlinks:
  - source: "/Users/username/dotfiles/my-project/.env"
    target: "/Users/username/projects/my-project/.env"

Google Drive Synchronization

To sync across machines:

1. Setup Google Drive: Ensure ~/dotfiles/ is in your Google Drive folder (or any other sync providers)
2. Backup on Machine A: Run dfsync backup in your project
3. Wait for Sync: Let Google Drive sync the backup
4. Restore on Machine B: Run dfsync restore project-name in target directory

Examples

Web Development Project

cd ~/projects/my-webapp
# Creates backup with .env, .vscode/settings.json, etc.
dfsync backup

# On another machine
cd ~/projects/my-webapp
dfsync restore my-webapp

Go Project with Custom Files

cd ~/projects/my-go-service
# Include additional configuration
dfsync backup --include ".air.toml" --include "configs/*.local.yml"

Check What's Backed Up

cd ~/projects/my-project
dfsync status
# Shows: Backed up to ~/dotfiles/my-project (3 files, 1 directory)

Development

Building from Source

git clone https://github.com/heytonyne/dfsync.git
cd dfsync
make build

Running Tests

make test

Project Structure

dfsync/
├── cmd/dfsync/           # CLI entrypoint
├── internal/             # Private packages
│   ├── backup/          # Backup logic
│   ├── restore/         # Restore logic
│   ├── config/          # Configuration management
│   ├── symlink/         # Symlink operations
│   └── utils/           # Utilities
├── pkg/logger/          # Shared logging
├── configs/             # Default configurations
└── docs/               # Documentation

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions