Repositories

This page explains Zoi's official repositories and mirrors, and how package repositories are organized by tier.

Official project and package database

• Source code (Zoi)

  • Primary: GitLab
  • Mirrors: GitHub, Codeberg

• Packages database (Zoi-Pkgs)

  • Primary: GitLab
  • Mirrors: GitHub, Codeberg

Managing the Package Database Registry

The package database is the core git repository that Zoi clones to ~/.zoi/pkgs/db. This repository contains all the package definitions organized into tiers. While you can manage which repositories inside the database are active using zoi repo, you can also change the URL of the entire database registry itself using zoi sync.

This is useful if you want to use a mirror or a completely different package database.

Examples

# Show the current registry URL
zoi sync show

# Set the registry to the official GitHub mirror
zoi sync set github

# Set the registry to a custom URL
zoi sync set https://my-custom-registry.com/zoi-pkgs.git

Automatic Fallback

To improve reliability, Zoi can automatically try syncing from the mirrors defined in the mirrors-git list of the repo.yaml file if your configured primary registry is unavailable.

• zoi sync --fallback: If the sync fails, Zoi will attempt to use the mirrors one by one until it succeeds.
• zoi update: The update command uses this fallback mechanism by default to ensure that package updates are as reliable as possible.

Repository tiers

Zoi organizes packages into tiers. Use these to decide where a package belongs and to assess stability.

Note: Packages from community, test, and archive may carry higher risk. Zoi prints warnings where appropriate.

Managing Active Repositories

The zoi repo command manages which repositories from the package database are active. Active repositories are searched during package operations like install and search.

Examples

# Add a repository interactively
zoi repo add

# Add official repositories by name
zoi repo add core
zoi repo add main
zoi repo add community

# Add by git URL (cloned under ~/.zoi/pkgs/git/ and used via @git/<repo>/<pkg>)
zoi repo add https://github.com/YourOrg/my-zoi-repo.git

# Remove and list
zoi repo rm community
zoi repo list
zoi repo list all
zoi repo git ls
zoi repo git rm my-zoi-repo

Direct Git Repository Installation

In addition to adding a git repository to your local configuration with zoi repo add, you can install a package directly from a remote git repository using the --repo flag with zoi install.

# Install from a GitHub repository
zoi install --repo Zillowe/Hello

# Install from a GitLab repository
zoi install --repo gl:Zillowe/Hello

# Install from a Codeberg repository
zoi install --repo cb:Zillowe/Hello

This works if the target repository has a zoi.yaml file in its root. The package field in this file can specify a package name (e.g. hello), a path to a .pkg.lua file within the repository, or a URL to a .pkg.lua file. This provides a quick way to install packages from git repositories without permanently adding them to your configuration.

Provider Prefixes:

• gh: or github: for GitHub (this is the default if no prefix is given).
• gl: or gitlab: for GitLab.
• cb: or codeberg: for Codeberg.

Installing from a specific repository

• Top-level repository:

zoi install @community/htop

• Nested repository path (e.g. platform-specific):

zoi install @core/linux/amd64/nvidia-driver

To install a package from your custom git repository, use the @git/ prefix, followed by the repository name and the package name.

# Install from the root of 'my-zoi-repo'
zoi install @git/my-zoi-repo/package

# Install from a nested directory within the git repo
zoi install @git/my-zoi-repo/path/to/package

For creating packages, see Creating Packages.

For publishing packages, see Publishing Packages.

Nel Package Registry

All packages from the official core, main, extra, and community repositories are browsable and searchable on the Nel Registry. This provides a convenient way to discover new packages and view their details online.

The repo.yaml file

A Zoi package registry is defined by a repo.yaml file at its root. This file contains metadata about the repository, such as its name, description, and the URLs for its git repository and pre-built packages.

Here are the fields available in repo.yaml:

The repo-pkg and mirrors-pkg URLs can contain the following placeholders, which Zoi will replace at runtime:

• {os}: The operating system (e.g. linux, macos, windows).
• {arch}: The CPU architecture (e.g. amd64, arm64).
• {version}: The version of the package.
• {package}: The name of the package.

Example

name: Zoi repo
description: The official Zoi package repository.
repo-git: https://gitlab.com/Zillowe/Zillwen/Zusty/Zoi-Pkgs.git
mirrors-git:
  - https://github.com/Zillowe/Zoi-Pkgs.git
  - https://codeberg.org/Zillowe/Zoi-Pkgs.git
repo-pkg: https://zoi.zillowe.qzz.io/pkgs/{os}/{arch}/{version}/{package}
mirrors-pkg:
  - https://zoi.zilo.qzz.io/pkgs/{os}/{arch}/{version}/{package}