dev-env-sync/README.md

Dev Environment Sync

A declarative YAML-based CLI tool to manage, sync, and automate developer environment setup across Linux, macOS, and WSL. Handles dotfiles, editor configs, shell settings, and package installations with dry-run and backup capabilities.

Features

• Declarative Configuration: Define your entire dev environment in a single YAML file
• Cross-Platform Support: Works on Linux, macOS, and WSL
• Dotfiles Management: Create symlinks from source dotfiles to target locations
• Editor Configuration: Sync VS Code settings, Neovim config, and more
• Package Installation: Support for Homebrew, apt, dnf, npm, and more
• Dry-Run Mode: Preview all changes before applying them
• Backup & Restore: Automatic backups before changes with restore capability
• Shell Integration: Handle bash, zsh, and fish configurations

Installation

From PyPI

pip install dev-env-sync

From Source

git clone https://github.com/yourusername/dev-env-sync.git
cd dev-env-sync
pip install -e .

Verify Installation

dev-env-sync --version

Quick Start

1. Generate a sample configuration:

dev-env-sync init

2. Edit the generated configuration (.dev-env-sync.yml) to match your environment.

3. Preview changes (dry-run):

dev-env-sync sync --dry-run

4. Apply changes:

dev-env-sync sync

Configuration

Create a .dev-env-sync.yml file in your project or home directory:

version: "1.0"
name: "My Dev Environment"
description: "My developer environment configuration"

dotfiles:
  bashrc:
    source: ./dotfiles/.bashrc
    target: ~/.bashrc
    backup: true
  zshrc:
    source: ./dotfiles/.zshrc
    target: ~/.zshrc
    backup: true
  vimrc:
    source: ./dotfiles/.vimrc
    target: ~/.vimrc

shell:
  shell: bash
  merge_strategy: replace

editors:
  vscode:
    settings:
      settings_file: ./editors/vscode/settings.json
    extensions:
      - name: ms-python.python
      - name: esbenp.prettier-vscode
  neovim:
    init_file: ./editors/nvim/init.lua
    plugins:
      - name: vim-airline/vim-airline

packages:
  - name: brew
    packages:
      - git
      - neovim
      - tmux
      - fzf
  - name: apt
    packages:
      - git
      - neovim
      - tmux

backup:
  enabled: true
  directory: ~/.dev-env-sync-backups
  timestamp_format: "%Y%m%d_%H%M%S"

Commands

sync

Synchronize your entire developer environment:

dev-env-sync sync
dev-env-sync sync --dry-run  # Preview without applying
dev-env-sync sync --verbose  # Detailed output

diff

Show pending changes without applying them:

dev-env-sync diff

backup

Create a manual backup of your dotfiles:

dev-env-sync backup
dev-env-sync backup --output /custom/path

restore

Restore from a previous backup:

dev-env-sync restore                    # Restore from latest backup
dev-env-sync restore --list             # List available backups
dev-env-sync restore 20240101_120000    # Restore from specific backup
dev-env-sync restore --restore-all      # Restore all files
dev-env-sync restore --file ~/.bashrc   # Restore specific file

init

Generate a sample configuration file:

dev-env-sync init
dev-env-sync init -o custom-config.yml

status

Show current environment status:

dev-env-sync status

platforms

Show supported platforms and current detection:

dev-env-sync platforms

Environment Variables

Variable	Description	Default
DEV_ENV_SYNC_CONFIG	Path to default config file	~/.dev-env-sync.yml
DEV_ENV_SYNC_VERBOSE	Enable verbose debug output	false
DEV_ENV_SYNC_BACKUP_DIR	Path to backup directory	~/.dev-env-sync-backups

Cross-Platform Support

Linux

• Supports apt, dnf, and pacman package managers
• XDG-compliant config directories
• Full symlink support

macOS

• Homebrew package manager support
• macOS-specific config paths
• Universal binary support

WSL (Windows Subsystem for Linux)

• Linux tools within Windows
• WSL-specific detection
• Cross-platform file paths

File Structure

dev-env-sync/
├── .dev-env-sync.yml      # Your configuration file
├── dotfiles/              # Your dotfiles repository
│   ├── .bashrc
│   ├── .vimrc
│   └── .gitconfig
├── editors/               # Editor configurations
│   ├── vscode/
│   │   └── settings.json
│   └── nvim/
│       └── init.lua
└── .dev-env-sync-backups/ # Automatic backups
    └── 20240101_120000/
        ├── manifest.json
        └── .bashrc

Ignoring Files

You can add ignore patterns (similar to .gitignore) to skip specific dotfiles:

dotfiles:
  bashrc:
    source: ./dotfiles/.bashrc
    target: ~/.bashrc
    ignore:
      - "*.bak"
      - "*.orig"
      - "*.local"

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add 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.

Acknowledgments

• Inspired by popular dotfiles management tools
• Built with Click for a great CLI experience
• Uses PyYAML for configuration parsing