### NUR Repositories Configuration Example

Source: https://github.com/nix-community/nur/blob/main/README.md

Configure your repository within NUR's 'repos.json' file. This example shows the structure for adding a new repository, including its URL.

```json
{
    "repos": {
        "mic92": {
            "url": "https://github.com/Mic92/nur-packages"
        },
        "<fill-your-repo-name>": {
            "url": "https://github.com/<your-user>/<your-repo>"
        }
    }
}
```

--------------------------------

### NUR CLI Global Options: Log Level Examples

Source: https://github.com/nix-community/nur/blob/main/_autodocs/cli-reference.md

Examples demonstrating how to set the log level for the NUR CLI to control verbosity.

```bash
./bin/nur --log-level debug update       # Verbose
```

```bash
./bin/nur --log-level info update        # Info only
```

```bash
./bin/nur --log-level error update       # Errors only
```

```bash
./bin/nur --log-level critical update    # Critical only
```

--------------------------------

### Example Repository Structure

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

Demonstrates the expected structure for a NUR repository, including packages, overlays, modules, and library functions.

```nix
{ pkgs }:
{
  # Packages
  hello = pkgs.callPackage ./hello {};

  # Overlays
  overlays = {
    example = final: prev: { ... };
  };

  # Modules
  nixosModules = import ./modules;

  # Library functions
  lib = {
    myFunction = x: x + 1;
  };
}
```

--------------------------------

### Install NUR package with nix-env

Source: https://github.com/nix-community/nur/blob/main/README.md

Install a package from NUR using the nix-env command.

```console
$ nix-env -f '<nixpkgs>' -iA nur.repos.mic92.hello-nur

```

--------------------------------

### Allowed Parameter Pattern: Good Example 2

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

A valid parameter pattern for a Nix function that accepts only 'pkgs'.

```nix
# GOOD: takes only pkgs
{ pkgs }:
{ hello = ...; }
```

--------------------------------

### Allowed Parameter Pattern: Good Example 1

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

A valid parameter pattern for a Nix function that accepts 'pkgs' and has default values for other parameters.

```nix
# GOOD: takes pkgs, has default values for others
{ pkgs, lib ? <lib>, ... }:
{ hello = ...; }
```

--------------------------------

### NUR Update Command Output Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/cli-reference.md

An example of the output produced by the 'nur update' command, showing repository updates and errors.

```bash
DEBUG:nur.update:Updated repository 0komo -> 895f0fe9ced70b1a93050aff3ce0803761a1a36f
DEBUG:nur.update:Updated repository 0x4A6F -> 0514d23b1eff0ee3d66d42266b0ca8230dc82d9a
ERROR:nur.update:repository badpkg failed to evaluate: badpkg does not evaluate:
$ nix-env -f /tmp/.../default.nix -qa * ...
/nix/store/...-badpkg/default.nix:5:1: error: undefined variable
ERROR:nur.update:Failed to update repository deleted-repo
Traceback (most recent call last):
  ... 
nur.error.RepositoryDeletedError: Repository deleted!
```

--------------------------------

### Repository URL Configuration Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Specifies the Git repository URL for a NUR package.

```json
{
  "url": "https://github.com/Mic92/nur-packages"
}
```

--------------------------------

### Custom Nix File Path Configuration Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Specifies a custom Nix file path within the repository to be used as the entry point.

```json
{
  "url": "https://github.com/user/repo",
  "file": "nur.nix"
}
```

--------------------------------

### Commit Message with Link Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/modules.md

Demonstrates the format for commit messages when a repository is initialized, including a link to the commit.

```text
{name}: init at {rev} ({link-to-combine-commit})
```

--------------------------------

### Allowed Parameter Pattern: Bad Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

An invalid parameter pattern that uses callPackage-style arguments and will result in an error.

```nix
# BAD: uses callPackage-style (will error)
{ stdenv, fetchurl, lib }:
stdenv.mkDerivation { ... }
```

--------------------------------

### NUR Default Entry Point Usage in flake.nix

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

Example of how to integrate the NUR default entry point as an overlay in a Nix flake configuration.

```nix
overlay = final: prev: {
  nur = import ./default.nix {
    nurpkgs = prev;
    pkgs = prev;
  };
};

```

--------------------------------

### NUR Package Derivation Example

Source: https://github.com/nix-community/nur/blob/main/README.md

A detailed Nix derivation for a 'hello' package, demonstrating how to define sources, patches, and metadata for a package within NUR.

```nix
{ stdenv, fetchurl, lib }:

stdenv.mkDerivation rec {
  pname = "hello";
  version = "2.10";

  src = fetchurl {
    url = "mirror://gnu/hello/${pname}-${version}.tar.gz";
    sha256 = "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i";
  };

  postPatch = ''
    sed -i -e 's/Hello, world!/Hello, NUR!/' src/hello.c
  '';

  # fails due to patch
  doCheck = false;

  meta = with lib; {
    description = "A program that produces a familiar, friendly greeting";
    longDescription = ''
      GNU Hello is a program that prints "Hello, world!" when you run it.
      It is fully customizable.
    '';
    homepage = https://www.gnu.org/software/hello/manual/;
    changelog = "https://git.savannah.gnu.org/cgit/hello.git/plain/NEWS?h=v${version}";
    license = licenses.gpl3Plus;
    maintainers = [ maintainers.eelco ];
    platforms = platforms.all;
  };
}
```

--------------------------------

### Example repos.json Manifest

Source: https://github.com/nix-community/nur/blob/main/_autodocs/README.md

