sigildocs

Dependency Redirects

Dependency redirects allow you to override where dependencies are resolved from during development. This enables working on a library while simultaneously building applications that depend on it.

Use Cases

  • Local development: Override a git dependency to use a local checkout
  • Fork development: Redirect an upstream repository to your fork
  • Testing changes: Test library changes across multiple dependent applications
  • Monorepo development: Work on Sigil packages while building apps that use them

Quick Start

Create a redirects file:

;;; my-redirects.sgl
(redirects
  repos: (list
    (for-repo
      url: "https://codeberg.org/sigil/sigil"
      use: (from-path dir: "/home/david/Projects/sigil"))))

Use it with any build command:

# Via environment variable
SIGIL_REDIRECTS=./my-redirects.sgl sigil build

# Via CLI flag
sigil build --redirects ./my-redirects.sgl

Redirects File Format

A redirects file is a Sigil source file that evaluates to a redirects struct. The necessary imports are provided automatically.

(redirects
  repos: (list
    ;; Repo redirects: match by repository URL
    )
  packages: (list
    ;; Package redirects: match by package name
    ))

Redirect Types

Repo Redirects (for-repo)

Redirect all packages from a repository URL to a different location:

;; Use local checkout instead of git
(for-repo
  url: "https://codeberg.org/sigil/sigil"
  use: (from-path dir: "/home/david/Projects/sigil"))

;; Use your fork instead of upstream
(for-repo
  url: "https://github.com/upstream/cool-lib"
  use: (from-git url: "https://codeberg.org/sigil/cool-lib-fork"))

;; Use a specific branch of your fork
(for-repo
  url: "https://github.com/upstream/other-lib"
  use: (from-git
         url: "https://codeberg.org/sigil/other-lib-fork"
         branch: "experimental"))

Package Redirects (for-package)

Redirect a specific package by name, regardless of how it was originally sourced:

;; Redirect to local path
(for-package
  name: "sigil-json"
  use: (from-path dir: "/home/david/Projects/sigil-json-dev"))

;; Redirect to a specific branch
(for-package
  name: "sigil-http"
  use: (from-git
         url: "https://codeberg.org/sigil/sigil"
         subpath: "packages/sigil-http"
         branch: "http-rewrite"))

Complete Example

;;; sigil-dev-redirects.sgl
;;;
;;; Local development redirects for working on Sigil while building apps.

(redirects
  repos: (list
    ;; Use local Sigil checkout for all sigil packages
    (for-repo
      url: "https://codeberg.org/sigil/sigil"
      use: (from-path dir: "/home/david/Projects/sigil"))

    ;; Use local Vessel checkout
    (for-repo
      url: "https://codeberg.org/sigil/vessel"
      use: (from-path dir: "/home/david/Projects/vessel")))

  packages: (list
    ;; Override: experimental JSON rewrite
    (for-package
      name: "sigil-json"
      use: (from-path dir: "/home/david/Projects/sigil-json-v2"))))

Resolution Precedence

When resolving a dependency:

  1. Package redirect (highest priority): If the package name matches a for-package entry
  2. Repo redirect: If no package redirect, check for-repo entries for URL matches
  3. Normal resolution: If no redirects match, resolve as specified in package.sgl

Transitive Application

Redirects apply to the entire dependency graph, not just direct dependencies. If your app depends on vessel, and vessel depends on sigil-json, a redirect for sigil-json affects vessel's dependency too.

This ensures consistent versions throughout the build.

URL Matching

Repo redirect URLs are matched after normalization:

  • Trailing slashes are stripped
  • .git suffix is stripped
  • Fragment identifiers (#ref) are stripped

These all match the same URL:

(for-repo url: "https://codeberg.org/sigil/sigil" ...)
(for-repo url: "https://codeberg.org/sigil/sigil/" ...)
(for-repo url: "https://codeberg.org/sigil/sigil.git" ...)

Configuration

Environment Variable

Set SIGIL_REDIRECTS in your shell profile or via direnv:

# ~/.bashrc
export SIGIL_REDIRECTS="$HOME/.sigil/dev-redirects.sgl"

# Or in .envrc for project-specific redirects
export SIGIL_REDIRECTS="./redirects.sgl"

CLI Flag

Override for a single command:

sigil build --redirects ./my-redirects.sgl
sigil deps --redirects ./my-redirects.sgl

Design Principles

  • External file only: Redirects are loaded from a separate file, not embedded in package.sgl
  • Evaluable code: The file is valid Sigil code that evaluates to a typed struct
  • Reuse existing types: Redirects use the same from-git and from-path dependency specs as package.sgl