finalized for publication
This commit is contained in:
randogoth
parent
df1f387795
commit
7d51de1052
4 changed files with 626 additions and 392 deletions
287
README.md
287
README.md
|
|
@ -1,62 +1,49 @@
|
|||
# curator - A Home-Manager Like Tool for Fedora
|
||||
# curator - A Home-Manager Like Tool for Universal Blue builds
|
||||
|
||||
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.
|
||||
A lightweight CLI that provides repository and dotfile management and package installation functionality through a centralized TOML configuration. Ported and expanded from [forge](https://github.com/ijadux2/forge) and inspired by [home-manager](https://github.com/nix-community/home-manager/).
|
||||
|
||||
## Overview
|
||||
|
||||
curator 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
|
||||
- Installing and managing system packages via `dnf` or `rpm-ostree`
|
||||
- Installing and managing userspace packages via `brew`, `flatpak`, or `nix`
|
||||
- Managing dotfiles through symlinks to actual files
|
||||
- Centralized configuration via a single `inventory.toml` file
|
||||
- User-level configuration similar to home-manager/nixos
|
||||
- Declarative user-level configuration similar to `home-manager`/`nixos`
|
||||
- Automatic backup of existing files before replacement
|
||||
|
||||
## Installation
|
||||
|
||||
1. Clone or download this repository.
|
||||
2. Install dependencies with `uv` (none beyond the standard library, but this sets up the venv):
|
||||
```bash
|
||||
uv sync
|
||||
```
|
||||
3. Run with `uv`:
|
||||
```bash
|
||||
uv run curator --help
|
||||
```
|
||||
4. Or use the local shim directly:
|
||||
```bash
|
||||
./curator --help
|
||||
```
|
||||
5. Optionally install globally via `uv`:
|
||||
```bash
|
||||
uv tool install .
|
||||
```
|
||||
Install the CLI directly from GitHub with [uv](https://github.com/astral-sh/uv):
|
||||
|
||||
```bash
|
||||
uv tool install --from git+https://codeberg.org/randogoth/curator/ curator
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Initialize the configuration structure
|
||||
uv run curator init
|
||||
curator init
|
||||
|
||||
# Edit the configuration file to add packages and dotfiles
|
||||
nano ~/.config/curator/inventory.toml
|
||||
|
||||
# Apply configuration
|
||||
uv run curator switch
|
||||
curator switch
|
||||
|
||||
# Check status
|
||||
uv run curator status
|
||||
curator status
|
||||
```
|
||||
|
||||
You can swap `uv run curator ...` for `./curator ...` if you prefer the local shim.
|
||||
|
||||
## Commands
|
||||
|
||||
### `init`
|
||||
Initialize the configuration structure and create `inventory.toml`.
|
||||
|
||||
```bash
|
||||
uv run curator init
|
||||
curator init
|
||||
# or ./curator init
|
||||
```
|
||||
|
||||
|
|
@ -68,10 +55,10 @@ Creates:
|
|||
Apply the current configuration (enable COPR, install packages, deploy dotfiles). Use `--rollback` to restore the previous `inventory.toml` snapshot before applying.
|
||||
|
||||
```bash
|
||||
uv run curator switch
|
||||
curator switch
|
||||
# or ./curator switch
|
||||
# rollback to the previous inventory.toml and apply it
|
||||
uv run curator switch --rollback
|
||||
curator switch --rollback
|
||||
```
|
||||
|
||||
This command:
|
||||
|
|
@ -86,7 +73,7 @@ This command:
|
|||
Show current configuration status and information.
|
||||
|
||||
```bash
|
||||
uv run curator status
|
||||
curator status
|
||||
# or ./curator status
|
||||
```
|
||||
|
||||
|
|
@ -99,10 +86,37 @@ Displays:
|
|||
Show help message with all available commands.
|
||||
|
||||
```bash
|
||||
uv run curator help
|
||||
curator help
|
||||
# or ./curator help
|
||||
```
|
||||
|
||||
### `from`
|
||||
Import currently installed packages/repos for a manager into `inventory.toml` so curator can manage them.
|
||||
|
||||
```bash
|
||||
curator from dnf
|
||||
curator from brew
|
||||
curator from flatpak
|
||||
curator from rpm-ostree
|
||||
curator from nix
|
||||
curator from copr
|
||||
```
|
||||
|
||||
### `add` / `remove`
|
||||
Add or remove entries directly in `inventory.toml` using `section:value` pairs. Supports `dnf`, `brew`, `flatpak`, `rpm-ostree`, `nix`, and `copr`.
|
||||
|
||||
```bash
|
||||
curator add dnf:uv nix:micro
|
||||
curator remove dnf:curl flatpak:org.mozilla.firefox
|
||||
```
|
||||
|
||||
### `reset`
|
||||
Remove the rollback snapshot (`inventory.toml.rollback`).
|
||||
|
||||
```bash
|
||||
curator reset
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### inventory.toml
|
||||
|
|
@ -197,6 +211,12 @@ List of packages to install via Homebrew. **One package per line**—presence me
|
|||
#### `[flatpak]`
|
||||
List of Flatpak refs to install. **One ref per line**—presence means install.
|
||||
|
||||
#### `[rpm-ostree]`
|
||||
List of rpm-ostree layered packages. **One package per line**—presence means install.
|
||||
|
||||
#### `[nix]`
|
||||
List of nix packages. **One package per line**—presence means install. You can specify plain names (e.g., `neovim`) or `nixpkgs#name`; curator will prefix `nixpkgs#` for installs and use the base name for removals.
|
||||
|
||||
#### `[dotfiles]`
|
||||
Dotfile mappings using symlinks:
|
||||
- **Key**: Target path where symlink should be created (relative to home directory)
|
||||
|
|
@ -222,209 +242,6 @@ Additional configuration options:
|
|||
└── vimrc.20231121_143022.bak
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
### COPR Repository Management
|
||||
COPR repositories are managed through the `[copr]` section in `inventory.toml`:
|
||||
- **Add COPR repo**: Add the repository name on its own line
|
||||
- **Remove COPR repo**: Remove the entry
|
||||
- **Automatic cleanup**: curator automatically disables COPR repos that are removed from configuration
|
||||
- **No flags needed**: Just presence/absence of the repository name matters
|
||||
- curator stores the previous configuration at `~/.config/curator/inventory.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 `[dnf]` section in `inventory.toml`:
|
||||
- **Add package**: Add the package name on its own line
|
||||
- **Remove package**: Remove the entry
|
||||
- **No flags needed**: Just presence/absence of the package name matters
|
||||
- The previous configuration snapshot (`inventory.toml.prev`) is used to detect additions/removals on each `switch`; added packages are installed and removed packages are uninstalled.
|
||||
|
||||
### Brew Management
|
||||
Homebrew packages are managed through the `[brew]` section:
|
||||
- **Add package**: Add the package name on its own line
|
||||
- **Remove package**: Remove the entry
|
||||
- Additions/removals are detected against `inventory.toml.prev` on `switch`; removed packages are uninstalled.
|
||||
|
||||
### Flatpak Management
|
||||
Flatpaks are managed through the `[flatpak]` section:
|
||||
- **Add ref**: Add the ref on its own line
|
||||
- **Remove ref**: Remove the entry
|
||||
- Additions/removals are detected against `inventory.toml.prev` on `switch`; removed refs are uninstalled.
|
||||
|
||||
### rpm-ostree Management
|
||||
rpm-ostree packages are managed through the `[rpm-ostree]` section:
|
||||
- **Add package**: Add the package name on its own line
|
||||
- **Remove package**: Remove the entry
|
||||
- Additions/removals are detected against `inventory.toml.prev` on `switch`; removed packages are uninstalled.
|
||||
|
||||
### Nix Management
|
||||
Nix packages are managed through the `[nix]` section (if `nix` is available on the system):
|
||||
- **Add package**: Add the package name (e.g., `nixpkgs#git` or just `git`) on its own line
|
||||
- **Remove package**: Remove the entry
|
||||
- Additions/removals are detected against `inventory.toml.prev` on `switch`; installs/removals use `nix profile` and will prefix `nixpkgs#` if missing.
|
||||
|
||||
### Dotfile Management
|
||||
curator uses symlinks to manage dotfiles:
|
||||
1. Your actual dotfiles are stored in `~/.config/curator/dotfiles/`
|
||||
2. Symlinks are created from your home directory to these files using relative paths
|
||||
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
|
||||
5. Source paths are automatically prefixed with "dotfiles/" for convenience
|
||||
|
||||
### Backup System
|
||||
Before creating symlinks, curator:
|
||||
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
|
||||
|
||||
`inventory.toml` is also backed up before the last switch timestamp is updated.
|
||||
|
||||
The previously applied configuration is stored separately as `~/.config/curator/inventory.toml.prev` to compute diffs for COPR and package changes.
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Setup
|
||||
```bash
|
||||
# Initialize curator
|
||||
uv run curator init
|
||||
|
||||
# Edit inventory.toml to add COPR repos and packages
|
||||
nano ~/.config/curator/inventory.toml
|
||||
|
||||
# Add to the sections:
|
||||
# [copr]
|
||||
# copr.fedorainfracloud.org/username/cool-repo
|
||||
# [dnf]
|
||||
# git
|
||||
# vim
|
||||
# curl
|
||||
# [brew]
|
||||
# wget
|
||||
# [flatpak]
|
||||
# org.mozilla.firefox
|
||||
# [rpm-ostree]
|
||||
# podman
|
||||
# [nix]
|
||||
# nixpkgs#git (or just "git")
|
||||
|
||||
# Create your dotfiles directory and add files
|
||||
mkdir -p ~/.config/curator/dotfiles
|
||||
echo "export EDITOR=vim" > ~/.config/curator/dotfiles/.bashrc
|
||||
|
||||
# Add to [dotfiles] section:
|
||||
".bashrc" = ".bashrc"
|
||||
|
||||
# Apply configuration
|
||||
uv run curator switch
|
||||
```
|
||||
|
||||
### Managing Application Configurations
|
||||
```bash
|
||||
# Add alacritty configuration
|
||||
mkdir -p ~/.config/curator/dotfiles
|
||||
cp ~/.config/alacritty/alacritty.yml ~/.config/curator/dotfiles/
|
||||
|
||||
# Edit inventory.toml
|
||||
nano ~/.config/curator/inventory.toml
|
||||
|
||||
# Add to [dotfiles] section:
|
||||
".config/alacritty/alacritty.yml" = "alacritty.yml"
|
||||
|
||||
# Apply changes
|
||||
uv run curator 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 entry
|
||||
# curator will automatically disable it during the next switch
|
||||
```
|
||||
|
||||
### Package Management Examples
|
||||
```toml
|
||||
[dnf]
|
||||
# Development tools
|
||||
git
|
||||
vim
|
||||
nodejs
|
||||
npm
|
||||
|
||||
# System utilities
|
||||
curl
|
||||
wget
|
||||
tree
|
||||
htop
|
||||
# To remove a package, just delete the entry
|
||||
|
||||
[brew]
|
||||
# Utilities and tools
|
||||
wget
|
||||
coreutils
|
||||
|
||||
[flatpak]
|
||||
org.mozilla.firefox
|
||||
com.spotify.Client
|
||||
|
||||
[rpm-ostree]
|
||||
podman
|
||||
htop
|
||||
```
|
||||
|
||||
### Version Control Your Configuration
|
||||
```bash
|
||||
# Initialize git repository in curator directory
|
||||
cd ~/.config/curator
|
||||
git init
|
||||
git add .
|
||||
git commit -m "Initial configuration"
|
||||
|
||||
# Now you can version control your entire system configuration
|
||||
git add inventory.toml dotfiles/
|
||||
git commit -m "Updated vim configuration"
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
- `CURATOR_DIR`: Override the default configuration directory (default: `~/.config/curator`)
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Python 3.11+
|
||||
- `uv` for environment and script management
|
||||
- `dnf` - Fedora package manager
|
||||
- `dnf-plugins-core` - For COPR repository management
|
||||
|
||||
## Migration from Previous Version
|
||||
|
||||
If you were using the old version of curator with `git = true` or bare keys under `[packages]`/`[copr]`:
|
||||
|
||||
1. Your existing configuration will not be automatically migrated, but the CLI will still read the legacy format.
|
||||
2. Run `uv run curator init` (or `./curator init`) to create the new `inventory.toml` structure.
|
||||
3. Convert to section-per-line format:
|
||||
```toml
|
||||
# Old formats
|
||||
[dnf]
|
||||
git = true
|
||||
vim = true
|
||||
# or
|
||||
[dnf]
|
||||
git
|
||||
vim
|
||||
|
||||
# New format
|
||||
[dnf]
|
||||
git
|
||||
vim
|
||||
[copr]
|
||||
copr.fedorainfracloud.org/username/repository
|
||||
```
|
||||
4. Move your existing dotfiles from the old directory to `~/.config/curator/dotfiles/`
|
||||
|
||||
## License
|
||||
|
||||
This project is open source. Feel free to contribute or report issues.
|
||||
- `CURATOR_DIR`: Override the default configuration directory (default: `~/.config/curator`)
|
||||
Loading…
Add table
Add a link
Reference in a new issue