reworked
This commit is contained in:
kumar vaibhav
parent
0cf22d6e5e
commit
980b1c01a8
2 changed files with 336 additions and 524 deletions
289
README.md
289
README.md
|
|
@ -1,14 +1,15 @@
|
|||
# fedora-home-manager
|
||||
# Forge - A Home-Manager Like Tool for Fedora
|
||||
|
||||
A home-manager like script for Fedora that provides dotfile management and package installation functionality.
|
||||
A lightweight configuration management tool for Fedora that provides dotfile management and package installation functionality through a centralized TOML configuration.
|
||||
|
||||
## Overview
|
||||
|
||||
fedora-home-manager is a bash script that helps you manage your Fedora system configuration by:
|
||||
Forge 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
|
||||
- Managing dotfiles through symlinks to actual files
|
||||
- Centralized configuration via a single `forge.toml` file
|
||||
- User-level configuration similar to home-manager/nixos
|
||||
- Automatic backup of existing files before replacement
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
@ -19,7 +20,7 @@ fedora-home-manager is a bash script that helps you manage your Fedora system co
|
|||
```
|
||||
3. Optionally, move it to a directory in your PATH:
|
||||
```bash
|
||||
sudo mv forge /usr/local/bin/fedora-home-manager
|
||||
sudo mv forge /usr/local/bin/forge
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
|
@ -28,88 +29,44 @@ fedora-home-manager is a bash script that helps you manage your Fedora system co
|
|||
# Initialize the configuration structure
|
||||
./forge init
|
||||
|
||||
# Add a dotfile to management
|
||||
./forge add ~/.bashrc
|
||||
|
||||
# Add packages to install (edit the packages file)
|
||||
echo "git = \"latest\"" >> ~/.config/fedora-home-manager/packages.toml
|
||||
echo "vim = \"latest\"" >> ~/.config/fedora-home-manager/packages.toml
|
||||
# Edit the configuration file to add packages and dotfiles
|
||||
nano ~/.config/forge/forge.toml
|
||||
|
||||
# Apply configuration
|
||||
./forge switch
|
||||
|
||||
# Check status
|
||||
./forge status
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### `init`
|
||||
Initialize the configuration structure and create example files.
|
||||
Initialize the configuration structure and create `forge.toml`.
|
||||
|
||||
```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.toml` - TOML file with packages to install
|
||||
- `~/.config/fedora-home-manager/state.json` - State tracking file
|
||||
- `~/.config/fedora-home-manager/backup/` - Backup directory for existing files
|
||||
- `~/.config/forge/` - Main configuration directory
|
||||
- `~/.config/forge/forge.toml` - Central configuration file
|
||||
|
||||
### `switch`
|
||||
Apply the current configuration (install packages, deploy dotfiles, cleanup old packages).
|
||||
Apply the current configuration (install packages, deploy dotfiles).
|
||||
|
||||
```bash
|
||||
./forge switch
|
||||
```
|
||||
|
||||
This command:
|
||||
1. Installs all packages listed in `packages.toml`
|
||||
2. Uninstalls packages that are no longer in `packages.toml`
|
||||
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 <file>`
|
||||
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 <path>`
|
||||
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
|
||||
1. Installs all packages listed in `forge.toml`
|
||||
2. Creates symlinks for all configured dotfiles
|
||||
3. Creates backups of existing files before replacing them
|
||||
4. Updates the last switch timestamp
|
||||
|
||||
### `status`
|
||||
Show current status and configuration information.
|
||||
Show current configuration status and information.
|
||||
|
||||
```bash
|
||||
./forge status
|
||||
|
|
@ -118,7 +75,7 @@ Show current status and configuration information.
|
|||
Displays:
|
||||
- Configuration directory paths
|
||||
- Last switch timestamp
|
||||
- List of managed files and packages
|
||||
- List of configured packages and dotfiles
|
||||
|
||||
### `help`
|
||||
Show help message with all available commands.
|
||||
|
|
@ -127,122 +84,168 @@ Show help message with all available commands.
|
|||
./forge help
|
||||
```
|
||||
|
||||
## Configuration Files
|
||||
## Configuration
|
||||
|
||||
### forge.toml
|
||||
The central configuration file located at `~/.config/forge/forge.toml`:
|
||||
|
||||
### packages.toml
|
||||
List of Fedora packages to install in TOML format:
|
||||
```toml
|
||||
# Fedora packages configuration
|
||||
# TOML format for better package management
|
||||
# Forge Configuration File
|
||||
# User-level configuration similar to home-manager/nixos
|
||||
|
||||
[forge]
|
||||
version = "1.0"
|
||||
last_switch = null
|
||||
|
||||
[packages]
|
||||
# Core development tools
|
||||
git = "latest"
|
||||
vim = "latest"
|
||||
curl = "latest"
|
||||
wget = "latest"
|
||||
# List of packages to install using dnf
|
||||
# Set to true to install, false or comment out to skip
|
||||
git = true
|
||||
vim = true
|
||||
curl = true
|
||||
wget = true
|
||||
|
||||
# Additional packages can be added with version specifications
|
||||
# Example: package_name = "version" or "latest"
|
||||
[dotfiles]
|
||||
# Dotfiles to manage with symlinks
|
||||
# Format: "target_path" = "source_path"
|
||||
# target_path: where the symlink should be created (relative to home directory)
|
||||
# source_path: where the actual file is stored (relative to forge directory)
|
||||
".bashrc" = "dotfiles/.bashrc"
|
||||
".config/vimrc" = "dotfiles/vimrc"
|
||||
".config/alacritty/alacritty.yml" = "dotfiles/alacritty.yml"
|
||||
|
||||
[options]
|
||||
# Additional options
|
||||
backup = true
|
||||
backup_dir = "backup"
|
||||
```
|
||||
|
||||
### dotfiles directory
|
||||
Place your dotfiles in `~/.config/fedora-home-manager/dotfiles/` maintaining the same directory structure as in your home:
|
||||
### Configuration Sections
|
||||
|
||||
#### `[forge]`
|
||||
- `version`: Configuration file version
|
||||
- `last_switch`: Timestamp of last switch operation (auto-updated)
|
||||
|
||||
#### `[packages]`
|
||||
List of packages to install via dnf. Set to `true` to install, `false` or comment out to skip.
|
||||
|
||||
#### `[dotfiles]`
|
||||
Dotfile mappings using symlinks:
|
||||
- **Key**: Target path where symlink should be created (relative to home directory)
|
||||
- **Value**: Source path where actual file is stored (relative to forge directory)
|
||||
|
||||
#### `[options]`
|
||||
Additional configuration options:
|
||||
- `backup`: Enable/disable backup of existing files (default: true)
|
||||
- `backup_dir`: Directory name for backups (relative to forge directory)
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
~/.config/fedora-home-manager/dotfiles/
|
||||
├── .bashrc
|
||||
├── .vimrc
|
||||
└── .config/
|
||||
└── alacritty/
|
||||
└── alacritty.yml
|
||||
~/.config/forge/
|
||||
├── forge.toml # Main configuration file
|
||||
├── dotfiles/ # Your actual dotfiles (source files)
|
||||
│ ├── .bashrc
|
||||
│ ├── vimrc
|
||||
│ └── alacritty.yml
|
||||
└── backup/ # Backups of replaced files
|
||||
├── .bashrc.20231121_143022.bak
|
||||
└── vimrc.20231121_143022.bak
|
||||
```
|
||||
|
||||
### state.json
|
||||
Internal state tracking file (managed automatically):
|
||||
- Tracks installed packages for cleanup
|
||||
- Records last switch timestamp
|
||||
- Maintains list of managed files
|
||||
## How It Works
|
||||
|
||||
## Features
|
||||
### Dotfile Management
|
||||
Forge uses symlinks to manage dotfiles:
|
||||
1. Your actual dotfiles are stored in `~/.config/forge/dotfiles/`
|
||||
2. Symlinks are created from your home directory to these files
|
||||
3. This allows you to version control your dotfiles in one place
|
||||
4. Changes to the source files are immediately reflected in your home directory
|
||||
|
||||
### Automatic Package Cleanup
|
||||
When you remove a package from `packages.toml` and run `switch`, the package will be automatically uninstalled from your system.
|
||||
|
||||
### Package State Tracking
|
||||
Previously installed packages are tracked to enable cleanup operations.
|
||||
|
||||
### TOML Format Support
|
||||
Packages are managed in TOML format for better organization and version support.
|
||||
### Package Management
|
||||
Packages are managed through the `[packages]` section in `forge.toml`:
|
||||
- Packages set to `true` are installed via `dnf`
|
||||
- Packages set to `false` or commented out are ignored
|
||||
- No automatic uninstallation (unlike the previous version)
|
||||
|
||||
### 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)
|
||||
Before creating symlinks, Forge:
|
||||
1. Checks if the target file exists and is not a symlink
|
||||
2. Creates a timestamped backup in the backup directory
|
||||
3. Removes the original file
|
||||
4. Creates the symlink to your managed dotfile
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Setup
|
||||
```bash
|
||||
# Initialize
|
||||
# Initialize forge
|
||||
./forge init
|
||||
|
||||
# Add your shell configuration
|
||||
./forge add ~/.bashrc
|
||||
./forge add ~/.bash_profile
|
||||
# Create your dotfiles directory and add files
|
||||
mkdir -p ~/.config/forge/dotfiles
|
||||
echo "export EDITOR=vim" > ~/.config/forge/dotfiles/.bashrc
|
||||
|
||||
# Add development tools
|
||||
cat >> ~/.config/fedora-home-manager/packages.toml << 'EOF'
|
||||
git = "latest"
|
||||
vim = "latest"
|
||||
nodejs = "latest"
|
||||
npm = "latest"
|
||||
EOF
|
||||
# Edit forge.toml to configure
|
||||
nano ~/.config/forge/forge.toml
|
||||
|
||||
# Add to [packages] section:
|
||||
git = true
|
||||
vim = true
|
||||
|
||||
# Add to [dotfiles] section:
|
||||
".bashrc" = "dotfiles/.bashrc"
|
||||
|
||||
# Apply configuration
|
||||
./forge switch
|
||||
```
|
||||
|
||||
### Managing Configuration Files
|
||||
### Managing Application Configurations
|
||||
```bash
|
||||
# Add application configurations
|
||||
./forge add ~/.config/alacritty/alacritty.yml
|
||||
./forge add ~/.config/git/config
|
||||
./forge add ~/.config/nvim/init.vim
|
||||
# Add alacritty configuration
|
||||
mkdir -p ~/.config/forge/dotfiles/.config/alacritty
|
||||
cp ~/.config/alacritty/alacritty.yml ~/.config/forge/dotfiles/.config/alacritty/
|
||||
|
||||
# Check what's managed
|
||||
./forge list
|
||||
# Edit forge.toml
|
||||
nano ~/.config/forge/forge.toml
|
||||
|
||||
# Add to [dotfiles] section:
|
||||
".config/alacritty/alacritty.yml" = "dotfiles/.config/alacritty/alacritty.yml"
|
||||
|
||||
# Apply changes
|
||||
./forge switch
|
||||
```
|
||||
|
||||
### Removing Packages
|
||||
### Version Control Your Configuration
|
||||
```bash
|
||||
# Edit packages.toml and remove entries for packages you don't want
|
||||
# Then run switch to uninstall them
|
||||
./forge switch
|
||||
# Initialize git repository in forge directory
|
||||
cd ~/.config/forge
|
||||
git init
|
||||
git add .
|
||||
git commit -m "Initial configuration"
|
||||
|
||||
# Now you can version control your entire system configuration
|
||||
git add forge.toml dotfiles/
|
||||
git commit -m "Updated vim configuration"
|
||||
```
|
||||
|
||||
## File Structure
|
||||
## Environment Variables
|
||||
|
||||
```
|
||||
~/.config/fedora-home-manager/
|
||||
├── dotfiles/ # Your dotfiles to deploy
|
||||
├── packages.toml # TOML file with packages to install
|
||||
├── state.json # State tracking
|
||||
└── backup/ # Backups of replaced files
|
||||
```
|
||||
- `FORGE_DIR`: Override the default configuration directory (default: `~/.config/forge`)
|
||||
|
||||
## Dependencies
|
||||
|
||||
- `dnf` - Fedora package manager
|
||||
- `sed` - For updating configuration file (usually pre-installed)
|
||||
|
||||
## Migration from Previous Version
|
||||
|
||||
If you were using the old version of forge:
|
||||
|
||||
1. Your existing configuration will not be automatically migrated
|
||||
2. Run `./forge init` to create the new `forge.toml` structure
|
||||
3. Manually migrate your packages and dotfile configurations to the new TOML format
|
||||
4. Move your existing dotfiles from the old directory to `~/.config/forge/dotfiles/`
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue