dev-env-sync/README.md

# Dev Environment Sync

[![CI](https://img.shields.io/endpoint?url=https://7000pct.gitea.bloupla.net/api/actions/7000pctAUTO/dev-env-sync/statusbranch/main)](https://7000pct.gitea.bloupla.net/7000pctAUTO/dev-env-sync/actions)
[![Version](https://img.shields.io/pypi/v/dev-env-sync)](https://pypi.org/project/dev-env-sync/)
[![License](https://img.shields.io/pypi/l/dev-env-sync)](https://github.com/7000pctAUTO/dev-env-sync/blob/main/LICENSE)
[![Python Versions](https://img.shields.io/pypi/pyversions/dev-env-sync)](https://pypi.org/project/dev-env-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

```bash
pip install dev-env-sync
```

### From Source

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

### Verify Installation

```bash
dev-env-sync --version
```

## Quick Start

1. **Generate a sample configuration**:

```bash
dev-env-sync init
```

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

3. **Preview changes** (dry-run):

```bash
dev-env-sync sync --dry-run
```

4. **Apply changes**:

```bash
dev-env-sync sync
```

## Configuration

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

```yaml
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:

```bash
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:

```bash
dev-env-sync diff
```

### backup

Create a manual backup of your dotfiles:

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

### restore

Restore from a previous backup:

```bash
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:

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

### status

Show current environment status:

```bash
dev-env-sync status
```

### platforms

Show supported platforms and current detection:

```bash
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:

```yaml
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](LICENSE) file for details.

## Acknowledgments

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