Quick Start

This guide will get you checking for updates in minutes.

Basic Usage

The simplest way to check for updates is using the convenience functions:

const std = @import("std");
const updater = @import("updater");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Check for updates on GitHub
    const result = try updater.checkGitHub(
        allocator,
        "ziglang",    // repository owner
        "zig",        // repository name
        "0.11.0",     // your current version
    );

    if (result.has_update) {
        std.debug.print("New version available: {s}\n", .{result.latest_version.?});
        std.debug.print("Download: {s}\n", .{result.release_url.?});
    } else {
        std.debug.print("You are running the latest version!\n", .{});
    }
}

Checking Different Providers

updater.zig supports multiple Git hosting providers:

// GitHub
const github_result = try updater.checkGitHub(allocator, "owner", "repo", "1.0.0");

// GitLab
const gitlab_result = try updater.checkGitLab(allocator, "owner", "repo", "1.0.0");

// Codeberg
const codeberg_result = try updater.checkCodeberg(allocator, "owner", "repo", "1.0.0");

Handling Results

The UpdateResult struct contains all information about the check:

const result = try updater.checkGitHub(allocator, "owner", "repo", "1.0.0");

// Check if the operation was skipped
if (result.skipped) {
    std.debug.print("Check skipped: {s}\n", .{@tagName(result.skip_reason)});
    return;
}

// Check for updates
if (result.has_update) {
    std.debug.print("Current: {s}\n", .{result.current_version});
    std.debug.print("Latest: {s}\n", .{result.latest_version.?});
    std.debug.print("URL: {s}\n", .{result.release_url.?});
}

Full Configuration

For more control, use the full configuration API:

const result = try updater.checkForUpdates(allocator, .{
    .enabled = true,
    .provider = updater.providers.github,
    .owner = "username",
    .repo = "myproject",
    .current_version = "1.0.0",
    .timeout_ms = 5000,
    .include_prereleases = false,
    .comparator = updater.version.semantic,
});

Error Handling

Update checks are designed to be non-fatal:

const result = updater.checkGitHub(allocator, "owner", "repo", "1.0.0") catch |err| {
    // Log the error but continue
    std.log.warn("Update check failed: {}", .{err});
    return;
};

// Process result...

Checking if Disabled

Before performing checks, you can verify if update checking is enabled:

// Check for global opt-out
if (updater.isGloballyDisabled()) {
    std.debug.print("Update checking is disabled\n", .{});
    return;
}

// Check for CI environment
if (updater.isCI()) {
    std.debug.print("Running in CI - skipping update check\n", .{});
    return;
}

Next Steps

• Build-time Checking - Integrate into your build process
• Runtime Checking - Advanced runtime options
• Version Comparison - Custom version comparison
• Custom Providers - Self-hosted Git servers