Defines the repositories to be managed by nur. This file should be edited manually and validated using the `nur format-manifest` command.

```json
{
  "repos": {
    "repository-name": {
      "url": "https://...",
      "github-contact": "username"
    }
  }
}
```

--------------------------------

### Nix Evaluation Success Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/errors.md

Demonstrates the correct way to structure Nix expressions to pass evaluation, by properly accepting and using the 'pkgs' argument.

```nix
# GOOD: will pass evaluation
{ pkgs }:
{ hello = pkgs.stdenv.mkDerivation { ... }; }
```

--------------------------------

### Submodule Enabled Configuration Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Enables submodule fetching for a repository. This requires using a generic git clone instead of archive APIs.

```json
{
  "url": "https://github.com/user/repo",
  "submodules": true
}
```

--------------------------------

### Nested Custom Nix File Path Configuration Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Specifies a custom Nix file path in a nested directory within the repository.

```json
{
  "url": "https://example.com/config",
  "file": "packages/default.nix"
}
```

--------------------------------

### GitHub Contact Configuration Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Provides the GitHub username for repository maintenance and issue contact.

```json
{
  "github-contact": "Mic92"
}
```

--------------------------------

### RepoType Enumeration Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/types.md

Shows how to access RepoType enum members and determine the type of a repository.

```python
from nur.manifest import RepoType, Repo

# Direct access to enum members
assert RepoType.GITHUB.value == 1
assert RepoType.GITLAB.value == 2
assert RepoType.GIT.value == 3

# Determine type for a repo
repo = load_manifest(...).repos[0]
if repo.type == RepoType.GITHUB:
    print("Uses GitHub archive API")
elif repo.type == RepoType.GITLAB:
    print("Uses GitLab API")
else:
    print("Uses git clone")
```

--------------------------------

### Get Nixpkgs Path

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

Retrieves the absolute path to the nixpkgs installation. The result is cached after the first call.

```python
from nur.path import nixpkgs_path

print(nixpkgs_path())  # /nix/store/...-nixpkgs-unstable
```

--------------------------------

### Url Type Alias Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/types.md

Demonstrates how to use the Url type alias by parsing a URL string and accessing its components.

```python
from urllib.parse import urlparse

url = urlparse("https://github.com/user/repo")
# url is of type ParseResult (aliased as Url)
# url.scheme == "https"
# url.hostname == "github.com"
# url.path == "/user/repo"
# url.geturl() == "https://github.com/user/repo"
```

--------------------------------

### NUR Repositories Configuration

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Example of how to define repositories in the NUR configuration file, including local and remote sources with different types and configurations.

```json
{
  "repos": {
    "mic92": {
      "url": "https://github.com/Mic92/nur-packages",
      "github-contact": "Mic92"
    },
    "custom-gl": {
      "url": "https://gitlab.company.com/team/packages",
      "github-contact": "team-lead",
      "type": "gitlab"
    },
    "local-packages": {
      "url": "https://github.com/user/local",
      "github-contact": "user",
      "file": "packages.nix",
      "branch": "develop"
    },
    "with-submodules": {
      "url": "https://github.com/user/complex",
      "github-contact": "user",
      "submodules": true
    }
  }
}
```

--------------------------------

### NUR Lock File Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/README.md

Pins each repository to a specific commit, updated automatically by the 'nur update' command.

```json
{
  "repos": {
    "mic92": {
      "url": "https://github.com/Mic92/nur-packages",
      "rev": "abc123def456...",
      "sha256": "1zf9dqyq..."
    }
  }
}
```

--------------------------------

### Specific Branch Tracking Configuration Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Configures the repository to track a specific branch instead of the default branch.

```json
{
  "url": "https://github.com/user/repo",
  "branch": "stable"
}
```

--------------------------------

### NUR CLI Global Options

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Example of using the global --log-level option with the NUR CLI to control output verbosity.

```bash
./bin/nur [--log-level {debug,info,error,critical}] SUBCOMMAND [args...]
```

```bash
./bin/nur --log-level info update
```

--------------------------------

### Install NUR package in nix-shell

Source: https://github.com/nix-community/nur/blob/main/README.md

Use a package from NUR within a nix-shell by referencing its attribute path.

```console
$ nix-shell -p nur.repos.mic92.hello-nur
nix-shell> hello
Hello, NUR!

```

--------------------------------

### JSON Configuration for NUR Repository

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Example of a repository entry in repos.json, showing the 'url' field and indicating that the 'file' field defaults to 'default.nix' if not explicitly specified.

```json
{
  "repository": {
    "url": "https://example.com/repo"
    // file defaults to "default.nix"
  }
}
```

--------------------------------

### Explicit Git Type Configuration Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Explicitly sets the repository type to 'git' for self-hosted git servers.

```json
{
  "url": "https://git.example.com/packages",
  "type": "git"
}
```

--------------------------------

### nur.path.nixpkgs_path

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

Retrieves the absolute path to the nixpkgs installation on the system. The result is cached after the first call to optimize performance.

```APIDOC
## nur.path.nixpkgs_path

### Description
Returns the path to the nixpkgs installation, cached after first call.

### Method
```python
def nixpkgs_path() -> str
```

### Return Type
`str` — Absolute path to nixpkgs

### Details
Uses `nix-instantiate --find-file nixpkgs` to locate nixpkgs on the system. Result is cached in a module-level variable.

### Example

```python
from nur.path import nixpkgs_path
print(nixpkgs_path())  # /nix/store/...-nixpkgs-unstable
```
```

--------------------------------

### Nix Evaluation Failed Example (Bad Syntax)

