zoryn up¶

Automatic package update to a new upstream version. A 14-stage state-aware pipeline that can be paused, resumed and rolled back.

Synopsis¶

zoryn up [-t|--tarball] [--tag TAG] [--allow-unrelated-histories] [-f|--force]
         [-r|--rebuild] [--top] [--switch-to-upstream-git]
         [--sandbox=RUNNER] [--no-sandbox]
         [-b|--builder PATTERN] [-a|--arch ARCH] [-B|--branch BRANCH]
         [-p|--parallel] [-s|--sequential] [--fail-if-busy] [--skip-busy]
         [--skip-check[=LIST]] [--batch-pkgs=PKGS] [-d] [-v]

Options¶

-t, --tarball — force tarball mode (download and update instead of git merge).
--tag TAG — use a specific upstream tag for merge (skip version detection).
--allow-unrelated-histories — merge unrelated histories (for packages with imported pristine upstream).
-f, --force — force update from prerelease to stable release when no newer version exists.
-b, --builder PATTERN — select builders by name or pattern (see Builder Patterns).
-a, --arch ARCH — select builder by target architecture (comma-separated for multiple).
-B, --branch BRANCH — select builder by target branch (comma-separated for multiple).
-p, --parallel — run builds in parallel when using multiple builders.
-s, --sequential — run builds sequentially (overrides parallel = on in config).
--fail-if-busy — exit immediately if builder is busy (default: wait).
--skip-busy — skip busy builders without error.
--skip-check[=LIST] — skip specified checks (comma-separated). Values: rpmbuild (skip %check), tool names like sisyphus_check, all. Without a value — skips everything.
--batch-pkgs=PKGS — build only specified batch values (comma-separated) instead of all values from [batch].
-r, --rebuild — use hsh-rebuild instead of hsh (rebuild in existing hasher without recreating chroot).
--top — interactive TUI for monitoring builds (htop-like).
--switch-to-upstream-git — migrate tarball-based repo to upstream-git scheme (see below).
--sandbox=RUNNER — sandbox backend for hooks: hybrid (default), bwrap, or direct.
--no-sandbox — disable sandbox for hooks.
--no-python-auto-deps — disable automatic pyproject_deps.json update and rebuild retry when Python dependencies change.
-v, --verbose — show build output on screen (in addition to log file).

Pipeline control¶

If a stage fails, you can resume, abort, or isolate stages:

Flag	Description
`--continue`	Resume from the last failed stage
`--abort`	Rollback changes to pre-update state
`--restart`	Discard saved state, start fresh
`--stage=STAGE`	Run a single stage in isolation
`--from=STAGE`	Run from a specific stage to the end

Available stages: detect, fetch, find-version, merge, merge-hooks, spec, gear-tags, up-hooks, build, batch-build.

Pipeline state is stored under the active git directory — .git/zoryn-up-state.json in a normal clone, or .git/worktrees/<name>/zoryn-up-state.json inside a git worktree — so each worktree resumes its own pipeline independently.

Supported repository schemes¶

zoryn auto-detects and supports four maintenance schemes.

1. Git merge (standard)¶

Working tree contains upstream source code plus ALT Linux build files (.gear/, .spec). Examples: php, curl, nginx.

.gear/rules: tar: v@version@:.

Upstream code is merged directly into the working tree. Patches are applied as commits on top of upstream. When updating, git merge integrates the new upstream version with local changes.

2. Tarball download¶

Upstream tarball is downloaded and extracted into a subdirectory. ALT Linux build files (.spec, .gear/, patches) are stored alongside. Used with zoryn up --tarball or auto-detected from the watch file.

.gear/rules: tar: @name@
             copy?: *.patch

The tarball is fetched from the upstream URL in the watch file and imported into the subdirectory.

3. Pristine tarball + history attachment¶

Working tree contains only ALT Linux build files (.spec, .gear/, *.patch). Upstream source code exists only in git history, attached via merge. Examples: libssh2, openssl.

.gear/rules: tar: @name@-@version@:.
             copy?: *.patch

When updating, zoryn uses git merge -s ours — attaching upstream history without modifying working tree files. Patches are maintained manually as separate files.

Detection is automatic: zoryn compares files in HEAD vs the upstream tag. If there are no common source files (only .spec, .patch, .gear/), the pristine-tarball scheme is detected and -s ours is used.

Importing with no common history. When the local branch has no common ancestor with upstream (e.g. fresh import of upstream sources), use --allow-unrelated-histories. This merges with -s ours --allow-unrelated-histories, then restores upstream files while preserving ALT-specific directories (.gear/, spec directory, copy directories from .gear/rules).

4. Subtree¶

Upstream source code lives in a subdirectory, ALT Linux build files in the root. Example: apache2-mod_auth_openidc.

.gear/rules: tar:  v@version@:.
             diff: v@version@:. mod_auth_openidc/

The diff: directive tells gear to create a patch from differences between the tag and the subdirectory. When updating, zoryn uses git subtree pull to update the subdirectory from upstream. Local changes in the subdirectory automatically become patches.

Detection is automatic: zoryn analyses commit history for each subdirectory. If recent commits are predominantly of the "Merge commit 'HASH'" pattern (characteristic of git subtree pull --squash), the subtree scheme is detected.

Workflow¶

Finds the spec file and extracts the current version.
Checks if the URL: tag points to pypi.org/project/<name>/ — if so, uses PyPI as the version source (filters yanked/pre-release per PEP 440, creates alias tags when PEP 440 normalisation differs from the git tag). --tag bypasses PyPI detection.
Reads the repository URL from the VCS: tag in the spec file.
Adds upstream remote and fetches tags.
Applies version mapping from .gear/version-up (if present).
Finds newer versions and selects the latest.
Detects merge strategy (standard or -s ours).
Merges the upstream tag (or downloads a tarball with --tarball).
Runs hooks from .gear/merge-up.d/.
Updates version in the spec file, resets release to alt1.
Scans the upstream changelog for CVEs (if configured).
Adds a changelog entry.
Runs hooks from .gear/up.d/.
Updates gear tags.

Migrating to upstream-git scheme¶

Migrate a tarball-based package to the upstream-git scheme:

zoryn up --switch-to-upstream-git

With an explicit upstream tag:

zoryn up --switch-to-upstream-git --tag v2007f