docs: prepare Pakker documentation
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: I03df3787081bde6ebf0366a24320307a6a6a6964
This commit is contained in:
parent
563ff2b187
commit
5a0a5cedeb
GPG key ID:
29D95B64378DB4BF
4 changed files with 2285 additions and 0 deletions
971
docs/COMMANDS.md
Normal file
971
docs/COMMANDS.md
Normal file
|
|
@ -0,0 +1,971 @@
|
|||
# Pakker Command Reference
|
||||
|
||||
Complete reference for all Pakker commands.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Global Options](#global-options)
|
||||
- [Project Management](#project-management)
|
||||
- [init](#init)
|
||||
- [import](#import)
|
||||
- [add](#add)
|
||||
- [add-prj](#add-prj)
|
||||
- [rm](#rm)
|
||||
- [ls](#ls)
|
||||
- [inspect](#inspect)
|
||||
- [Updates and Sync](#updates-and-sync)
|
||||
- [update](#update)
|
||||
- [fetch](#fetch)
|
||||
- [sync](#sync)
|
||||
- [status](#status)
|
||||
- [Project Configuration](#project-configuration)
|
||||
- [set](#set)
|
||||
- [link](#link)
|
||||
- [unlink](#unlink)
|
||||
- [Export](#export)
|
||||
- [export](#export-1)
|
||||
- [Configuration](#configuration)
|
||||
- [cfg](#cfg)
|
||||
- [credentials](#credentials)
|
||||
- [Remote Management](#remote-management)
|
||||
- [remote](#remote)
|
||||
- [remote-update](#remote-update)
|
||||
- [fork](#fork)
|
||||
- [Utilities](#utilities)
|
||||
- [diff](#diff)
|
||||
|
||||
---
|
||||
|
||||
## Global Options
|
||||
|
||||
All commands support these global flags:
|
||||
|
||||
```bash
|
||||
-v, --verbose # Enable verbose output
|
||||
-vv # Very verbose (debug level)
|
||||
-vvv # Trace level logging
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
pakker -v add sodium # Info logging
|
||||
pakker -vv fetch # Debug logging
|
||||
pakker -vvv export # Trace logging
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Management
|
||||
|
||||
### init
|
||||
|
||||
Initialize a new modpack project in the current directory.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker init [OPTIONS]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `-t, --target <TARGET>` - Target platform (default: multiplatform)
|
||||
- `-m, --mc-version <VERSION>` - Minecraft version (default: 1.20.1)
|
||||
- `-l, --loader <LOADER>` - Mod loader (default: fabric)
|
||||
- `--loader-version <VERSION>` - Specific loader version
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Initialize Fabric 1.20.1 modpack
|
||||
pakker init
|
||||
|
||||
# Initialize Forge 1.19.4 modpack
|
||||
pakker init -m 1.19.4 -l forge
|
||||
|
||||
# Initialize with specific loader version
|
||||
pakker init -l fabric --loader-version 0.15.0
|
||||
|
||||
# Initialize for CurseForge only
|
||||
pakker init --target curseforge
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
Creates:
|
||||
- `pakku.json` - Configuration file
|
||||
- `pakku-lock.json` - Lockfile
|
||||
- `overrides/` - Override directory
|
||||
|
||||
---
|
||||
|
||||
### import
|
||||
|
||||
Import an existing modpack from CurseForge or Modrinth.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker import <SOURCE>
|
||||
```
|
||||
|
||||
**Supported Formats:**
|
||||
|
||||
- CurseForge ZIP files
|
||||
- Modrinth .mrpack files
|
||||
- Local directories with manifest
|
||||
- Remote URLs
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Import from local file
|
||||
pakker import modpack.zip
|
||||
pakker import pack.mrpack
|
||||
|
||||
# Import from URL
|
||||
pakker import https://example.com/modpack.zip
|
||||
|
||||
# Import from directory
|
||||
pakker import ./existing-modpack/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### add
|
||||
|
||||
Interactively add projects to the modpack.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker add <QUERY>...
|
||||
```
|
||||
|
||||
**Features:**
|
||||
|
||||
- Interactive platform selection
|
||||
- Automatic dependency resolution
|
||||
- Fuzzy search with suggestions
|
||||
- Version selection
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Add single project
|
||||
pakker add sodium
|
||||
|
||||
# Add multiple projects
|
||||
pakker add sodium lithium phosphor
|
||||
|
||||
# Add with typo correction
|
||||
pakker add sodum
|
||||
# Suggests: Did you mean "sodium"?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### add-prj
|
||||
|
||||
Add projects non-interactively with explicit platform specification.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker add-prj [OPTIONS] <PROJECT>
|
||||
```
|
||||
|
||||
**Platform Options:**
|
||||
|
||||
- `--cf, --curseforge <ID>` - CurseForge project ID or slug
|
||||
- `--mr, --modrinth <ID>` - Modrinth project ID or slug
|
||||
- `--gh, --github <REPO>` - GitHub repository (format: owner/repo)
|
||||
|
||||
**Property Options:**
|
||||
|
||||
- `--type <TYPE>` - Project type (mod, resourcepack, shader, modpack)
|
||||
- `--side <SIDE>` - Project side (client, server, both)
|
||||
- `--strategy <STRATEGY>` - Update strategy (latest, specific, pinned)
|
||||
- `--version <VERSION>` - Specific version to use
|
||||
- `--redistributable <BOOL>` - Allow redistribution (true/false)
|
||||
- `--subpath <PATH>` - Custom subpath in mods directory
|
||||
- `--alias <NAME>` - Project alias
|
||||
- `--export <BOOL>` - Include in exports (true/false)
|
||||
|
||||
**Control Options:**
|
||||
|
||||
- `--yes, -y` - Skip all confirmations
|
||||
- `--no-deps` - Don't resolve dependencies
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Add from Modrinth
|
||||
pakker add-prj --mr sodium --yes
|
||||
|
||||
# Add from CurseForge
|
||||
pakker add-prj --cf jei --yes
|
||||
|
||||
# Add from multiple platforms (creates unified project)
|
||||
pakker add-prj --mr sodium --cf sodium --yes
|
||||
|
||||
# Add with custom properties
|
||||
pakker add-prj --mr sodium --side client --strategy pinned --yes
|
||||
|
||||
# Add without dependencies (for CI)
|
||||
pakker add-prj --mr fabric-api --yes --no-deps
|
||||
|
||||
# Add with alias
|
||||
pakker add-prj --mr sodium --alias "sodium-mod" --yes
|
||||
|
||||
# Add GitHub release
|
||||
pakker add-prj --gh "IrisShaders/Iris" --yes
|
||||
```
|
||||
|
||||
**CI/CD Usage:**
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Batch add mods
|
||||
mods=(
|
||||
"fabric-api"
|
||||
"sodium"
|
||||
"lithium"
|
||||
"phosphor"
|
||||
)
|
||||
|
||||
for mod in "${mods[@]}"; do
|
||||
pakker add-prj --mr "$mod" --yes --no-deps || exit 1
|
||||
done
|
||||
|
||||
# Resolve all dependencies at once
|
||||
pakker update --yes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### rm
|
||||
|
||||
Remove projects from the modpack.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker rm <PROJECT>...
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Remove single project
|
||||
pakker rm sodium
|
||||
|
||||
# Remove multiple projects
|
||||
pakker rm sodium lithium phosphor
|
||||
|
||||
# Remove with confirmation
|
||||
pakker rm outdated-mod
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ls
|
||||
|
||||
List all projects in the modpack.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker ls [OPTIONS]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--type <TYPE>` - Filter by type
|
||||
- `--side <SIDE>` - Filter by side
|
||||
- `--platform <PLATFORM>` - Filter by platform
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# List all projects
|
||||
pakker ls
|
||||
|
||||
# List only mods
|
||||
pakker ls --type mod
|
||||
|
||||
# List client-only projects
|
||||
pakker ls --side client
|
||||
|
||||
# List CurseForge projects
|
||||
pakker ls --platform curseforge
|
||||
```
|
||||
|
||||
**Output Format:**
|
||||
|
||||
```
|
||||
sodium (v0.5.0) - both - [CF, MR]
|
||||
lithium (v0.11.2) - both - [CF, MR]
|
||||
iris (v1.6.4) - client - [CF, MR]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### inspect
|
||||
|
||||
View detailed information about projects including dependencies.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker inspect [PROJECT]...
|
||||
```
|
||||
|
||||
**Features:**
|
||||
|
||||
- Project metadata (name, version, platforms)
|
||||
- File information (name, size, hashes)
|
||||
- Dependency trees with visualization
|
||||
- Circular dependency detection
|
||||
- Property display
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Inspect single project
|
||||
pakker inspect sodium
|
||||
|
||||
# Inspect multiple projects
|
||||
pakker inspect sodium lithium phosphor
|
||||
|
||||
# View modpack overview (no arguments)
|
||||
pakker inspect
|
||||
|
||||
# Fuzzy matching with suggestions
|
||||
pakker inspect sodum
|
||||
# Suggests: Did you mean "sodium"?
|
||||
```
|
||||
|
||||
**Example Output:**
|
||||
|
||||
```
|
||||
Sodium v0.5.0
|
||||
Type: mod
|
||||
Side: client
|
||||
Platforms: curseforge, modrinth
|
||||
|
||||
Files:
|
||||
sodium-fabric-0.5.0+mc1.20.jar
|
||||
Size: 2.3 MB
|
||||
SHA1: abc123...
|
||||
|
||||
Dependencies:
|
||||
└── fabric-api v0.87.0
|
||||
└── fabric-loader >=0.14.0
|
||||
|
||||
Properties:
|
||||
Redistributable: true
|
||||
Update Strategy: latest
|
||||
Export: true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Updates and Sync
|
||||
|
||||
### update
|
||||
|
||||
Update projects to newer versions.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker update [PROJECT]... [OPTIONS]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--yes, -y` - Skip confirmations
|
||||
- `--all` - Update all projects
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Update specific project
|
||||
pakker update sodium
|
||||
|
||||
# Update multiple projects
|
||||
pakker update sodium lithium
|
||||
|
||||
# Update all projects
|
||||
pakker update --all
|
||||
|
||||
# Update without confirmation (CI)
|
||||
pakker update --all --yes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### fetch
|
||||
|
||||
Download all project files.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker fetch [OPTIONS]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--force` - Re-download existing files
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Fetch all files
|
||||
pakker fetch
|
||||
|
||||
# Force re-download
|
||||
pakker fetch --force
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
```
|
||||
Fetching 42 files...
|
||||
✓ sodium-fabric-0.5.0.jar (local)
|
||||
✓ lithium-fabric-0.11.2.jar (download)
|
||||
✓ fabric-api-0.87.0.jar (download)
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### sync
|
||||
|
||||
Update projects and fetch files in one command.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker sync [OPTIONS]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--yes, -y` - Skip confirmations
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Sync everything
|
||||
pakker sync
|
||||
|
||||
# Sync without confirmation
|
||||
pakker sync --yes
|
||||
```
|
||||
|
||||
Equivalent to:
|
||||
|
||||
```bash
|
||||
pakker update --all --yes
|
||||
pakker fetch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### status
|
||||
|
||||
Check for available updates.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker status
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
pakker status
|
||||
```
|
||||
|
||||
**Example Output:**
|
||||
|
||||
```
|
||||
Updates available:
|
||||
sodium: v0.5.0 → v0.5.1
|
||||
lithium: v0.11.1 → v0.11.2
|
||||
|
||||
No updates:
|
||||
fabric-api (v0.87.0)
|
||||
iris (v1.6.4)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Project Configuration
|
||||
|
||||
### set
|
||||
|
||||
Modify project properties.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker set <PROJECT> [OPTIONS]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--type <TYPE>` - Set project type
|
||||
- `--side <SIDE>` - Set project side
|
||||
- `--strategy <STRATEGY>` - Set update strategy
|
||||
- `--version <VERSION>` - Set specific version (use with strategy=specific)
|
||||
- `--redistributable <BOOL>` - Set redistributable flag
|
||||
- `--subpath <PATH>` - Set custom subpath
|
||||
- `--alias <NAME>` - Set project alias
|
||||
- `--export <BOOL>` - Set export flag
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Change project side
|
||||
pakker set sodium --side client
|
||||
|
||||
# Pin to specific version
|
||||
pakker set fabric-api --strategy specific --version 0.87.0
|
||||
|
||||
# Always update to latest
|
||||
pakker set lithium --strategy latest
|
||||
|
||||
# Never update
|
||||
pakker set custom-mod --strategy pinned
|
||||
|
||||
# Mark as non-redistributable
|
||||
pakker set optifine --redistributable false
|
||||
|
||||
# Don't include in exports
|
||||
pakker set dev-mod --export false
|
||||
|
||||
# Set custom subpath
|
||||
pakker set performance-mod --subpath "mods/performance/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### link
|
||||
|
||||
Link projects together (define relationships).
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker link <PROJECT> <TARGET>
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Link projects
|
||||
pakker link sodium fabric-api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### unlink
|
||||
|
||||
Remove project links.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker unlink <PROJECT> <TARGET>
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Unlink projects
|
||||
pakker unlink sodium fabric-api
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Export
|
||||
|
||||
### export
|
||||
|
||||
Export modpack for distribution.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker export [OPTIONS]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--profile <PROFILE>` - Export profile (curseforge, modrinth, serverpack, or custom)
|
||||
- `-o, --output <PATH>` - Output file path
|
||||
|
||||
**Built-in Profiles:**
|
||||
|
||||
- `curseforge` - CurseForge ZIP format with manifest.json
|
||||
- `modrinth` - Modrinth .mrpack format
|
||||
- `serverpack` - Server-optimized pack (no client-only mods)
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Export for CurseForge
|
||||
pakker export --profile curseforge
|
||||
|
||||
# Export for Modrinth
|
||||
pakker export --profile modrinth
|
||||
|
||||
# Export with custom output path
|
||||
pakker export --profile curseforge -o dist/modpack-v1.0.0.zip
|
||||
|
||||
# Export server pack
|
||||
pakker export --profile serverpack -o server.zip
|
||||
|
||||
# Export all formats
|
||||
pakker export --profile curseforge -o dist/cf.zip
|
||||
pakker export --profile modrinth -o dist/mr.mrpack
|
||||
pakker export --profile serverpack -o dist/server.zip
|
||||
```
|
||||
|
||||
**Profile Configuration:**
|
||||
|
||||
Configure profiles in `pakku.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false
|
||||
},
|
||||
"production": {
|
||||
"filterPlatform": "modrinth",
|
||||
"overrides": ["overrides", "prod-config"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See [EXPORT_PROFILES.md](./EXPORT_PROFILES.md) for complete documentation.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### cfg
|
||||
|
||||
Configure modpack properties.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker cfg [OPTIONS]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--name <NAME>` - Set modpack name
|
||||
- `--version <VERSION>` - Set modpack version
|
||||
- `--description <TEXT>` - Set description
|
||||
- `--author <NAME>` - Set author
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Set modpack name
|
||||
pakker cfg --name "My Awesome Pack"
|
||||
|
||||
# Set version
|
||||
pakker cfg --version "1.0.0"
|
||||
|
||||
# Set multiple properties
|
||||
pakker cfg --name "Performance Pack" --author "YourName" --version "2.0.0"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### credentials
|
||||
|
||||
Manage platform API credentials.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
# View credentials
|
||||
pakker credentials
|
||||
|
||||
# Set credentials
|
||||
pakker credentials set --curseforge <KEY>
|
||||
pakker credentials set --modrinth <TOKEN>
|
||||
|
||||
# Remove credentials
|
||||
pakker credentials remove --curseforge
|
||||
pakker credentials remove --modrinth
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Set CurseForge API key
|
||||
pakker credentials set --curseforge $CF_API_KEY
|
||||
|
||||
# Set Modrinth token
|
||||
pakker credentials set --modrinth $MR_TOKEN
|
||||
|
||||
# View current credentials
|
||||
pakker credentials
|
||||
|
||||
# Remove CurseForge key
|
||||
pakker credentials remove --curseforge
|
||||
```
|
||||
|
||||
**Credential Storage:**
|
||||
|
||||
Credentials are stored securely:
|
||||
1. System keyring (if available)
|
||||
2. Pakker credentials file (encrypted)
|
||||
3. Environment variables
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Higher API rate limits
|
||||
- Access to private/early-access mods
|
||||
- Faster downloads
|
||||
- Better error messages
|
||||
|
||||
---
|
||||
|
||||
## Remote Management
|
||||
|
||||
### remote
|
||||
|
||||
Manage Git remote repositories for modpack configuration.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
# Add remote
|
||||
pakker remote add <NAME> <URL>
|
||||
|
||||
# List remotes
|
||||
pakker remote list
|
||||
|
||||
# Remove remote
|
||||
pakker remote remove <NAME>
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Add origin remote
|
||||
pakker remote add origin https://github.com/user/modpack.git
|
||||
|
||||
# Add upstream
|
||||
pakker remote add upstream https://github.com/original/modpack.git
|
||||
|
||||
# List all remotes
|
||||
pakker remote list
|
||||
|
||||
# Remove remote
|
||||
pakker remote remove origin
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### remote-update
|
||||
|
||||
Pull modpack configuration updates from remote Git repository.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker remote-update [REMOTE]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Update from default remote
|
||||
pakker remote-update
|
||||
|
||||
# Update from specific remote
|
||||
pakker remote-update upstream
|
||||
|
||||
# Update and sync
|
||||
pakker remote-update && pakker sync
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### fork
|
||||
|
||||
Manage fork configuration.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker fork [OPTIONS]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--ref <REF>` - Set fork reference (branch, tag, commit)
|
||||
- `--type <TYPE>` - Set reference type
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Fork from branch
|
||||
pakker fork --ref main --type branch
|
||||
|
||||
# Fork from tag
|
||||
pakker fork --ref v1.0.0 --type tag
|
||||
|
||||
# Fork from commit
|
||||
pakker fork --ref abc1234 --type commit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Utilities
|
||||
|
||||
### diff
|
||||
|
||||
Show differences between local and remote modpack configuration.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
pakker diff [REMOTE]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Show diff with default remote
|
||||
pakker diff
|
||||
|
||||
# Show diff with specific remote
|
||||
pakker diff upstream
|
||||
|
||||
# Show diff in detail
|
||||
pakker -v diff
|
||||
```
|
||||
|
||||
**Example Output:**
|
||||
|
||||
```
|
||||
Changes in remote:
|
||||
+ sodium v0.5.1 (added)
|
||||
- old-mod v1.0.0 (removed)
|
||||
~ lithium v0.11.1 → v0.11.2 (updated)
|
||||
|
||||
Local changes:
|
||||
+ custom-mod v1.0.0 (added)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### CI/CD Pipeline
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
|
||||
# Add projects non-interactively
|
||||
pakker add-prj --mr fabric-api --yes --no-deps
|
||||
pakker add-prj --mr sodium --yes --no-deps
|
||||
pakker add-prj --mr lithium --yes --no-deps
|
||||
|
||||
# Resolve dependencies
|
||||
pakker update --all --yes
|
||||
|
||||
# Fetch files
|
||||
pakker fetch
|
||||
|
||||
# Export for all platforms
|
||||
pakker export --profile curseforge -o dist/curseforge.zip
|
||||
pakker export --profile modrinth -o dist/modrinth.mrpack
|
||||
pakker export --profile serverpack -o dist/server.zip
|
||||
```
|
||||
|
||||
### Batch Updates
|
||||
|
||||
```bash
|
||||
# Update all projects
|
||||
pakker update --all --yes
|
||||
|
||||
# Fetch new versions
|
||||
pakker fetch
|
||||
|
||||
# Export updated pack
|
||||
pakker export --profile modrinth -o updated-pack.mrpack
|
||||
```
|
||||
|
||||
### Platform Migration
|
||||
|
||||
```bash
|
||||
# Add projects from new platform
|
||||
pakker add-prj --mr sodium --cf sodium --yes
|
||||
pakker add-prj --mr lithium --cf lithium --yes
|
||||
|
||||
# Export for both platforms
|
||||
pakker export --profile curseforge -o cf-pack.zip
|
||||
pakker export --profile modrinth -o mr-pack.mrpack
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Credentials
|
||||
|
||||
```bash
|
||||
export CURSEFORGE_API_KEY="your-key"
|
||||
export MODRINTH_TOKEN="your-token"
|
||||
```
|
||||
|
||||
### Verbosity
|
||||
|
||||
```bash
|
||||
export PAKKER_LOG=debug # or info, warn, error
|
||||
```
|
||||
|
||||
### Cache
|
||||
|
||||
```bash
|
||||
export PAKKER_CACHE_DIR="$HOME/.cache/pakker"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exit Codes
|
||||
|
||||
- `0` - Success
|
||||
- `1` - General error
|
||||
- `2` - Invalid arguments
|
||||
- `3` - Project not found
|
||||
- `4` - Network error
|
||||
- `5` - File system error
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Main Documentation](./README.md)
|
||||
- [Export Profiles](./EXPORT_PROFILES.md)
|
||||
- [Migration Guide](./MIGRATION.md)
|
||||
- [Examples](../examples/)
|
||||
348
docs/EXPORT_PROFILES.md
Normal file
348
docs/EXPORT_PROFILES.md
Normal file
|
|
@ -0,0 +1,348 @@
|
|||
# Export Profiles Configuration
|
||||
|
||||
Pakker supports profile-specific export configurations, allowing you to customize export behavior for different platforms and use cases.
|
||||
|
||||
## Overview
|
||||
|
||||
Export profiles enable you to:
|
||||
- Use different override directories per profile
|
||||
- Filter projects by platform availability
|
||||
- Control non-redistributable mod inclusion
|
||||
- Customize client-only mod filtering
|
||||
- Override settings per project
|
||||
|
||||
## Configuration
|
||||
|
||||
Add an `exportProfiles` section to your `pakku.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "My Modpack",
|
||||
"version": "1.0.0",
|
||||
"overrides": ["overrides"],
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false,
|
||||
"overrides": ["overrides", "curseforge-overrides"]
|
||||
},
|
||||
"modrinth": {
|
||||
"filterPlatform": "modrinth",
|
||||
"includeNonRedistributable": true
|
||||
},
|
||||
"serverpack": {
|
||||
"includeClientOnly": false,
|
||||
"serverOverrides": ["server-config"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Profile Configuration Options
|
||||
|
||||
### `filterPlatform` (string, optional)
|
||||
|
||||
Filter projects to only include those available on the specified platform.
|
||||
|
||||
**Supported values**: `"curseforge"`, `"modrinth"`, `"github"`
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"filterPlatform": "modrinth"
|
||||
}
|
||||
```
|
||||
|
||||
Projects without a Modrinth version will be excluded from the export.
|
||||
|
||||
---
|
||||
|
||||
### `includeNonRedistributable` (boolean, optional)
|
||||
|
||||
Control whether non-redistributable mods are included in the export.
|
||||
|
||||
**Default**: `false` for CurseForge, `true` for others
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"includeNonRedistributable": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `includeClientOnly` (boolean, optional)
|
||||
|
||||
Control whether client-only mods are included in server pack exports.
|
||||
|
||||
**Default**: `false` for serverpack profile, `true` for others
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"includeClientOnly": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `overrides` (array of strings, optional)
|
||||
|
||||
Override directories to include in the export. Replaces global `overrides` setting.
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"overrides": ["overrides", "platform-specific-overrides"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `serverOverrides` (array of strings, optional)
|
||||
|
||||
Server-specific override directories. Replaces global `serverOverrides` setting.
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"serverOverrides": ["server-config", "server-scripts"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `clientOverrides` (array of strings, optional)
|
||||
|
||||
Client-specific override directories. Replaces global `clientOverrides` setting.
|
||||
|
||||
**Example**:
|
||||
```json
|
||||
{
|
||||
"clientOverrides": ["client-config", "shaderpacks"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `projectOverrides` (object, optional)
|
||||
|
||||
Per-project configuration within this profile. Not yet implemented.
|
||||
|
||||
**Future feature**:
|
||||
```json
|
||||
{
|
||||
"projectOverrides": {
|
||||
"sodium": {
|
||||
"export": false
|
||||
},
|
||||
"optifine": {
|
||||
"export": true,
|
||||
"subpath": "mods/performance/"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Default Profiles
|
||||
|
||||
Pakker provides sensible defaults for common profiles:
|
||||
|
||||
### CurseForge Default
|
||||
|
||||
```json
|
||||
{
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false
|
||||
}
|
||||
```
|
||||
|
||||
### Modrinth Default
|
||||
|
||||
```json
|
||||
{
|
||||
"filterPlatform": "modrinth",
|
||||
"includeNonRedistributable": true
|
||||
}
|
||||
```
|
||||
|
||||
### ServerPack Default
|
||||
|
||||
```json
|
||||
{
|
||||
"includeClientOnly": false
|
||||
}
|
||||
```
|
||||
|
||||
These defaults are used automatically when exporting with `pakker export --profile <name>` if no custom configuration is specified.
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Example 1: Multi-Platform Modpack
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Multi-Platform Pack",
|
||||
"version": "1.0.0",
|
||||
"overrides": ["overrides"],
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false,
|
||||
"overrides": ["overrides", "curseforge-overrides"]
|
||||
},
|
||||
"modrinth": {
|
||||
"filterPlatform": "modrinth",
|
||||
"includeNonRedistributable": true,
|
||||
"overrides": ["overrides", "modrinth-overrides"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
pakker export --profile curseforge
|
||||
pakker export --profile modrinth
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Server Pack with Custom Config
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Survival Server",
|
||||
"version": "2.0.0",
|
||||
"overrides": ["overrides"],
|
||||
"serverOverrides": ["server-base"],
|
||||
"exportProfiles": {
|
||||
"serverpack": {
|
||||
"includeClientOnly": false,
|
||||
"serverOverrides": ["server-base", "server-production"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
pakker export --profile serverpack
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Development vs Production
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Dev Pack",
|
||||
"version": "1.0.0-dev",
|
||||
"overrides": ["overrides"],
|
||||
"exportProfiles": {
|
||||
"dev": {
|
||||
"includeNonRedistributable": true,
|
||||
"overrides": ["overrides", "dev-config"]
|
||||
},
|
||||
"production": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false,
|
||||
"overrides": ["overrides", "prod-config"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
pakker export --profile dev # For testing
|
||||
pakker export --profile production # For release
|
||||
```
|
||||
|
||||
## How Profile Configuration Works
|
||||
|
||||
### Priority Order
|
||||
|
||||
1. **Profile-specific settings** from `exportProfiles.<profile>`
|
||||
2. **Profile defaults** (curseforge/modrinth/serverpack)
|
||||
3. **Global settings** from root `pakku.json`
|
||||
|
||||
### Example Resolution
|
||||
|
||||
Given this configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"overrides": ["overrides"],
|
||||
"serverOverrides": ["server-global"],
|
||||
"exportProfiles": {
|
||||
"myprofile": {
|
||||
"overrides": ["custom-overrides"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When exporting with `--profile myprofile`:
|
||||
- `overrides`: Uses `["custom-overrides"]` (from profile)
|
||||
- `serverOverrides`: Uses `["server-global"]` (from global, no profile override)
|
||||
|
||||
### Filter Execution Order
|
||||
|
||||
Export rules are executed in this order:
|
||||
|
||||
1. **Copy project files** - Download and copy mod files
|
||||
2. **Filter by platform** - Remove mods not available on target platform
|
||||
3. **Copy overrides** - Copy override directories
|
||||
4. **Generate manifest** - Create platform-specific manifest
|
||||
5. **Filter non-redistributable** - Remove non-redistributable mods (if configured)
|
||||
6. **Filter client-only** - Remove client-only mods (for server packs)
|
||||
|
||||
## Migration from Pakku
|
||||
|
||||
If you're migrating from Pakku, export profiles work the same way. The configuration format is compatible.
|
||||
|
||||
### Pakku Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This works identically in Pakker.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Mods Missing from Export
|
||||
|
||||
**Problem**: Some mods are missing after export.
|
||||
|
||||
**Solution**: Check if `filterPlatform` is excluding them. Use `pakker inspect <project>` to see platform availability.
|
||||
|
||||
---
|
||||
|
||||
### Override Files Not Copied
|
||||
|
||||
**Problem**: Override files aren't appearing in the export.
|
||||
|
||||
**Solution**: Verify the override path in your profile config matches the actual directory structure.
|
||||
|
||||
---
|
||||
|
||||
### Non-Redistributable Mods Included
|
||||
|
||||
**Problem**: Non-redistributable mods are in the export when they shouldn't be.
|
||||
|
||||
**Solution**: Set `includeNonRedistributable: false` in your profile configuration.
|
||||
|
||||
## See Also
|
||||
|
||||
- [Export Command Documentation](./COMMANDS.md#export)
|
||||
- [Configuration Reference](./CONFIGURATION.md)
|
||||
- [Project Configuration](./PROJECTS.md)
|
||||
511
docs/MIGRATION.md
Normal file
511
docs/MIGRATION.md
Normal file
|
|
@ -0,0 +1,511 @@
|
|||
# Migrating from Pakku to Pakker
|
||||
|
||||
This guide helps you migrate from Pakku (Kotlin) to Pakker (Rust).
|
||||
|
||||
## Overview
|
||||
|
||||
Pakker is designed to be largely compatible with Pakku, maintaining the same configuration format and workflow. Most Pakku modpacks can be imported directly into Pakker with minimal changes.
|
||||
|
||||
## Key Differences
|
||||
|
||||
### Performance
|
||||
|
||||
- **Faster execution** - Rust implementation provides significant speed improvements
|
||||
- **Lower memory usage** - More efficient resource utilization
|
||||
- **Parallel operations** - Better concurrency for downloads and processing
|
||||
|
||||
### Enhanced Features
|
||||
|
||||
- **Non-interactive mode** - `add-prj` command for CI/CD workflows
|
||||
- **Advanced inspection** - Enhanced `inspect` command with dependency trees
|
||||
- **Export profiles** - More flexible profile-based export configuration
|
||||
- **Platform filtering** - Automatic platform-specific mod filtering
|
||||
|
||||
### Compatibility
|
||||
|
||||
✅ **Compatible**:
|
||||
- Configuration format (`pakku.json`)
|
||||
- Lockfile format (`pakku-lock.json`)
|
||||
- Export formats (CurseForge ZIP, Modrinth .mrpack)
|
||||
- Override directory structure
|
||||
- Project properties and metadata
|
||||
|
||||
⚠️ **Differences**:
|
||||
- Some CLI flag names (documented below)
|
||||
- New features not in Pakku
|
||||
- Performance characteristics
|
||||
|
||||
## Quick Migration
|
||||
|
||||
### Step 1: Import Existing Modpack
|
||||
|
||||
If you have an existing Pakku modpack:
|
||||
|
||||
```bash
|
||||
# Navigate to your modpack directory
|
||||
cd my-modpack
|
||||
|
||||
# Pakker will use existing pakku.json and pakku-lock.json
|
||||
pakker ls
|
||||
```
|
||||
|
||||
That's it! Pakker reads the same configuration files.
|
||||
|
||||
### Step 2: Verify Projects
|
||||
|
||||
```bash
|
||||
# List all projects
|
||||
pakker ls
|
||||
|
||||
# Inspect specific projects
|
||||
pakker inspect sodium lithium
|
||||
```
|
||||
|
||||
### Step 3: Test Export
|
||||
|
||||
```bash
|
||||
# Export for your target platform
|
||||
pakker export --profile curseforge
|
||||
pakker export --profile modrinth
|
||||
```
|
||||
|
||||
## Configuration Migration
|
||||
|
||||
### pakku.json Format
|
||||
|
||||
Pakker uses the **same format** as Pakku:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "My Modpack",
|
||||
"version": "1.0.0",
|
||||
"description": "A performance modpack",
|
||||
"author": "YourName",
|
||||
"overrides": ["overrides"],
|
||||
"serverOverrides": ["server-overrides"],
|
||||
"clientOverrides": ["client-overrides"]
|
||||
}
|
||||
```
|
||||
|
||||
### Export Profiles
|
||||
|
||||
Pakker extends Pakku's configuration with enhanced export profiles:
|
||||
|
||||
**Pakku format** (still supported):
|
||||
|
||||
```json
|
||||
{
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Pakker enhancements** (new features):
|
||||
|
||||
```json
|
||||
{
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false,
|
||||
"overrides": ["overrides", "curseforge-specific"]
|
||||
},
|
||||
"modrinth": {
|
||||
"filterPlatform": "modrinth",
|
||||
"includeNonRedistributable": true
|
||||
},
|
||||
"serverpack": {
|
||||
"includeClientOnly": false,
|
||||
"serverOverrides": ["server-config"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See [EXPORT_PROFILES.md](./EXPORT_PROFILES.md) for complete documentation.
|
||||
|
||||
## Command Mapping
|
||||
|
||||
Most commands are identical or very similar:
|
||||
|
||||
| Pakku | Pakker | Notes |
|
||||
|-------|--------|-------|
|
||||
| `pakku init` | `pakker init` | Identical |
|
||||
| `pakku import` | `pakker import` | Identical |
|
||||
| `pakku add` | `pakker add` | Identical |
|
||||
| `pakku add` | `pakker add-prj` | New non-interactive variant |
|
||||
| `pakku rm` | `pakker rm` | Identical |
|
||||
| `pakku update` | `pakker update` | Identical |
|
||||
| `pakku ls` | `pakker ls` | Identical |
|
||||
| `pakku status` | `pakker status` | Identical |
|
||||
| `pakku fetch` | `pakker fetch` | Identical |
|
||||
| `pakku export` | `pakker export` | Enhanced with profiles |
|
||||
| `pakku link` | `pakker link` | Identical |
|
||||
| `pakku set` | `pakker set` | Identical |
|
||||
| `pakku cfg` | `pakker cfg` | Identical |
|
||||
| `pakku diff` | `pakker diff` | Identical |
|
||||
|
||||
### New Commands in Pakker
|
||||
|
||||
- `pakker add-prj` - Non-interactive project addition for CI/CD
|
||||
- `pakker inspect` - Enhanced project inspection with dependency trees
|
||||
- `pakker sync` - Combined update + fetch operation
|
||||
- `pakker credentials` - Credential management
|
||||
- `pakker remote` - Git remote management
|
||||
- `pakker fork` - Fork configuration
|
||||
|
||||
## Feature Comparison
|
||||
|
||||
### Project Management
|
||||
|
||||
| Feature | Pakku | Pakker | Notes |
|
||||
|---------|-------|--------|-------|
|
||||
| Add projects | ✅ | ✅ | Enhanced with `add-prj` |
|
||||
| Remove projects | ✅ | ✅ | Identical |
|
||||
| Update projects | ✅ | ✅ | Identical |
|
||||
| List projects | ✅ | ✅ | Identical |
|
||||
| Project properties | ✅ | ✅ | Identical |
|
||||
| Dependencies | ✅ | ✅ | Enhanced inspection |
|
||||
|
||||
### Export System
|
||||
|
||||
| Feature | Pakku | Pakker | Notes |
|
||||
|---------|-------|--------|-------|
|
||||
| CurseForge export | ✅ | ✅ | Identical format |
|
||||
| Modrinth export | ✅ | ✅ | Identical format |
|
||||
| Server pack | ✅ | ✅ | Enhanced filtering |
|
||||
| Export profiles | ✅ | ✅ | Extended features |
|
||||
| Override dirs | ✅ | ✅ | Identical |
|
||||
| Platform filtering | ❌ | ✅ | New in Pakker |
|
||||
| Profile-specific overrides | ❌ | ✅ | New in Pakker |
|
||||
|
||||
### Configuration
|
||||
|
||||
| Feature | Pakku | Pakker | Notes |
|
||||
|---------|-------|--------|-------|
|
||||
| pakku.json | ✅ | ✅ | Same format |
|
||||
| pakku-lock.json | ✅ | ✅ | Same format |
|
||||
| Project config | ✅ | ✅ | Identical |
|
||||
| Export profiles | ✅ | ✅ | Extended in Pakker |
|
||||
|
||||
## Migration Scenarios
|
||||
|
||||
### Scenario 1: Local Development
|
||||
|
||||
**Pakku workflow:**
|
||||
|
||||
```bash
|
||||
pakku init
|
||||
pakku add sodium lithium
|
||||
pakku fetch
|
||||
pakku export
|
||||
```
|
||||
|
||||
**Pakker workflow:**
|
||||
|
||||
```bash
|
||||
pakker init
|
||||
pakker add sodium lithium
|
||||
pakker fetch
|
||||
pakker export --profile modrinth
|
||||
```
|
||||
|
||||
No changes needed!
|
||||
|
||||
### Scenario 2: CI/CD Pipeline
|
||||
|
||||
**Pakku workflow:**
|
||||
|
||||
```bash
|
||||
# Interactive, requires user input
|
||||
pakku add sodium
|
||||
pakku add lithium
|
||||
pakku fetch
|
||||
pakku export
|
||||
```
|
||||
|
||||
**Pakker workflow:**
|
||||
|
||||
```bash
|
||||
# Fully automated
|
||||
pakker add-prj --mr sodium --yes --no-deps
|
||||
pakker add-prj --mr lithium --yes --no-deps
|
||||
pakker update --all --yes
|
||||
pakker fetch
|
||||
pakker export --profile modrinth -o dist/pack.mrpack
|
||||
```
|
||||
|
||||
Benefits: No interactive prompts, perfect for CI/CD.
|
||||
|
||||
### Scenario 3: Multi-Platform Release
|
||||
|
||||
**Pakku workflow:**
|
||||
|
||||
```bash
|
||||
# Manual export for each platform
|
||||
pakku export
|
||||
# Manually select CurseForge
|
||||
pakku export
|
||||
# Manually select Modrinth
|
||||
```
|
||||
|
||||
**Pakker workflow:**
|
||||
|
||||
```bash
|
||||
# Script multiple exports
|
||||
pakker export --profile curseforge -o dist/cf.zip
|
||||
pakker export --profile modrinth -o dist/mr.mrpack
|
||||
pakker export --profile serverpack -o dist/server.zip
|
||||
```
|
||||
|
||||
Benefits: Scriptable, reproducible builds.
|
||||
|
||||
## Migrating CI/CD Workflows
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
**Before (Pakku):**
|
||||
|
||||
```yaml
|
||||
- name: Setup Pakku
|
||||
run: |
|
||||
# Install Pakku
|
||||
|
||||
- name: Build modpack
|
||||
run: |
|
||||
pakku fetch
|
||||
pakku export
|
||||
```
|
||||
|
||||
**After (Pakker):**
|
||||
|
||||
```yaml
|
||||
- name: Setup Pakker
|
||||
run: |
|
||||
# Install Pakker
|
||||
cargo install pakker
|
||||
|
||||
- name: Build modpack
|
||||
run: |
|
||||
pakker fetch
|
||||
pakker export --profile curseforge -o dist/curseforge.zip
|
||||
pakker export --profile modrinth -o dist/modrinth.mrpack
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
**Before (Pakku):**
|
||||
|
||||
```yaml
|
||||
build:
|
||||
script:
|
||||
- pakku fetch
|
||||
- pakku export
|
||||
```
|
||||
|
||||
**After (Pakker):**
|
||||
|
||||
```yaml
|
||||
build:
|
||||
script:
|
||||
- pakker fetch
|
||||
- pakker export --profile curseforge -o curseforge.zip
|
||||
- pakker export --profile modrinth -o modrinth.mrpack
|
||||
artifacts:
|
||||
paths:
|
||||
- "*.zip"
|
||||
- "*.mrpack"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Projects Not Found After Migration
|
||||
|
||||
**Problem**: Pakker can't find projects that worked in Pakku.
|
||||
|
||||
**Solution**: Verify lockfile format:
|
||||
|
||||
```bash
|
||||
# Check lockfile
|
||||
cat pakku-lock.json
|
||||
|
||||
# Re-fetch projects
|
||||
pakker fetch
|
||||
|
||||
# If issues persist, re-add problematic projects
|
||||
pakker rm problematic-mod
|
||||
pakker add-prj --mr problematic-mod --yes
|
||||
```
|
||||
|
||||
### Export Format Differences
|
||||
|
||||
**Problem**: Exported packs look different.
|
||||
|
||||
**Solution**: Pakker may organize files slightly differently. Both formats are valid:
|
||||
|
||||
```bash
|
||||
# Inspect export
|
||||
unzip -l curseforge.zip
|
||||
|
||||
# Verify manifest
|
||||
jq . manifest.json
|
||||
```
|
||||
|
||||
If needed, configure export profiles to match Pakku behavior exactly.
|
||||
|
||||
### Performance Issues
|
||||
|
||||
**Problem**: Pakker seems slower than expected.
|
||||
|
||||
**Solution**: Pakker should be faster than Pakku. Check:
|
||||
|
||||
```bash
|
||||
# Enable logging
|
||||
pakker -vv fetch
|
||||
|
||||
# Check network connectivity
|
||||
pakker status
|
||||
|
||||
# Verify credentials (for rate limits)
|
||||
pakker credentials
|
||||
```
|
||||
|
||||
### Configuration Not Recognized
|
||||
|
||||
**Problem**: Some configuration options don't work.
|
||||
|
||||
**Solution**: Ensure you're using compatible options:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "My Pack",
|
||||
"version": "1.0.0",
|
||||
"overrides": ["overrides"]
|
||||
}
|
||||
```
|
||||
|
||||
Pakker supports all Pakku options plus new ones. Check [EXPORT_PROFILES.md](./EXPORT_PROFILES.md) for new features.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Test Before Full Migration
|
||||
|
||||
```bash
|
||||
# Copy modpack to test directory
|
||||
cp -r my-modpack my-modpack-test
|
||||
cd my-modpack-test
|
||||
|
||||
# Test with Pakker
|
||||
pakker ls
|
||||
pakker fetch
|
||||
pakker export --profile modrinth
|
||||
|
||||
# Verify exports match expectations
|
||||
```
|
||||
|
||||
### 2. Update CI/CD Gradually
|
||||
|
||||
1. Test Pakker locally first
|
||||
2. Update a single workflow
|
||||
3. Verify builds succeed
|
||||
4. Roll out to all workflows
|
||||
|
||||
### 3. Use New Features
|
||||
|
||||
Take advantage of Pakker enhancements:
|
||||
|
||||
```bash
|
||||
# Non-interactive project addition
|
||||
pakker add-prj --mr sodium --yes
|
||||
|
||||
# Enhanced inspection
|
||||
pakker inspect sodium
|
||||
|
||||
# Profile-based exports
|
||||
pakker export --profile production -o release.mrpack
|
||||
```
|
||||
|
||||
### 4. Keep Backward Compatibility
|
||||
|
||||
If you need to support both Pakku and Pakker:
|
||||
|
||||
```json
|
||||
{
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Use the common subset of features that both support.
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Resources
|
||||
|
||||
- [Pakker Documentation](./README.md)
|
||||
- [Command Reference](./COMMANDS.md)
|
||||
- [Export Profiles](./EXPORT_PROFILES.md)
|
||||
|
||||
### Common Issues
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Project not found | Try explicit platform: `pakker add-prj --mr <name>` |
|
||||
| Export fails | Check export profile configuration |
|
||||
| Missing files | Run `pakker fetch` |
|
||||
| Slow performance | Verify network, add credentials |
|
||||
| Config not recognized | Check pakku.json syntax with `jq` |
|
||||
|
||||
### Support Channels
|
||||
|
||||
- GitHub Issues: Report bugs and feature requests
|
||||
- Documentation: Check docs/ directory
|
||||
- Examples: See examples/ directory
|
||||
|
||||
## Migration Checklist
|
||||
|
||||
- [ ] Backup existing modpack directory
|
||||
- [ ] Install Pakker
|
||||
- [ ] Verify `pakker ls` shows all projects
|
||||
- [ ] Test `pakker fetch` downloads files
|
||||
- [ ] Test export for your target platform
|
||||
- [ ] Update CI/CD workflows
|
||||
- [ ] Test automated builds
|
||||
- [ ] Update documentation
|
||||
- [ ] Train team members on new commands
|
||||
- [ ] Monitor for issues
|
||||
|
||||
## Feature Roadmap
|
||||
|
||||
Pakker aims for full Pakku compatibility plus enhancements. If you find missing features, please report them!
|
||||
|
||||
**Current Status:**
|
||||
- ✅ Core functionality (add, remove, update, export)
|
||||
- ✅ Multi-platform support
|
||||
- ✅ Export profiles
|
||||
- ✅ CI/CD workflows
|
||||
- ✅ Dependency resolution
|
||||
|
||||
**Planned:**
|
||||
- Custom export rules
|
||||
- Advanced project filtering
|
||||
- Enhanced remote sync
|
||||
- Plugin system
|
||||
|
||||
## Summary
|
||||
|
||||
Migrating from Pakku to Pakker is straightforward:
|
||||
|
||||
1. **No configuration changes** needed for basic usage
|
||||
2. **Same commands** for most operations
|
||||
3. **Enhanced features** available when ready
|
||||
4. **Better performance** out of the box
|
||||
5. **CI/CD friendly** with non-interactive modes
|
||||
|
||||
Most users can start using Pakker immediately with existing Pakku modpacks!
|
||||
455
docs/README.md
Normal file
455
docs/README.md
Normal file
|
|
@ -0,0 +1,455 @@
|
|||
# Pakker
|
||||
|
||||
A fast, reliable multiplatform modpack manager for Minecraft, written in Rust.
|
||||
|
||||
## Overview
|
||||
|
||||
Pakker is a command-line tool for managing Minecraft modpacks across multiple
|
||||
platforms including CurseForge, Modrinth, and GitHub. It provides a streamlined
|
||||
workflow for creating, maintaining, and distributing modpacks with support for
|
||||
automated dependency resolution, version management, and multi-platform exports.
|
||||
|
||||
## Key Features
|
||||
|
||||
### Multi-Platform Support
|
||||
|
||||
- **CurseForge**, **Modrinth**, and **GitHub** integration
|
||||
- Unified project management across all platforms
|
||||
- Platform-specific filtering and optimizations
|
||||
- Automatic platform-specific manifest generation
|
||||
|
||||
### Intelligent Project Management
|
||||
|
||||
- **Dependency Resolution** - Automatically resolve and manage project
|
||||
dependencies
|
||||
- **Version Management** - Update strategies (latest, specific version, pinned)
|
||||
- **Project Inspection** - Detailed project information with dependency trees
|
||||
- **Fuzzy Matching** - Typo-tolerant project searches with suggestions
|
||||
|
||||
### Flexible Export System
|
||||
|
||||
- **Profile-Based Exports** - Customize exports for different platforms and use
|
||||
cases
|
||||
- **Platform Filtering** - Automatically exclude projects not available on
|
||||
target platform
|
||||
- **Override Management** - Separate override directories for client/server
|
||||
configurations
|
||||
- **Non-Interactive Mode** - Full CI/CD support with scriptable commands
|
||||
|
||||
### Advanced Configuration
|
||||
|
||||
- **Profile-Specific Settings** - Override paths, filtering rules, and export
|
||||
behavior per profile
|
||||
- **Project-Level Customization** - Per-project export settings, aliases, and
|
||||
properties
|
||||
- **Side Detection** - Automatic client/server/both classification
|
||||
- **Redistributable Control** - Manage non-redistributable mod inclusion per
|
||||
profile
|
||||
|
||||
## Installation
|
||||
|
||||
### From Source
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/pakker
|
||||
cd pakker
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
The binary will be available at `target/release/pakker`.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Rust 1.70 or later
|
||||
- Git (for remote repository features)
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Initialize a New Modpack
|
||||
|
||||
```bash
|
||||
# Create a new modpack for Fabric 1.20.1
|
||||
pakker init -m 1.20.1 -l fabric
|
||||
|
||||
# Or for Forge
|
||||
pakker init -m 1.20.1 -l forge
|
||||
```
|
||||
|
||||
### Add Mods
|
||||
|
||||
```bash
|
||||
# Interactive mode - search and select
|
||||
pakker add sodium
|
||||
|
||||
# Non-interactive with platform specification
|
||||
pakker add-prj --mr sodium --yes
|
||||
|
||||
# Add with specific properties
|
||||
pakker add-prj --cf jei --side both --yes
|
||||
```
|
||||
|
||||
### Inspect Projects
|
||||
|
||||
```bash
|
||||
# View project details
|
||||
pakker inspect sodium
|
||||
|
||||
# Multiple projects with dependency trees
|
||||
pakker inspect sodium lithium phosphor
|
||||
|
||||
# View all projects
|
||||
pakker ls
|
||||
```
|
||||
|
||||
### Fetch Mod Files
|
||||
|
||||
```bash
|
||||
# Download all mod files
|
||||
pakker fetch
|
||||
|
||||
# Or use sync to update and fetch
|
||||
pakker sync
|
||||
```
|
||||
|
||||
### Export Modpack
|
||||
|
||||
```bash
|
||||
# Export for CurseForge
|
||||
pakker export --profile curseforge
|
||||
|
||||
# Export for Modrinth
|
||||
pakker export --profile modrinth
|
||||
|
||||
# Export server pack
|
||||
pakker export --profile serverpack
|
||||
```
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
my-modpack/
|
||||
├── pakku.json # Modpack configuration
|
||||
├── pakku-lock.json # Lockfile with resolved versions
|
||||
├── mods/ # Downloaded mod files
|
||||
├── overrides/ # Files to include in all exports
|
||||
├── server-overrides/ # Server-specific files
|
||||
└── client-overrides/ # Client-specific files
|
||||
```
|
||||
|
||||
## Configuration Example
|
||||
|
||||
### Basic Configuration (`pakku.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "My Awesome Modpack",
|
||||
"version": "1.0.0",
|
||||
"description": "A performance-focused modpack",
|
||||
"author": "YourName",
|
||||
"overrides": ["overrides"],
|
||||
"serverOverrides": ["server-overrides"],
|
||||
"clientOverrides": ["client-overrides"]
|
||||
}
|
||||
```
|
||||
|
||||
### With Export Profiles
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Multi-Platform Pack",
|
||||
"version": "1.0.0",
|
||||
"overrides": ["overrides"],
|
||||
"exportProfiles": {
|
||||
"curseforge": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false,
|
||||
"overrides": ["overrides", "curseforge-specific"]
|
||||
},
|
||||
"modrinth": {
|
||||
"filterPlatform": "modrinth",
|
||||
"includeNonRedistributable": true
|
||||
},
|
||||
"serverpack": {
|
||||
"includeClientOnly": false,
|
||||
"serverOverrides": ["server-config"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Development Workflow
|
||||
|
||||
```bash
|
||||
# Initialize project
|
||||
pakker init -m 1.20.1 -l fabric
|
||||
|
||||
# Add core mods
|
||||
pakker add-prj --mr fabric-api --yes
|
||||
pakker add-prj --mr sodium --yes
|
||||
pakker add-prj --mr lithium --yes
|
||||
|
||||
# Configure and test
|
||||
pakker fetch
|
||||
# ... test in game ...
|
||||
|
||||
# Add more mods
|
||||
pakker add create
|
||||
|
||||
# Check status
|
||||
pakker status
|
||||
|
||||
# Export for testing
|
||||
pakker export --profile modrinth
|
||||
```
|
||||
|
||||
### CI/CD Pipeline
|
||||
|
||||
```bash
|
||||
# Non-interactive project addition
|
||||
pakker add-prj --mr fabric-api --yes --no-deps
|
||||
pakker add-prj --cf jei --yes
|
||||
|
||||
# Update to latest versions
|
||||
pakker update --yes
|
||||
|
||||
# Fetch all files
|
||||
pakker fetch
|
||||
|
||||
# Export for all platforms
|
||||
pakker export --profile curseforge -o dist/curseforge.zip
|
||||
pakker export --profile modrinth -o dist/modrinth.mrpack
|
||||
pakker export --profile serverpack -o dist/server.zip
|
||||
```
|
||||
|
||||
### Multi-Platform Release
|
||||
|
||||
```bash
|
||||
# Add projects from multiple platforms
|
||||
pakker add-prj --mr sodium --cf sodium --yes
|
||||
pakker add-prj --mr lithium --cf lithium --yes
|
||||
|
||||
# Configure CurseForge export (no non-redistributable)
|
||||
# Configure Modrinth export (allow all)
|
||||
# (in pakku.json - see Export Profiles documentation)
|
||||
|
||||
# Export for both
|
||||
pakker export --profile curseforge -o releases/curseforge-pack.zip
|
||||
pakker export --profile modrinth -o releases/modrinth-pack.mrpack
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[Commands Reference](./COMMANDS.md)** - Complete command documentation
|
||||
- **[Export Profiles](./EXPORT_PROFILES.md)** - Profile configuration guide
|
||||
- **[Migration Guide](./MIGRATION.md)** - Migrating from Pakku
|
||||
- **[Examples](../examples/)** - Configuration examples
|
||||
|
||||
## Command Overview
|
||||
|
||||
| Command | Description |
|
||||
| ------------- | ------------------------------------------------------ |
|
||||
| `init` | Initialize a new modpack project |
|
||||
| `import` | Import an existing modpack |
|
||||
| `add` | Add projects interactively |
|
||||
| `add-prj` | Add projects non-interactively with explicit platforms |
|
||||
| `rm` | Remove projects |
|
||||
| `update` | Update projects to newer versions |
|
||||
| `ls` | List all projects in modpack |
|
||||
| `inspect` | View detailed project information |
|
||||
| `fetch` | Download all project files |
|
||||
| `sync` | Update and fetch in one command |
|
||||
| `export` | Export modpack for distribution |
|
||||
| `status` | Check for available updates |
|
||||
| `set` | Modify project properties |
|
||||
| `link` | Link related projects |
|
||||
| `diff` | Show differences with remote |
|
||||
| `credentials` | Manage API credentials |
|
||||
| `cfg` | Configure modpack properties |
|
||||
|
||||
See [COMMANDS.md](./COMMANDS.md) for detailed usage.
|
||||
|
||||
## Features in Detail
|
||||
|
||||
### Dependency Resolution
|
||||
|
||||
Pakker automatically resolves and manages dependencies:
|
||||
|
||||
```bash
|
||||
pakker add sodium
|
||||
# Automatically adds fabric-api as a dependency
|
||||
```
|
||||
|
||||
Dependencies are tracked in `pakku-lock.json` and can be inspected:
|
||||
|
||||
```bash
|
||||
pakker inspect sodium
|
||||
# Shows:
|
||||
# Dependencies: fabric-api
|
||||
```
|
||||
|
||||
### Project Side Detection
|
||||
|
||||
Projects are automatically classified as client-only, server-only, or both:
|
||||
|
||||
- **Client-only**: Shaders, client performance mods, minimap mods
|
||||
- **Server-only**: Server management mods, world generation mods
|
||||
- **Both**: Most gameplay mods, APIs, libraries
|
||||
|
||||
Override this with:
|
||||
|
||||
```bash
|
||||
pakker set sodium --side client
|
||||
```
|
||||
|
||||
### Version Management
|
||||
|
||||
Control how projects are updated:
|
||||
|
||||
```bash
|
||||
# Pin to specific version
|
||||
pakker set sodium --strategy specific --version 0.5.0
|
||||
|
||||
# Always use latest
|
||||
pakker set lithium --strategy latest
|
||||
|
||||
# Manual updates only
|
||||
pakker set fabric-api --strategy pinned
|
||||
```
|
||||
|
||||
### Export Profiles
|
||||
|
||||
Customize export behavior per platform:
|
||||
|
||||
- **Override directories** - Different overrides per export
|
||||
- **Platform filtering** - Exclude unavailable mods
|
||||
- **Redistributable control** - Manage non-redistributable content
|
||||
- **Client/server filtering** - Remove client-only mods from server packs
|
||||
|
||||
See [EXPORT_PROFILES.md](./EXPORT_PROFILES.md) for complete documentation.
|
||||
|
||||
### Remote Repositories
|
||||
|
||||
Sync modpack configuration with Git repositories:
|
||||
|
||||
```bash
|
||||
# Add remote
|
||||
pakker remote add origin https://github.com/user/modpack.git
|
||||
|
||||
# Pull updates
|
||||
pakker remote-update
|
||||
|
||||
# Configuration is automatically synced
|
||||
```
|
||||
|
||||
### Credentials Management
|
||||
|
||||
Store platform API credentials securely:
|
||||
|
||||
```bash
|
||||
# Set credentials
|
||||
pakker credentials set --curseforge YOUR_CF_KEY
|
||||
pakker credentials set --modrinth YOUR_MR_TOKEN
|
||||
|
||||
# Credentials are used automatically for:
|
||||
# - Private mods
|
||||
# - Rate limit increases
|
||||
# - Authenticated downloads
|
||||
```
|
||||
|
||||
## Platform Compatibility
|
||||
|
||||
### CurseForge
|
||||
|
||||
- Full project search and metadata
|
||||
- Automatic manifest generation
|
||||
- Non-redistributable mod detection
|
||||
- Curse modpack import support
|
||||
|
||||
### Modrinth
|
||||
|
||||
- Complete Modrinth API integration
|
||||
- .mrpack format import/export
|
||||
- Environment metadata support
|
||||
- Full modpack search
|
||||
|
||||
### GitHub
|
||||
|
||||
- GitHub Releases integration
|
||||
- Direct JAR downloads
|
||||
- Version tag support
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Fuzzy Project Search
|
||||
|
||||
Don't remember exact names? Pakker helps:
|
||||
|
||||
```bash
|
||||
pakker add sodum
|
||||
# Suggested: Did you mean "sodium"?
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
|
||||
Add multiple projects efficiently:
|
||||
|
||||
```bash
|
||||
pakker add-prj --mr sodium --yes
|
||||
pakker add-prj --mr lithium --yes
|
||||
pakker add-prj --mr phosphor --yes
|
||||
```
|
||||
|
||||
Or use a script:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
mods=("sodium" "lithium" "phosphor" "iris")
|
||||
for mod in "${mods[@]}"; do
|
||||
pakker add-prj --mr "$mod" --yes
|
||||
done
|
||||
```
|
||||
|
||||
### Inspect Dependency Trees
|
||||
|
||||
Visualize complex dependency relationships:
|
||||
|
||||
```bash
|
||||
pakker inspect create
|
||||
# Shows:
|
||||
# create v0.5.1
|
||||
# ├── flywheel v0.6.10
|
||||
# │ └── forge-api v1.20.1
|
||||
# └── registrate v1.3.3
|
||||
```
|
||||
|
||||
### Custom Export Profiles
|
||||
|
||||
Create specialized export configurations:
|
||||
|
||||
```json
|
||||
{
|
||||
"exportProfiles": {
|
||||
"production": {
|
||||
"filterPlatform": "curseforge",
|
||||
"includeNonRedistributable": false,
|
||||
"overrides": ["overrides", "prod-config"]
|
||||
},
|
||||
"development": {
|
||||
"includeNonRedistributable": true,
|
||||
"overrides": ["overrides", "dev-config"]
|
||||
},
|
||||
"client": {
|
||||
"includeClientOnly": true,
|
||||
"overrides": ["overrides", "client-extras"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
Pakker is inspired by [Pakku](https://github.com/juraj-hrivnak/Pakku), bringing
|
||||
similar functionality with improved performance and additional features through
|
||||
Rust implementation.
|
||||
Loading…
Add table
Add a link
Reference in a new issue