Source: https://github.com/nix-community/nur/blob/main/_autodocs/errors.md

Illustrates a common Nix syntax error that leads to an EvalError. It shows the incorrect use of 'with import <nixpkgs>' instead of passing 'pkgs' as an argument.

```nix
# BAD: will fail evaluation
{ }:
with import <nixpkgs>;
{ hello = stdenv.mkDerivation { ... }; }
```

--------------------------------

### Home Manager Configuration without Flakes

Source: https://github.com/nix-community/nur/blob/main/README.md

Integrate NUR modules into your Home Manager configuration when not using flakes. This example demonstrates fetching NUR via tarball and importing its Home Manager modules.

```nix
let
  nur-no-pkgs = import (builtins.fetchTarball "https://github.com/nix-community/NUR/archive/main.tar.gz") {};
in
{
  imports = lib.attrValues nur-no-pkgs.repos.moredhel.homeModules;
}
```

--------------------------------

### Logging Output for New Repository EvalError

Source: https://github.com/nix-community/nur/blob/main/_autodocs/errors.md

Example log output when a new repository fails evaluation, indicating a critical issue that might prevent its addition to the lock file.

```text
# New repository failed
ERROR:nur.update:repository newfoo failed to evaluate: newfoo does not evaluate:
$ nix-env -f /tmp/.../default.nix -qa * ...
newfoo/default.nix:5:1: error: attempt to call something which is not a function but a set
```

--------------------------------

### NUR Repository Manifest Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/README.md

Defines a repository in NUR, specifying its URL and contact information. Supports optional configurations like type, submodules, file, and branch.

```json
{
  "repos": {
    "mic92": {
      "url": "https://github.com/Mic92/nur-packages",
      "github-contact": "Mic92"
    }
  }
}
```

--------------------------------

### Explicit GitLab Type Configuration Example

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Explicitly sets the repository type to 'gitlab' for GitLab instances on custom domains.

```json
{
  "url": "https://gitlab.company.com/team/packages",
  "type": "gitlab"
}
```

--------------------------------

### Development Shell for NUR Package

Source: https://github.com/nix-community/nur/blob/main/README.md

Use 'nix-shell' to enter a development environment for a NUR package. This example shows how to specify the Nixpkgs version and access the package within the shell.

```console
$ nix-shell --arg pkgs 'import <nixpkgs> {}' -A hello-nur
nix-shell> hello
nix-shell> find $buildInputs
```

--------------------------------

### Example repos.json.lock Lock File

Source: https://github.com/nix-community/nur/blob/main/_autodocs/README.md

Pins repositories to specific commits, ensuring reproducible builds. This file is automatically generated by the `nur update` command.

```json
{
  "repos": {
    "repository-name": {
      "url": "https://...",
      "rev": "abc123...",
      "sha256": "..."
    }
  }
}
```

--------------------------------

### Set PATH Environment Variable for NUR

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Example of setting the PATH environment variable to include necessary Nix binaries for NUR operations.

```bash
PATH=/nix/var/nix/profiles/default/bin:$PATH ./bin/nur update
```

--------------------------------

### Use NUR flake in NixOS configuration

Source: https://github.com/nix-community/nur/blob/main/README.md

Integrate NUR overlays and modules into your NixOS configuration. This example shows how to add the NUR overlay and import specific NUR modules.

```nix
{ 
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
    nur = {
      url = "github:nix-community/NUR";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, nur }:
    {
    nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
      # ...
      modules = [
        # Adds the NUR overlay
        nur.modules.nixos.default
        # NUR modules can be imported directly:
        nur.repos.iopq.modules.nixos.xraya
        # Or via legacyPackages (legacy path):
        # nur.legacyPackages."${system}".repos.iopq.modules.xraya
        # This adds the NUR nixpkgs overlay.
        # Example:
        # ({ pkgs, ... }:
        # ({ 
        #   environment.systemPackages = [ pkgs.nur.repos.mic92.hello-nur ];
        # }))
      ];
    };
  };
}

```

--------------------------------

### Lock File Management with Python

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Python code examples for locking and unlocking repositories in the NUR lock file using the LockedVersion class and update_lock_file function.

```python
# To lock a repository to a specific commit:
repo.locked_version = LockedVersion(
    url=urlparse(repo.url),
    rev="abc123def456...",
    sha256="...",
    submodules=False
)
update_lock_file([repo], Path("repos.json.lock"))

# To unlock (remove from lock):
repo.locked_version = None
update_lock_file([repo], Path("repos.json.lock"))
```

--------------------------------

### Logging Output for Existing Repository EvalError

Source: https://github.com/nix-community/nur/blob/main/_autodocs/errors.md

Example log output when an existing repository fails evaluation, showing that the error is logged but the previous lock version is retained.

```text
# Existing repository failed
ERROR:nur.update:repository example failed to evaluate: example does not evaluate:
$ nix-env -f /tmp/.../default.nix -qa * ...
example: invalid license value 'Apache'
```

--------------------------------

### Home Manager Configuration with NUR Flakes

Source: https://github.com/nix-community/nur/blob/main/README.md

Integrate NUR modules into your Home Manager configuration when using flakes. This example shows how to import Home Manager modules from NUR and configure the 'unison' service.

```nix
{ # In your Home Manager configuration
  imports = lib.attrValues nur.repos.moredhel.modules.homeManager;

  services.unison = {
    enable = true;
    profiles = {
      org = {
        src = "/home/moredhel/org";
        dest = "/home/moredhel/org.backup";
        extraArgs = "-batch -watch -ui text -repeat 60 -fat";
      };
    };
  };
}
```

