# niv ![GitHub Actions](https://github.com/nmattia/niv/workflows/Test/badge.svg?branch=master) [![Netlify Status](https://api.netlify.com/api/v1/badges/48532eaa-259f-4ca2-aadf-67f7c6b957fd/deploy-status)](https://niv.nmattia.com) Painless dependencies for [Nix] projects. Read more in the [Getting started](#getting-started) section below.
## Install `niv` is available in [`nixpkgs`](https://github.com/NixOS/nixpkgs) on the `master` branch as `niv`. It is also available on the `release-19.09` branch as `haskellPackages.niv`. Otherwise, run: ``` bash $ nix-env -iA niv -f https://github.com/nmattia/niv/tarball/master ``` ## Build Inside the provided nix shell: ``` bash $ repl ``` Run the test suite with this command: ``` bash $ ./script/test ``` ## Usage `niv` simplifies [adding](#add) and [updating](#update) dependencies in Nix projects. It uses a single file, `nix/sources.json`, where it stores the data necessary for fetching and updating the packages. * [Add](#add): inserts a package in `nix/sources.json`. * [Update](#update): updates one or all packages in `nix/sources.json`. * [Drop](#drop): deletes a package from `nix/sources.json`. `niv` has two more utility functions: * [Init](#init): bootstraps a Nix project, in particular creates a `nix/sources.json` file containing `niv` and `nixpkgs` as well as a `nix/sources.nix` file that returns the sources as a Nix object. * [Show](#show): shows the packages' information. ### Configuration The following environment variables are read by `niv`: | Name | Note | | --------------- | ---- | | GITHUB_TOKEN | When set, the value is used to authenticate GitHub API requests. | | GITHUB_HOST | The GitHub host to use when fetching packages. Port may be appended here. | | GITHUB_API_HOST | The host used when performing GitHub API requests. Use `GITHUB_API_PORT` for specifying the port. | | GITHUB_API_PORT | The port used when performing GitHub API requests. Defaults to `443` for secure requests. Defaults to `80` for insecure requests. See also: `GITHUB_INSECURE`. | | GITHUB_INSECURE | When set to anything but the empty string, requests are performed over `http` instead of `https`. | | GITHUB_PATH | The base path used when performing GitHub API requests. | The next two sections cover [common use cases](#getting-started) and [full command description](#commands). ### Getting started This section covers common use cases: * [Bootstrapping a Nix project](#bootstrapping-a-nix-project). * [Tracking a different nixpkgs branch](#tracking-a-nixpkgs-branch). * [Importing packages from GitHub](#importing-packages-from-github). * [Fetching packages from custom URLs](#using-custom-urls). #### Bootstrapping a Nix project Use the `init` command when starting a new Nix project or when porting an existing Nix project to niv: ``` shell $ niv init ... $ tree . └── nix ├── sources.json └── sources.nix 1 directory, 2 files ``` The file `nix/sources.json` is the file used by niv to store versions and is initialized with niv and nixpkgs: ``` json { "nixpkgs": { "url": "https://github.com/NixOS/nixpkgs-channels/archive/109a28ab954a0ad129f7621d468f829981b8b96c.tar.gz", "owner": "NixOS", "branch": "nixos-19.09", "url_template": "https://github.com/