riyyi/declpac
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Rewrite README with accurate docs

Browse Source
This commit is contained in:
AI Bot
2026-04-15 22:51:30 +02:00
committed by Riyyi
parent 1c74373d6b
commit 192b41e18b
1 changed files with 74 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+74 -116
View File
@@ -1,18 +1,14 @@
# declpac # declpac
`declpac` is a declarative package manager for Arch Linux that syncs your system Declarative package manager for Arch Linux that syncs your system with a declared package list using pacman.
with a declared package list using `pacman`. It ensures your system matches your
desired state, handling package installation, upgrades, and orphan cleanup
automatically.
## Features ## Features
- **Declarative state management** — Define your desired package list in files or stdin - Declarative state management — define your desired package list in files or stdin
- **Automatic dependency resolution** — Pacman handles transitive dependencies - Smart orphan cleanup — removes packages no longer needed
- **Smart orphan cleanup** — Removes packages no longer needed - Explicit package tracking — marks declared packages as explicit
- **Explicit package tracking** — Marks your declared packages as explicit - AUR support — builds and installs AUR packages automatically
- **AUR support** — Falls back to AUR for packages not in official repos - Machine-readable output — perfect for scripting
- **Machine-readable output** — Perfect for scripting and automation
## Installation ## Installation
@@ -28,14 +24,13 @@ sudo mv declpac /usr/local/bin/
### Dependencies ### Dependencies
- Go 1.21+ - Go 1.21+
- pacman (system package manager) - pacman
- aur (AUR helper, optional for AUR support) - makepkg (for AUR support)
- Root privileges (required for pacman operations) - git (for AUR support)
- Root privileges
## Usage ## Usage
### Basic Usage
```bash ```bash
# Single state file # Single state file
sudo declpac --state packages.txt sudo declpac --state packages.txt
@@ -45,119 +40,63 @@ sudo declpac --state base.txt --state apps.txt
# From stdin # From stdin
cat packages.txt | sudo declpac cat packages.txt | sudo declpac
# Preview changes without applying
sudo declpac --dry-run --state packages.txt
``` ```
### State File Format ### State File Format
State files contain one package name per line: One package name per line, lines beginning with `#` are comments:
``` ```
bash bash
vim vim
git git
docker docker
# this is a comment
``` ```
Lines are treated as package names with whitespace trimmed: ### Options
```
bash # bash
vim # vim
# comment # ignored
```
### Command Line Options
| Flag | Alias | Description | | Flag | Alias | Description |
|------|-------|-------------| |------|-------|-------------|
| `--state` | `-s` | State file(s) to read package list from (can be used multiple times) | | `--state` | `-s` | State file to read package list from (can be used multiple times) |
| `--yes` | `-y` | Skip confirmation prompts (for scripting) | | `--dry-run` | | Preview changes without applying them |
| `--dry-run` | | Simulate sync without making changes |
| `--help` | `-h` | Show help message | | `--help` | `-h` | Show help message |
### Examples
#### Minimal System
```bash
# Create a minimal system package list
echo -e "base\nbase-devel\nlinux-headers\nvim\ngit\ncurl\nwget" > ~/.config/declpac/minimal.txt
# Apply the state
sudo declpac --state ~/.config/declpac/minimal.txt
```
#### Development Environment
```bash
# development.txt
go
nodejs
python
rust
docker
docker-compose
kubectl
helm
terraform
# Apply
sudo declpac --state development.txt
```
#### Full System Sync
```bash
# Combine multiple files
sudo declpac --state ~/.config/declpac/base.txt --state ~/.config/declpac/desktop.txt
# Or use stdin
cat ~/.config/declpac/full-system.txt | sudo declpac
```
#### Dry-Run Preview
```bash
# Preview what would happen without making changes
sudo declpac --dry-run --state packages.txt
# Example output:
# Installed 3 packages, removed 2 packages
# Would install: vim, git, docker
# Would remove: python2, perl-xml-parser
```
## How It Works ## How It Works
1. **Collect packages** — Reads from all `--state` files and stdin 1. **Read** — Collect packages from all state files and stdin
2. **Merge** — Combines all packages additively (duplicates allowed) 2. **Merge** — Combine into single package list
3. **Validate** — Checks packages exist in repos or AUR 3. **Categorize** — Check if packages are in official repos or AUR
4. **Mark explicit** — Marks declared packages as explicit dependencies 4. **Sync** — Install/update packages via pacman
5. **Sync** — Runs `pacman -Syu` to install/upgrade packages 5. **Build** — Build and install AUR packages via makepkg
6. **Cleanup** — Removes orphaned packages with `pacman -Rns` 6. **Mark** — Mark declared packages as explicit, all others as dependencies
7. **Report** — Outputs summary: `Installed X packages, removed Y packages` 7. **Cleanup** — Remove orphaned packages
### Database Freshness ### Database Freshness
If the pacman database is older than 24 hours, `declpac` automatically refreshes it with `pacman -Syy` before validation. If the pacman database is older than 24 hours, it is automatically refreshed.
### Orphan Cleanup ### Logging
After syncing, `declpac` identifies and removes packages that are: Operations are logged to `/var/log/declpac.log`.
- Not explicitly installed
- Not required by any other package
This keeps your system clean from dependency artifacts. ## Output
## Output Format
``` ```
# Success (packages installed/removed) # Packages installed/removed
Installed 5 packages, removed 2 packages Installed 5 packages, removed 2 packages
# Success (no changes) # No changes needed
Installed 0 packages, removed 0 packages Installed 0 packages, removed 0 packages
# Dry-run preview
Installed 3 packages, removed 1 packages
Would install: vim, git, docker
Would remove: python2
# Error # Error
error: package not found: <package-name> error: package not found: <package-name>
``` ```
@@ -167,36 +106,54 @@ error: package not found: <package-name>
| Code | Meaning | | Code | Meaning |
|------|---------| |------|---------|
| 0 | Success | | 0 | Success |
| 1 | Error (no packages, validation failure, pacman error) | | 1 | Error |
## Security Considerations ## Examples
- **Run as root** — `declpac` requires root privileges for pacman operations ### Minimal System
- **Review state files** — Only install packages from trusted sources
- **Backup** — Consider backing up your system before major changes ```bash
echo -e "base\nbase-devel\nlinux-headers\nvim\ngit\ncurl" > ~/.config/declpac/minimal.txt
sudo declpac --state ~/.config/declpac/minimal.txt
```
### Development Environment
```bash
# development.txt
go
nodejs
python
rust
docker
sudo declpac --state development.txt
```
### Dry-Run
```bash
sudo declpac --dry-run --state packages.txt
```
## Troubleshooting ## Troubleshooting
### "Permission denied" ### Permission denied
`declpac` requires root privileges. Use `sudo`:
Use sudo:
```bash ```bash
sudo declpac --state packages.txt sudo declpac --state packages.txt
``` ```
### "Package not found" ### Package not found
The package doesn't exist in pacman repos or AUR. Check the package name:
Check if the package exists:
```bash ```bash
pacman -Ss <package> pacman -Ss <package>
``` ```
### Database sync fails ### Database sync fails
Refresh manually:
```bash ```bash
sudo pacman -Syy sudo pacman -Syy
``` ```
@@ -210,13 +167,14 @@ declpac/
├── pkg/ ├── pkg/
│ ├── input/ # State file/stdin reading │ ├── input/ # State file/stdin reading
│ ├── merge/ # Package merging │ ├── merge/ # Package merging
│ ├── validation/ # Package validation │ ├── fetch/ # Package resolution (pacman/AUR)
│ ├── pacman/ # Pacman integration │ ├── pacman/ # Pacman operations
│ └── output/ # Output formatting │ ├── validation/ # Database freshness check
├── go.mod # Go module │ ├── output/ # Output formatting
└── README.md # This file │ └── state/ # Logging
└── README.md
``` ```
## License ## License
GPL-3.0 GPL-3.0