--------------------------------

### nur.prefetch.GitPrefetcher

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

Prefetches git repositories by querying the git protocol and using `nix-prefetch-git`. The constructor takes a `Repo` object, and it provides methods to get the latest commit hash and prefetch a specific reference.

```APIDOC
## nur.prefetch.GitPrefetcher

### Description
Prefetches git repositories by querying git protocol and using nix-prefetch-git.

### Constructor
#### GitPrefetcher(repo: Repo)

**Parameters:**
- **repo** (Repo) - Required - Repository object to prefetch

### Methods
#### GitPrefetcher.latest_commit

##### Description
Queries the remote repository's git info refs to get the latest commit hash of the tracked branch/HEAD.

##### Method
Async Python Method

##### Return Type
- `str` — Git commit hash (SHA1)

##### Raises
- `RepositoryDeletedError` — if repository responds with 401
- `NurError` — if refs cannot be retrieved

##### Example
```python
import asyncio
from nur.manifest import load_manifest
from nur.prefetch import GitPrefetcher

repo = load_manifest(Path("repos.json"), Path("repos.json.lock")).repos[0]
prefetcher = GitPrefetcher(repo)
commit = asyncio.run(prefetcher.latest_commit())
print(f"Latest commit: {commit}")
```

#### GitPrefetcher.prefetch

##### Description
Prefetches a specific git reference (commit, branch, or tag) from the repository.

##### Method
Async Python Method

##### Parameters
- **ref** (str) - Required - The git reference to prefetch (e.g., commit hash, branch name, tag name)

##### Return Type
- `Tuple[str, Path]` — (sha256_hash, extracted_path)

##### Raises
- `RepositoryDeletedError` — if repository responds with 401
- `NurError` — if the ref cannot be fetched or prefetch fails

##### Example
```python
import asyncio
from nur.manifest import load_manifest
from nur.prefetch import GitPrefetcher

repo = load_manifest(Path("repos.json"), Path("repos.json.lock")).repos[0]
prefetcher = GitPrefetcher(repo)

# Prefetch a specific commit
sha256, path = asyncio.run(prefetcher.prefetch("abcdef1234567890abcdef1234567890abcdef12"))
print(f"Prefetched commit hash: {sha256}")
print(f"Extracted path: {path}")

# Prefetch a branch
sha256_branch, path_branch = asyncio.run(prefetcher.prefetch("main"))
print(f"Prefetched branch main hash: {sha256_branch}")
print(f"Extracted path: {path_branch}")
```
```

--------------------------------

### List all packages from a specific NUR repository

Source: https://github.com/nix-community/nur/blob/main/_autodocs/cli-reference.md

Lists all packages belonging to a specific repository within the NUR index. This uses jq to filter package keys based on a starting string.

```bash
./bin/nur index > packages.json

# List all packages from specific repo
jq 'keys[] | select(startswith("nur.repos.mic92.")) | .[19:]' packages.json
```

--------------------------------

### NUR Default Entry Point Usage with legacy packageOverrides

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

Demonstrates using the NUR default entry point with legacy packageOverrides in Nix.

```nix
packageOverrides = pkgs: {
  nur = import (builtins.fetchTarball "https://...") {
    inherit pkgs;
  };
};

```

--------------------------------

### Consumer Code Example for EvalError

Source: https://github.com/nix-community/nur/blob/main/_autodocs/errors.md

An example of a consumer function that safely updates a repository, catching EvalError and returning None to use the existing lock if evaluation fails.

```python
from nur.error import EvalError
from nur.update import update
import asyncio

async def safe_update(repo):
    try:
        updated = await update(repo)
        print(f"Updated {repo.name}")
        return updated
    except EvalError as e:
        print(f"Repository {repo.name} has evaluation errors: {e}")
        return None  # Use existing lock
```

--------------------------------

### Get Latest Commit Hash

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

Queries the remote repository's git info refs to get the latest commit hash of the tracked branch/HEAD. Uses the git protocol `/info/refs?service=git-upload-pack` endpoint to fetch available refs, then searches for HEAD (or the specified branch) and returns its commit hash.

```python
import asyncio
from nur.prefetch import GitPrefetcher
from nur.manifest import load_manifest
from pathlib import Path

repo = load_manifest(Path("repos.json"), Path("repos.json.lock")).repos[0]
prefetcher = GitPrefetcher(repo)
commit = asyncio.run(prefetcher.latest_commit())
print(f"Latest commit: {commit}")
```

--------------------------------

### Verify Repository Configuration with Nix

Source: https://github.com/nix-community/nur/blob/main/_autodocs/errors.md

Tests if repo-source can be built, verifying prefetch settings. Use these commands to check your repository configuration.

```bash
nix-instantiate --find-file nixpkgs
nix-build -A repo-sources.myrepo --no-out-link
```

--------------------------------

### NUR Default Entry Point Usage with local overrides

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

Shows how to use local overrides for the NUR default entry point, typically for development or testing purposes.

```nix
import ./default.nix {
  inherit pkgs;
  repoOverrides = {
    # Replace mic92 repository with local version during development
    mic92 = import ../my-nur-packages { inherit pkgs; };
  };
}

```

--------------------------------

### Create a combined NUR repository

Source: https://github.com/nix-community/nur/blob/main/_autodocs/cli-reference.md

Sets up a new directory to combine multiple NUR repositories. This involves initializing a new directory and using the 'combine' command.

