Dotfiles Management Repository

This repository contains a comprehensive dotfiles management system that automates the synchronization, installation, and maintenance of system configurations across different environments.

Table of Contents

• Overview
• Getting Started
• Configuration
• Scripts
• Repository Structure
• Usage Examples
• Contributing
• License

Overview

This dotfiles repository provides:

• Automated synchronization between your home directory and the repository
• Package management with support for multiple package managers (pacman, yay, apt, brew, etc.)
• Font installation scripts for system fonts
• Configuration file management with automatic backup and restoration
• Multi-system support with OS detection and cross-platform compatibility

Getting Started

Prerequisites

• Python 3.6 or higher
• Git
• A .dotfiles_config file in your home directory (see Configuration)

Quick Start

1. Clone this repository:

   git clone <repository-url> ~/.dotfiles
   cd ~/.dotfiles

2. Create your .dotfiles_config file in your home directory (see examples in the config parser documentation)

3. Run the update script to sync your dotfiles:

   python scripts/update_dotfiles.py --sync

Configuration

The system uses a JSON configuration file (.dotfiles_config) that defines:

• Metadata: Repository information, version, and description
• Package Managers: Supported package managers for your system
• Packages: Applications and tools to install, organized by category
• Fonts: Font packages to install
• Files: Configuration files and directories to manage

The configuration parser (scripts/utils/config_parser.py) provides comprehensive validation and management of this configuration.

Scripts

Main Script: update_dotfiles.py

The primary management script with the following capabilities:

Actions

• --sync: Synchronize files from your home directory to the repository
• --push: Commit and push changes to GitHub
• --pull: Pull latest changes from GitHub

Options

• --dry-run: Preview what would be done without making changes
• --force: Force operations even with conflicts
• --create-missing: Create missing directories automatically
• --message, -m: Custom commit message for push operations
• --verbose, -v: Enable detailed logging
• --quiet, -q: Suppress non-essential output

Generated Files

The script automatically generates several helpful files in system directories:

• packages.sh: Installation script for all packages
• fonts.sh: Installation script for all fonts
• packages.json: Detailed package information
• fonts.json: Detailed font information
• README.md: Auto-generated documentation for each system configuration

Repository Structure

dotfiles/
├── scripts/                # Management scripts
│   ├── update_dotfiles.py  # Main management script
│   └── utils/              # Utility modules
│       └── config_parser.py # Configuration parsing and validation
├── LICENSE
└── README.md               # This file

Usage Examples

Synchronize and Push Changes

# Sync files from home directory and push to GitHub
python scripts/update_dotfiles.py --sync --push

# With custom commit message
python scripts/update_dotfiles.py --sync --push -m "Update i3 configuration"

Preview Changes

# See what would be synchronized without making changes
python scripts/update_dotfiles.py --sync --dry-run

Install Packages

# After syncing, install packages on a new system
cd <NAME>
./packages.sh
./fonts.sh

Pull Latest Changes

# Update local repository with remote changes
python scripts/update_dotfiles.py --pull

Force Operations

# Force sync even if there are conflicts
python scripts/update_dotfiles.py --sync --force

Error Handling

The scripts include comprehensive error handling and logging:

• Validation: Configuration files are validated before operations
• Backup: Existing files are backed up before being overwritten
• Rollback: Failed operations can be rolled back
• Logging: Detailed logs help troubleshoot issues

Contributing

Contributions are welcome! Please:

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