From d11639ea8f528469b7596e1a6e51e22392b46f86 Mon Sep 17 00:00:00 2001 From: kumar vaibhav Date: Wed, 19 Nov 2025 22:42:28 +0530 Subject: [PATCH] README --- README.md | 235 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4f8e2cd --- /dev/null +++ b/README.md @@ -0,0 +1,235 @@ +# fedora-home-manager + +A home-manager like script for Fedora that provides dotfile management and package installation functionality. + +## Overview + +fedora-home-manager is a bash script that helps you manage your Fedora system configuration by: +- Installing and managing system packages via dnf +- Deploying and managing dotfiles to your home directory +- Automatically cleaning up packages that are no longer needed +- Tracking state of managed files and packages + +## Installation + +1. Clone or download this repository +2. Make the script executable: + ```bash + chmod +x forge + ``` +3. Optionally, move it to a directory in your PATH: + ```bash + sudo mv forge /usr/local/bin/fedora-home-manager + ``` + +## Quick Start + +```bash +# Initialize the configuration structure +./forge init + +# Add a dotfile to management +./forge add ~/.bashrc + +# Add packages to install (edit the packages file) +echo "git" >> ~/.config/fedora-home-manager/packages.txt +echo "vim" >> ~/.config/fedora-home-manager/packages.txt + +# Apply configuration +./forge switch +``` + +## Commands + +### `init` +Initialize the configuration structure and create example files. + +```bash +./forge init +``` + +Creates: +- `~/.config/fedora-home-manager/` - Main configuration directory +- `~/.config/fedora-home-manager/dotfiles/` - Directory for your dotfiles +- `~/.config/fedora-home-manager/packages.txt` - List of packages to install +- `~/.config/fedora-home-manager/state.json` - State tracking file +- `~/.config/fedora-home-manager/backup/` - Backup directory for existing files + +### `switch` +Apply the current configuration (install packages, deploy dotfiles, cleanup old packages). + +```bash +./forge switch +``` + +This command: +1. Installs all packages listed in `packages.txt` +2. Uninstalls packages that are no longer in `packages.txt` +3. Deploys all dotfiles from the dotfiles directory to your home +4. Creates backups of existing files before overwriting +5. Updates the state tracking + +### `build` +Alias for `switch` command. + +```bash +./forge build +``` + +### `add ` +Add a file to dotfiles management. + +```bash +./forge add ~/.bashrc +./forge add ~/.vimrc +./forge add ~/.config/alacritty/alacritty.yml +``` + +The file is copied to the dotfiles directory while maintaining its relative path structure. + +### `remove ` +Remove a dotfile from management. + +```bash +./forge remove .bashrc +./forge remove .config/alacritty/alacritty.yml +``` + +Optionally restores the original file from backup. + +### `list` +List all managed files and packages. + +```bash +./forge list +``` + +Shows: +- All dotfiles currently under management +- All packages that will be installed + +### `status` +Show current status and configuration information. + +```bash +./forge status +``` + +Displays: +- Configuration directory paths +- Last switch timestamp +- List of managed files and packages + +### `help` +Show help message with all available commands. + +```bash +./forge help +``` + +## Configuration Files + +### packages.txt +List of Fedora packages to install, one package per line: +``` +# Comments start with # +git +vim +curl +wget +neofetch +``` + +### dotfiles directory +Place your dotfiles in `~/.config/fedora-home-manager/dotfiles/` maintaining the same directory structure as in your home: + +``` +~/.config/fedora-home-manager/dotfiles/ +├── .bashrc +├── .vimrc +└── .config/ + └── alacritty/ + └── alacritty.yml +``` + +### state.json +Internal state tracking file (managed automatically): +- Tracks installed packages for cleanup +- Records last switch timestamp +- Maintains list of managed files + +## Features + +### Automatic Package Cleanup +When you remove a package from `packages.txt` and run `switch`, the package will be automatically uninstalled from your system. + +### Backup System +Before overwriting existing files, the script creates timestamped backups in the backup directory. + +### State Tracking +Previously installed packages are tracked to enable intelligent cleanup operations. + +## Environment Variables + +- `HOME_MANAGER_DIR`: Override the default configuration directory (default: `~/.config/fedora-home-manager`) + +## Dependencies + +- `dnf` - Fedora package manager +- `jq` - JSON processor (optional, for enhanced state tracking) + +## Examples + +### Basic Setup +```bash +# Initialize +./forge init + +# Add your shell configuration +./forge add ~/.bashrc +./forge add ~/.bash_profile + +# Add development tools +echo "git" >> ~/.config/fedora-home-manager/packages.txt +echo "vim" >> ~/.config/fedora-home-manager/packages.txt +echo "nodejs" >> ~/.config/fedora-home-manager/packages.txt +echo "npm" >> ~/.config/fedora-home-manager/packages.txt + +# Apply configuration +./forge switch +``` + +### Managing Configuration Files +```bash +# Add application configurations +./forge add ~/.config/alacritty/alacritty.yml +./forge add ~/.config/git/config +./forge add ~/.config/nvim/init.vim + +# Check what's managed +./forge list + +# Apply changes +./forge switch +``` + +### Removing Packages +```bash +# Edit packages.txt and remove lines for packages you don't want +# Then run switch to uninstall them +./forge switch +``` + +## File Structure + +``` +~/.config/fedora-home-manager/ +├── dotfiles/ # Your dotfiles to deploy +├── packages.txt # List of packages to install +├── state.json # State tracking +└── backup/ # Backups of replaced files +``` + +## License + +This project is open source. Feel free to contribute or report issues. \ No newline at end of file