```bash
# First time setup
mkdir ~/nur-combined && cd ~/nur-combined

# Combine all repositories
cd /path/to/nur && ./bin/nur combine ~/nur-combined

# Results in:
# ~/nur-combined/repos/mic92/default.nix
# ~/nur-combined/repos/example/default.nix
# ~/nur-combined/repos.json
# ~/nur-combined/repos.json.lock
# ~/nur-combined/.git (with full history)
```

--------------------------------

### NUR Repository Structure with Default Nix File

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Illustrates the expected file structure within a NUR repository when 'default.nix' is used as the main entry point. This includes the default.nix file itself and a packages directory.

```text
repository/
├── default.nix          (entry point)
└── packages/
    ├── foo.nix
    └── bar.nix
```

--------------------------------

### Debug NUR Evaluation

Source: https://github.com/nix-community/nur/blob/main/_autodocs/00-START-HERE.txt

Run the NUR CLI with the debug log level to get detailed output during repository evaluation.

```bash
./bin/nur --log-level debug eval /path/to/repo
```

--------------------------------

### NUR Source Implementation Details: repoSource and createRepo

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

Helper functions used by default.nix for fetching and evaluating repository sources. `repoSource` handles fetching, and `createRepo` evaluates the repository.

```nix
repoSource = name: attr:
  import ./lib/repoSource.nix {
    inherit name attr manifest lockedRevisions lib;
    fetchgit = builtins.fetchGit or nurpkgs.fetchgit;
    fetchzip = builtins.fetchTarball or nurpkgs.fetchzip;
  };

createRepo = name: attr:
  import ./lib/evalRepo.nix {
    inherit name pkgs lib;
    inherit (attr) url;
    src = repoSource name attr + ("/" + (attr.file or ""));
  };

```

--------------------------------

### Main Entry Point

Source: https://github.com/nix-community/nur/blob/main/_autodocs/README.md

The `main` function serves as the primary entry point for the Nur CLI. It parses command-line arguments and executes the corresponding subcommand.

```APIDOC
## Main Entry Point

### Description
The `main` function is the primary entry point for the Nur CLI. It parses `sys.argv` and executes the appropriate subcommand.

### Function Signature
```python
from nur import main
main()
```

### Usage
This function is typically called internally when the `nur` command is executed from the terminal.
```

--------------------------------

### Building NUR Package with nix-build

Source: https://github.com/nix-community/nur/blob/main/README.md

Build a NUR package using 'nix-build'. This command compiles the specified package, making it available in the Nix store.

```console
$ nix-build --arg pkgs 'import <nixpkgs> {}' -A hello-nur
```

--------------------------------

### Create a Combined Repository

Source: https://github.com/nix-community/nur/blob/main/_autodocs/README.md

Assemble all repositories into a single, unified directory structure while preserving their complete git history. This is useful for creating a consolidated view of multiple repositories.

```bash
mkdir ~/nur-combined
./bin/nur combine ~/nur-combined
```

--------------------------------

### Building NUR Package with Default pkgs Argument

Source: https://github.com/nix-community/nur/blob/main/README.md

Build a NUR package when the 'pkgs' argument has a default value. This simplifies the build command as 'pkgs' does not need to be explicitly provided.

```console
$ nix-build -A hello-nur
```

--------------------------------

### Run Index Command

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

CLI subcommand handler that indexes all repositories and outputs the combined package metadata as JSON to stdout.

```bash
$ python -m nur index /path/to/nur | jq '.["nur.repos.mic92.hello"] | .meta.description'
```

--------------------------------

### Applying NUR Overlay in NixOS System Configuration

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

Shows how to apply the NUR overlay to a NixOS system configuration within a flake. This makes NUR packages available to the system.

```nix
{ 
  outputs = { self, nixpkgs, nur }:
  {
    nixosConfigurations.my-system = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [ 
        { nixpkgs.overlays = [ nur.overlays.default ]; }
        ./configuration.nix
      ];
    };
  };
}
```

--------------------------------

### NUR Eval Command Use Case: Diagnose Evaluation Failure

Source: https://github.com/nix-community/nur/blob/main/_autodocs/cli-reference.md

Example of using 'nur eval' to diagnose an evaluation failure in a broken repository.

```bash
# Diagnose evaluation failure
./bin/nur eval /tmp/broken-repo
# EvalError: broken-repo does not evaluate:
# $ nix-env -f /tmp/.../default.nix -qa * ...
# default.nix:5: error: attempt to call something which is not a function but a set
```

--------------------------------

### NUR Eval Command Use Case: Test Current Directory Repository

Source: https://github.com/nix-community/nur/blob/main/_autodocs/cli-reference.md

Example of using 'nur eval' to test the repository in the current directory.

```bash
# Test repository from current directory
cd /path/to/repo && ./bin/nur eval
# OK
```

--------------------------------

### NUR Eval Command Use Case: Test Local Repository

Source: https://github.com/nix-community/nur/blob/main/_autodocs/cli-reference.md

Example of using 'nur eval' to test a local repository before adding it to NUR.

```bash
# Test a local repository before adding to NUR
./bin/nur eval /tmp/my-nur-packages
# OK
```

--------------------------------

### NUR Default Entry Point Definition

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

The main entry point for NUR, responsible for assembling the package set from registered repositories. It accepts Nixpkgs instances and repository overrides.

```nix
{ 
  nurpkgs ? import <nixpkgs> { }, # For nixpkgs dependencies used by NUR itself
  pkgs ? (
    import <nixpkgs> {
      overrides = [ 
        (final: prev: if prev ? nur then prev else { nur = import ./. { pkgs = final; }; })
      ];
    }
  ),
  repoOverrides ? { },
}:

```

