randogoth/curator
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

init

Browse source
This commit is contained in:
randogoth 2025-12-24 07:56:11 +02:00
parent 359c250101
commit da6d24c74f
13 changed files with 973 additions and 555 deletions
Download patch file Download diff file Expand all files Collapse all files

206
README.md
View file

@ -1,10 +1,10 @@
# Forge - A Home-Manager Like Tool for Fedora
A lightweight configuration management tool for Fedora that provides COPR repository management, dotfile management and package installation functionality through a centralized TOML configuration.
A lightweight Python CLI (managed with `uv`) for Fedora that provides COPR repository management, dotfile management and package installation functionality through a centralized TOML configuration.
## Overview
Forge is a bash script that helps you manage your Fedora system configuration by:
Forge is a Python CLI that helps you manage your Fedora system configuration by:
- Managing COPR repositories (enable/disable automatically)
- Installing and managing system packages via dnf
- Managing dotfiles through symlinks to actual files
@ -14,39 +14,50 @@ Forge is a bash script that helps you manage your Fedora system configuration by
## Installation
1. Clone or download this repository
2. Make the script executable:
1. Clone or download this repository.
2. Install dependencies with `uv` (none beyond the standard library, but this sets up the venv):
```bash
chmod +x forge
uv sync
```
3. Optionally, move it to a directory in your PATH:
3. Run with `uv`:
```bash
sudo mv forge /usr/local/bin/forge
uv run forge --help
```
4. Or use the local shim directly:
```bash
./forge --help
```
5. Optionally install globally via `uv`:
```bash
uv tool install .
```
## Quick Start
```bash
# Initialize the configuration structure
./forge init
uv run forge init
# Edit the configuration file to add packages and dotfiles
nano ~/.config/forge/forge.toml
# Apply configuration
./forge switch
uv run forge switch
# Check status
./forge status
uv run forge status
```
You can swap `uv run forge ...` for `./forge ...` if you prefer the local shim.
## Commands
### `init`
Initialize the configuration structure and create `forge.toml`.
```bash
./forge init
uv run forge init
# or ./forge init
```
Creates:
@ -57,7 +68,8 @@ Creates:
Apply the current configuration (enable COPR, install packages, deploy dotfiles).
```bash
./forge switch
uv run forge switch
# or ./forge switch
```
This command:
@ -72,7 +84,8 @@ This command:
Show current configuration status and information.
```bash
./forge status
uv run forge status
# or ./forge status
```
Displays:
@ -84,7 +97,8 @@ Displays:
Show help message with all available commands.
```bash
./forge help
uv run forge help
# or ./forge help
```
## Configuration
@ -96,23 +110,21 @@ The central configuration file located at `~/.config/forge/forge.toml`:
# Forge Configuration File
# User-level configuration similar to home-manager/nixos
copr = [
# "copr.fedorainfracloud.org/username/repository",
# "copr.fedorainfracloud.org/anotheruser/anotherrepo",
]
packages = [
# "git",
# "vim",
# "curl",
# "wget",
]
[forge]
version = "1.0"
last_switch = null
[copr]
# COPR repositories to enable
# Just list COPR repository names - presence means enable, absence means don't enable
copr.fedorainfracloud.org/username/repository
copr.fedorainfracloud.org/anotheruser/anotherrepo
[packages]
# List of packages to install using dnf
# Just list package names - presence means install, absence means don't install
git
vim
curl
wget
last_switch = ""
[dotfiles]
# Dotfiles to manage with symlinks
@ -135,30 +147,32 @@ backup_dir = "backup"
- `version`: Configuration file version
- `last_switch`: Timestamp of last switch operation (auto-updated)
#### `[copr]`
List of COPR repositories to enable via `dnf copr enable`. **Just list COPR repository names** - presence means enable, absence means don't enable.
#### `copr`
Array of COPR repositories to enable via `dnf copr enable`. **Just list COPR repository names** - presence means enable, absence means don't enable.
**Examples:**
```toml
[copr]
copr.fedorainfracloud.org/username/repository
copr.fedorainfracloud.org/anotheruser/anotherrepo
copr = [
"copr.fedorainfracloud.org/username/repository",
"copr.fedorainfracloud.org/anotheruser/anotherrepo",
]
```
To remove a COPR repository, simply delete the line containing the repository name. Forge will automatically disable it during the next switch.
#### `[packages]`
List of packages to install via dnf. **Just list package names** - presence means install, absence means don't install.
#### `packages`
Array of packages to install via dnf. **Just list package names** - presence means install, absence means don't install.
**Examples:**
```toml
[packages]
git
vim
curl
wget
nodejs
npm
packages = [
"git",
"vim",
"curl",
"wget",
"nodejs",
"npm",
]
```
To remove a package, simply delete the line containing the package name.
@ -191,17 +205,19 @@ Additional configuration options:
## How It Works
### COPR Repository Management
COPR repositories are managed through the `[copr]` section in `forge.toml`:
- **Add COPR repo**: Simply add the repository name on a new line
- **Remove COPR repo**: Delete the line containing the repository name
COPR repositories are managed through the `copr` array in `forge.toml`:
- **Add COPR repo**: Add the repository name to the array
- **Remove COPR repo**: Remove the entry from the array
- **Automatic cleanup**: Forge automatically disables COPR repos that are removed from configuration
- **No flags needed**: Just presence/absence of the repository name matters
- Forge stores the previous configuration at `~/.config/forge/forge.toml.prev` and compares it to the current file during `switch`; newly added repos are enabled, removed repos are disabled.
### Package Management
Packages are managed through the `[packages]` section in `forge.toml`:
- **Add package**: Simply add the package name on a new line
- **Remove package**: Delete the line containing the package name
Packages are managed through the `packages` array in `forge.toml`:
- **Add package**: Add the package name to the array
- **Remove package**: Remove the entry from the array
- **No flags needed**: Just presence/absence of the package name matters
- The previous configuration snapshot (`forge.toml.prev`) is used to detect additions/removals on each `switch`; added packages are installed and removed packages are uninstalled.
### Dotfile Management
Forge uses symlinks to manage dotfiles:
@ -218,23 +234,29 @@ Before creating symlinks, Forge:
3. Removes the original file
4. Creates the symlink to your managed dotfile
`forge.toml` is also backed up before the last switch timestamp is updated.
The previously applied configuration is stored separately as `~/.config/forge/forge.toml.prev` to compute diffs for COPR and package changes.
## Examples
### Basic Setup
```bash
# Initialize forge
./forge init
uv run forge init
# Edit forge.toml to add COPR repos and packages
nano ~/.config/forge/forge.toml
# Add to [copr] section:
copr.fedorainfracloud.org/username/cool-repo
# Add to [packages] section:
git
vim
curl
# Add to the arrays:
# copr = [
# "copr.fedorainfracloud.org/username/cool-repo",
# ]
# packages = [
# "git",
# "vim",
# "curl",
# ]
# Create your dotfiles directory and add files
mkdir -p ~/.config/forge/dotfiles
@ -244,7 +266,7 @@ echo "export EDITOR=vim" > ~/.config/forge/dotfiles/.bashrc
".bashrc" = ".bashrc"
# Apply configuration
./forge switch
uv run forge switch
```
### Managing Application Configurations
@ -260,37 +282,36 @@ nano ~/.config/forge/forge.toml
".config/alacritty/alacritty.yml" = "alacritty.yml"
# Apply changes
./forge switch
uv run forge switch
```
### COPR Repository Management Examples
```toml
[copr]
# Development tools COPR
copr.fedorainfracloud.org/development/tools
copr.fedorainfracloud.org/user/neovim-nightly
# To remove a COPR repo, just delete the line
copr = [
# Development tools COPR
"copr.fedorainfracloud.org/development/tools",
"copr.fedorainfracloud.org/user/neovim-nightly",
]
# To remove a COPR repo, just delete the entry
# Forge will automatically disable it during the next switch
```
### Package Management Examples
```toml
[packages]
# Development tools
git
vim
nodejs
npm
packages = [
# Development tools
"git",
"vim",
"nodejs",
"npm",
# System utilities
curl
wget
tree
htop
# To remove a package, just delete the line
# For example, to remove htop, delete the "htop" line
# System utilities
"curl",
"wget",
"tree",
"htop",
]
# To remove a package, just delete the entry
```
### Version Control Your Configuration
@ -312,30 +333,35 @@ git commit -m "Updated vim configuration"
## Dependencies
- Python 3.11+
- `tomlkit` (installed automatically via `uv sync`)
- `uv` for environment and script management
- `dnf` - Fedora package manager
- `dnf-plugins-core` - For COPR repository management
- `sed` - For updating configuration file (usually pre-installed)
## Migration from Previous Version
If you were using the old version of forge with `git = true` format:
If you were using the old version of forge with `git = true` or bare keys under `[packages]`/`[copr]`:
1. Your existing configuration will not be automatically migrated
2. Run `./forge init` to create the new `forge.toml` structure
3. Convert your package configuration from:
1. Your existing configuration will not be automatically migrated, but the CLI will still read the legacy format.
2. Run `uv run forge init` (or `./forge init`) to create the new `forge.toml` structure.
3. Convert to arrays:
```toml
# Old format
# Old formats
[packages]
git = true
vim = true
```
to:
```toml
# New format
# or
[packages]
git
vim
# New format
packages = ["git", "vim"]
copr = ["copr.fedorainfracloud.org/username/repository"]
```
4. Move your existing dotfiles from the old directory to `~/.config/forge/dotfiles/`
## License
This project is open source. Feel free to contribute or report issues.
This project is open source. Feel free to contribute or report issues.