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

Rewrite README with accurate docs

master
AI Bot 3 days ago committed by Riyyi
parent
1c74373d6b
commit
192b41e18b
1 changed files with 74 additions and 116 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 190
      README.md

190
README.md
Unescape 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
After syncing, `declpac` identifies and removes packages that are: ### Logging
- Not explicitly installed
- Not required by any other package
This keeps your system clean from dependency artifacts. Operations are logged to `/var/log/declpac.log`.
## Output Format ## Output
``` ```
# 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
## Troubleshooting ```bash
echo -e "base\nbase-devel\nlinux-headers\nvim\ngit\ncurl" > ~/.config/declpac/minimal.txt
sudo declpac --state ~/.config/declpac/minimal.txt
```
### "Permission denied" ### Development Environment
`declpac` requires root privileges. Use `sudo`: ```bash
# development.txt
go
nodejs
python
rust
docker
sudo declpac --state development.txt
```
### Dry-Run
```bash ```bash
sudo declpac --state packages.txt sudo declpac --dry-run --state packages.txt
``` ```
### "Package not found" ## Troubleshooting
The package doesn't exist in pacman repos or AUR. Check the package name: ### Permission denied
Use sudo:
```bash
sudo declpac --state packages.txt
```
### Package not found
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
Write Preview
Loading…
Cancel
Save