--------------------------------

### CLI Index Command

Source: https://github.com/nix-community/nur/blob/main/_autodocs/README.md

Index all packages available across the managed repositories. The output, which is in JSON format, is printed to standard output.

```bash
./bin/nur index
# Outputs JSON to stdout
```

--------------------------------

### Use single NUR package in a flake devshell

Source: https://github.com/nix-community/nur/blob/main/README.md

Add a single package from NUR to a devshell defined in a flake.nix. This example uses flake-utils and overlays the NUR package.

```nix
{ 
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
    nur = {
      url = "github:nix-community/NUR";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { self, nixpkgs, flake-utils, nur }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs {
          inherit system;
          overlays = [ nur.overlays.default ];
        };
      in
      {
        devShells.default = pkgs.mkShell {
          packages = [ pkgs.nur.repos.mic92.hello-nur ];
        };
      }
    );
}

```

--------------------------------

### Create Manifest from Repos

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

Constructs a Manifest object containing a list of Repo objects. Use this to manage a collection of repositories defined in a NUR manifest.

```python
from nur.manifest import Manifest, Repo
manifest = Manifest(repos=[repo1, repo2, repo3])
for repo in manifest.repos:
    print(repo.name)
```

--------------------------------

### Fetch GitHub Repository Archive

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

Fetches a GitHub repository as a zip archive. Efficient for repositories without submodules.

```nix
fetchzip {
  url = "${attr.url}/archive/${revision.rev}.zip";
  inherit (revision) sha256;
}
```

--------------------------------

### Get Repository Prefetcher

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

Factory function that returns the appropriate prefetcher class for a repository type. Uses the repository's `type` property to select the correct prefetch strategy.

```python
from nur.manifest import load_manifest
from nur.prefetch import prefetcher_for
import asyncio

manifest = load_manifest(Path("repos.json"), Path("repos.json.lock"))
repo = manifest.repos[0]

prefetcher = prefetcher_for(repo)
# Returns GithubPrefetcher, GitlabPrefetcher, or GitPrefetcher depending on repo.type

# Use prefetcher
latest_commit = asyncio.run(prefetcher.latest_commit())
```

--------------------------------

### GitPrefetcher Class Definition

Source: https://github.com/nix-community/nur/blob/main/_autodocs/types.md

Base class for prefetching Git repository information. It initializes with a Repo object and provides methods to get the latest commit and prefetch source code.

```python
class GitPrefetcher:
    def __init__(self, repo: Repo) -> None:
        self.repo = repo

    async def latest_commit(self) -> str:
        # ... git protocol querying ...
        return parts[0].decode()

    async def prefetch(self, ref: str) -> Tuple[str, Path]:
        # ... nix-prefetch-git invocation ...
        return sha256, path
```

--------------------------------

### GitPrefetcher.prefetch

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

Fetches and hashes a git repository at the specified reference. Invokes `nix-prefetch-git` with optional `--fetch-submodules` flag if the repository uses submodules. Returns the SHA256 hash and path to the fetched repository. Has a 30s timeout.

```python
async def prefetch(self, ref: str) -> Tuple[str, Path]
```

--------------------------------

### NUR Repository Package Definition

Source: https://github.com/nix-community/nur/blob/main/README.md

Define a package within your NUR repository. This example shows a typical Nix derivation for a package, including fetching source, applying patches, and setting metadata.

```nix
{ pkgs }:
{
  hello-nur = pkgs.callPackage ./hello-nur {};
}
```

--------------------------------

### Prefetcher Hierarchy

Source: https://github.com/nix-community/nur/blob/main/_autodocs/modules.md

Illustrates the inheritance structure of prefetcher classes, showing the base GitPrefetcher and its specialized subclasses for GitHub and GitLab.

```text
GitPrefetcher (base)
├── latest_commit() — Query git refs via HTTP
├── prefetch() — Use nix-prefetch-git
│
├─→ GithubPrefetcher
│   └── prefetch() — Use GitHub archive API (faster)
│
└─→ GitlabPrefetcher
    └── prefetch() — Use GitLab API (faster)
```

--------------------------------

### Index Repository Packages

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

Indexes all packages within a specified repository using nix-env query. It adds metadata like source location and returns a dictionary of package information.

```python
from pathlib import Path
from nur.index import index_repo

pkgs = index_repo(
    directory=Path("/tmp/nur"),
    repo="mic92",
    expression_file="default.nix",
    url="https://github.com/Mic92/nur-packages"
)
for pkg_name, metadata in pkgs.items():
    print(f"{pkg_name}: {metadata['_repo']}")
```

--------------------------------

### Enable Unsupported Systems for Evaluation

Source: https://github.com/nix-community/nur/blob/main/_autodocs/README.md

Set the `NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM` environment variable to `1` to permit Nix evaluation on unsupported platforms. This is often required for certain development or build environments.

```bash
NIXPKGS_ALLOW_UNSUPPORTED_SYSTEM=1 ./bin/nur update
```

--------------------------------

### Schedule weekly NUR index generation with Cron

Source: https://github.com/nix-community/nur/blob/main/_autodocs/cli-reference.md

Sets up a weekly cron job to generate the NUR package index. This can be used to update a public package list.

```bash
# Weekly index
0 0 * * 0 cd /path/to/nur && ./bin/nur index > /var/www/packages.json
```

--------------------------------

### Evaluate a local repository

Source: https://github.com/nix-community/nur/blob/main/_autodocs/cli-reference.md

