Rewrite README with accurate docs
This commit is contained in:
AI Bot
Riyyi
@@ -1,18 +1,14 @@
|
||||
# declpac
|
||||
|
||||
`declpac` is a declarative package manager for Arch Linux that syncs your system
|
||||
with a declared package list using `pacman`. It ensures your system matches your
|
||||
desired state, handling package installation, upgrades, and orphan cleanup
|
||||
automatically.
|
||||
Declarative package manager for Arch Linux that syncs your system with a declared package list using pacman.
|
||||
|
||||
## Features
|
||||
|
||||
- **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
|
||||
- **Explicit package tracking** — Marks your declared packages as explicit
|
||||
- **AUR support** — Falls back to AUR for packages not in official repos
|
||||
- **Machine-readable output** — Perfect for scripting and automation
|
||||
- Declarative state management — define your desired package list in files or stdin
|
||||
- Smart orphan cleanup — removes packages no longer needed
|
||||
- Explicit package tracking — marks declared packages as explicit
|
||||
- AUR support — builds and installs AUR packages automatically
|
||||
- Machine-readable output — perfect for scripting
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -28,14 +24,13 @@ sudo mv declpac /usr/local/bin/
|
||||
### Dependencies
|
||||
|
||||
- Go 1.21+
|
||||
- pacman (system package manager)
|
||||
- aur (AUR helper, optional for AUR support)
|
||||
- Root privileges (required for pacman operations)
|
||||
- pacman
|
||||
- makepkg (for AUR support)
|
||||
- git (for AUR support)
|
||||
- Root privileges
|
||||
|
||||
## Usage
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Single state file
|
||||
sudo declpac --state packages.txt
|
||||
@@ -45,119 +40,63 @@ sudo declpac --state base.txt --state apps.txt
|
||||
|
||||
# From stdin
|
||||
cat packages.txt | sudo declpac
|
||||
|
||||
# Preview changes without applying
|
||||
sudo declpac --dry-run --state packages.txt
|
||||
```
|
||||
|
||||
### State File Format
|
||||
|
||||
State files contain one package name per line:
|
||||
One package name per line, lines beginning with `#` are comments:
|
||||
|
||||
```
|
||||
bash
|
||||
vim
|
||||
git
|
||||
docker
|
||||
# this is a comment
|
||||
```
|
||||
|
||||
Lines are treated as package names with whitespace trimmed:
|
||||
|
||||
```
|
||||
bash # bash
|
||||
vim # vim
|
||||
# comment # ignored
|
||||
```
|
||||
|
||||
### Command Line Options
|
||||
### Options
|
||||
|
||||
| Flag | Alias | Description |
|
||||
|------|-------|-------------|
|
||||
| `--state` | `-s` | State file(s) to read package list from (can be used multiple times) |
|
||||
| `--yes` | `-y` | Skip confirmation prompts (for scripting) |
|
||||
| `--dry-run` | | Simulate sync without making changes |
|
||||
| `--state` | `-s` | State file to read package list from (can be used multiple times) |
|
||||
| `--dry-run` | | Preview changes without applying them |
|
||||
| `--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
|
||||
|
||||
1. **Collect packages** — Reads from all `--state` files and stdin
|
||||
2. **Merge** — Combines all packages additively (duplicates allowed)
|
||||
3. **Validate** — Checks packages exist in repos or AUR
|
||||
4. **Mark explicit** — Marks declared packages as explicit dependencies
|
||||
5. **Sync** — Runs `pacman -Syu` to install/upgrade packages
|
||||
6. **Cleanup** — Removes orphaned packages with `pacman -Rns`
|
||||
7. **Report** — Outputs summary: `Installed X packages, removed Y packages`
|
||||
1. **Read** — Collect packages from all state files and stdin
|
||||
2. **Merge** — Combine into single package list
|
||||
3. **Categorize** — Check if packages are in official repos or AUR
|
||||
4. **Sync** — Install/update packages via pacman
|
||||
5. **Build** — Build and install AUR packages via makepkg
|
||||
6. **Mark** — Mark declared packages as explicit, all others as dependencies
|
||||
7. **Cleanup** — Remove orphaned packages
|
||||
|
||||
### 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:
|
||||
- Not explicitly installed
|
||||
- Not required by any other package
|
||||
Operations are logged to `/var/log/declpac.log`.
|
||||
|
||||
This keeps your system clean from dependency artifacts.
|
||||
|
||||
## Output Format
|
||||
## Output
|
||||
|
||||
```
|
||||
# Success (packages installed/removed)
|
||||
# Packages installed/removed
|
||||
Installed 5 packages, removed 2 packages
|
||||
|
||||
# Success (no changes)
|
||||
# No changes needed
|
||||
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: package not found: <package-name>
|
||||
```
|
||||
@@ -167,36 +106,54 @@ error: package not found: <package-name>
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 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
|
||||
- **Review state files** — Only install packages from trusted sources
|
||||
- **Backup** — Consider backing up your system before major changes
|
||||
### Minimal System
|
||||
|
||||
```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
|
||||
|
||||
### "Permission denied"
|
||||
|
||||
`declpac` requires root privileges. Use `sudo`:
|
||||
### Permission denied
|
||||
|
||||
Use sudo:
|
||||
```bash
|
||||
sudo declpac --state packages.txt
|
||||
```
|
||||
|
||||
### "Package not found"
|
||||
|
||||
The package doesn't exist in pacman repos or AUR. Check the package name:
|
||||
### Package not found
|
||||
|
||||
Check if the package exists:
|
||||
```bash
|
||||
pacman -Ss <package>
|
||||
```
|
||||
|
||||
### Database sync fails
|
||||
|
||||
Refresh manually:
|
||||
|
||||
```bash
|
||||
sudo pacman -Syy
|
||||
```
|
||||
@@ -210,11 +167,12 @@ declpac/
|
||||
├── pkg/
|
||||
│ ├── input/ # State file/stdin reading
|
||||
│ ├── merge/ # Package merging
|
||||
│ ├── validation/ # Package validation
|
||||
│ ├── pacman/ # Pacman integration
|
||||
│ └── output/ # Output formatting
|
||||
├── go.mod # Go module
|
||||
└── README.md # This file
|
||||
│ ├── fetch/ # Package resolution (pacman/AUR)
|
||||
│ ├── pacman/ # Pacman operations
|
||||
│ ├── validation/ # Database freshness check
|
||||
│ ├── output/ # Output formatting
|
||||
│ └── state/ # Logging
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Reference in New Issue
Block a user