Tests a local repository's Nix expressions before adding it to the main NUR configuration. This helps catch errors early.

```bash
./bin/nur eval ~/nur-packages
```

--------------------------------

### NUR Default Entry Point Output Attributes

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

Defines the structure of the output from the NUR default entry point, including evaluated repositories and their source paths.

```nix
{
  repos = {
    # Each repository is evaluated and accessible as an attribute
    # Example: repos.mic92 evaluates the mic92 repository
    mic92 = import ./lib/evalRepo.nix { ... };
    example = import ./lib/evalRepo.nix { ... };
  };

  repo-sources = {
    # Source paths for each repository (before evaluation)
    # Used internally by nix-build to fetch sources
    mic92 = <fetched-source>;
    example = <fetched-source>;
  };
}

```

--------------------------------

### nur.prefetch.nix_prefetch_zip

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

Asynchronously fetches and hashes a zip or tarball using `nix-prefetch-url`. It returns the computed SHA256 hash and the path to the extracted contents. Raises `NurError` if the prefetching fails.

```APIDOC
## nur.prefetch.nix_prefetch_zip

### Description
Asynchronously fetches and hashes a zip/tarball using nix-prefetch-url. Invokes `nix-prefetch-url --name source --unpack --print-path <url>` to fetch, verify, and extract an archive. Returns both the computed SHA256 hash and the path to extracted contents. Raises `NurError` if nix-prefetch-url fails.

### Method
Async Python Function

### Parameters
#### Path Parameters
- **url** (str) - Required - URL to archive to fetch

### Response
#### Success Response
- **Return Type:** `Tuple[str, Path]` — (sha256_hash, extracted_path)

### Example
```python
import asyncio
from nur.prefetch import nix_prefetch_zip

async def fetch():
    sha256, path = await nix_prefetch_zip(
        "https://github.com/user/repo/archive/main.tar.gz"
    )
    print(f"Hash: {sha256}")
    print(f"Path: {path}")

asyncio.run(fetch())
```
```

--------------------------------

### Per-System Configuration for NUR Packages

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

Configures the availability of NUR packages for each system, making them accessible via `legacyPackages.${system}.repos.<name>.<package>`.

```nix
perSystem = { pkgs, ... }:
{
  formatter = pkgs.treefmt.withConfig { ... };

  # legacyPackages is used because nur is a package set
  legacyPackages = (pkgs.extend overlay).nur;
};
```

--------------------------------

### Main Entry Point for nur CLI

Source: https://github.com/nix-community/nur/blob/main/_autodocs/README.md

The `main` function serves as the primary entry point for the nur command-line interface. It parses command-line arguments and executes the appropriate subcommand.

```python
from nur import main
main()  # Parses sys.argv and executes subcommand
```

--------------------------------

### Add a Repository Workflow

Source: https://github.com/nix-community/nur/blob/main/_autodocs/00-START-HERE.txt

Steps to add a new repository to NUR. This involves editing the manifest file, formatting it, evaluating the repository, and updating it.

```bash
1. Edit repos.json with new entry
2. ./bin/nur format-manifest
3. ./bin/nur eval /path/to/repo
4. ./bin/nur update
```

--------------------------------

### NUR Python Repo Class File Handling

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Code snippet from the NUR Python module demonstrating how the 'file' attribute is handled. If no file is specified, it defaults to 'default.nix'.

```python
if file_ is None:
    self.file = "default.nix"
else:
    self.file = file_
```

--------------------------------

### Default Nix Expression File

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

When no specific file is provided for evaluation, NUR defaults to using 'default.nix' as the entry point for a repository. This structure is common for Nix projects.

```nix
{ pkgs }:
{
  foo = pkgs.callPackage ./packages/foo.nix { };
  bar = pkgs.callPackage ./packages/bar.nix { };
}
```

--------------------------------

### Find packages by description

Source: https://github.com/nix-community/nur/blob/main/_autodocs/cli-reference.md

Searches all indexed NUR packages for those whose description contains a specific keyword. This command evaluates all repositories, so it can be slow.

```bash
./bin/nur index | jq 'to_entries[] | select(.value.meta.description | contains("python")) | .key'
```

--------------------------------

### Add NUR to packageOverrides in config.nix

Source: https://github.com/nix-community/nur/blob/main/README.md

Make NUR accessible for your login user by adding it to your ~/.config/nixpkgs/config.nix file using packageOverrides.

```nix
{ 
  packageOverrides = pkgs: { 
    nur = import (builtins.fetchTarball "https://github.com/nix-community/NUR/archive/main.tar.gz") { 
      inherit pkgs; 
    };
  };
}

```

--------------------------------

### CLI Format Manifest Command

Source: https://github.com/nix-community/nur/blob/main/_autodocs/README.md

Validate and normalize the `repos.json` manifest file. This command ensures the manifest adheres to the expected schema and formatting.

```bash
./bin/nur format-manifest
```

--------------------------------

### NUR Repository with Custom File Path

Source: https://github.com/nix-community/nur/blob/main/README.md

Specify a custom Nix file to load packages from within a NUR repository. Use the 'file' option to point to a different file than 'default.nix'.

```json
{
    "repos": {
        "mic92": {
            "url": "https://github.com/Mic92/nur-packages",
            "file": "subdirectory/default.nix"
        }
    }
}
```

--------------------------------

### Schedule daily NUR updates with Cron

Source: https://github.com/nix-community/nur/blob/main/_autodocs/cli-reference.md

Sets up a daily cron job to automatically update NUR repositories. This ensures the package index is current.

```bash
# Daily update
0 0 * * * cd /path/to/nur && ./bin/nur --log-level info update && git commit -am "daily update"
```

--------------------------------

### nur.combine.combine_command

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

Handles the CLI subcommand for combining NUR repositories, setting up git, and calling the update function.

```APIDOC
## nur.combine.combine_command

### Description
CLI subcommand handler for combining NUR repositories.

### Method
```python
async def combine_command(args: Namespace) -> None
```

### Parameters
#### Path Parameters
- **args** (Namespace) - Required - Parsed args with `directory` attribute

### Details
Sets up git in the target directory (if not already a git repo) and calls `update_combined` to sync all repositories.

### Return Type
`None`

### Example

```python
from argparse import Namespace
import asyncio

args = Namespace(directory="/tmp/nur-combined")
asyncio.run(combine_command(args))
```
```

--------------------------------

### Package Index Output Format

Source: https://github.com/nix-community/nur/blob/main/_autodocs/modules.md

Shows the expected JSON structure for indexed packages, including metadata like description and source position.

```python
{
    "nur.repos.{repo}.{package}": {
        "_attr": "package-name",
        "_repo": "repo-name",
        "meta": {
            "description": "...",
            "position": "https://github.com/.../file.nix#L123",
            # ... other metadata
        }
    }
}
```

--------------------------------

### Update All Repositories Command

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

CLI subcommand handler that updates all repositories concurrently. Loads the manifest, spawns concurrent tasks to update all repositories, and updates the lock file with successful locks. Handles specific errors for new and existing repositories.

```python
from argparse import Namespace
from nur.update import update_command
import asyncio

args = Namespace()
asyncio.run(update_command(args))
```

--------------------------------

### GitPrefetcher.prefetch

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

Fetches and hashes a git repository at the specified reference using nix-prefetch-git. It handles submodules if present and returns the SHA256 hash and the path to the fetched repository.

```APIDOC
## GitPrefetcher.prefetch

### Description
Fetches and hashes a git repository at the specified reference. This method invokes `nix-prefetch-git` and can optionally handle submodules.

### Method
`prefetch`

### Parameters
#### Path Parameters
- **ref** (str) - Required - Git reference (commit hash or branch)

### Return Type
`Tuple[str, Path]` — (sha256_hash, repo_path)

### Raises
- `NurError` — if prefetch fails or times out (30s timeout)

### Source
`ci/nur/prefetch.py:47-121`
```

--------------------------------

### Fetch GitLab Repository Archive

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

Fetches a GitLab repository as a tar.gz archive. Handles GitLab's project path escaping.

```nix
let
  gitlab = parseGitlabUrl attr.url;
  escapedPath = builtins.concatStringsSep "%2F" gitlab.path;
in
fetchzip {
  url = "https://${gitlab.domain}/api/v4/projects/${escapedPath}/repository/archive.tar.gz?sha=${revision.rev}";
  inherit (revision) sha256;
}
```

--------------------------------

### Index NUR Packages

Source: https://github.com/nix-community/nur/blob/main/_autodocs/configuration.md

Indexes all packages from all NUR repositories and outputs the result as JSON to stdout, with one JSON object per line. The directory argument specifies the NUR repository to index; defaults to the main NUR repository.

```bash
./bin/nur index /tmp/nur | jq '.["nur.repos.mic92.hello"] | .meta.description'
# "Hello world package"
```

--------------------------------

### NUR Overlay for Flake Configurations

Source: https://github.com/nix-community/nur/blob/main/_autodocs/nix-lib.md

Provides the default overlay for NUR, enabling its packages and modules to be used within flake-based Nix configurations.

```nix
overlay = final: prev: {
  nur = import ./default.nix {
    nurpkgs = prev;
    pkgs = prev;
  };
};
```

--------------------------------

### nur.index.index_repo

Source: https://github.com/nix-community/nur/blob/main/_autodocs/api-reference.md

Indexes all packages within a specified repository using nix-env query and enriches package metadata.

```APIDOC
## nur.index.index_repo

### Description
Indexes all packages in a repository using nix-env query.

### Method
```python
def index_repo(
    directory: Path,
    repo: str,
    expression_file: str,
    url: str
) -> Dict[str, Any]
```

### Parameters
#### Path Parameters
- **directory** (Path) - Required - Path to NUR root directory
- **repo** (str) - Required - Repository name
- **expression_file** (str) - Required - Nix file to evaluate (usually "default.nix")
- **url** (str) - Required - Repository URL (for source links)

### Details
Uses `nix-env -qa * --meta --json` to query all packages in a repository. For each package, adds metadata fields:
- `_attr` — package attribute name
- `_repo` — repository name
- `meta.position` — resolved source code location (GitHub/GitLab/nixpkgs link with line number)

Returns empty dict if evaluation fails.

### Return Type
`Dict[str, Any]` — Dictionary mapping fully-qualified package names to package metadata

### Example

```python
from pathlib import Path
from nur.index import index_repo

pkgs = index_repo(
    directory=Path("/tmp/nur"),
    repo="mic92",
    expression_file="default.nix",
    url="https://github.com/Mic92/nur-packages"
)
for pkg_name, metadata in pkgs.items():
    print(f"{pkg_name}: {metadata['_repo']}")
```
```

--------------------------------

### CLI Combine Command

Source: https://github.com/nix-community/nur/blob/main/_autodocs/README.md

Assemble all repositories into a single, combined repository structure. This command preserves the full git history of all included repositories.

```bash
./bin/nur combine /path/to/combined
```