faq: how to pin nixpkgs

source/faq.rst

@@ -44,8 +44,45 @@ How nix decides which parts of the environment affect a derivation and its sha25
 How to pin nixpkgs to a specific commit/branch?
 -----------------------------------------------
 
--I nixpkgs=http://nixos.org/channels/nixos-16.09/nixexprs.tar.xz
+
-NIX_PATH=nixpkgs=http://nixos.org/channels/nixos-16.09/nixexprs.tar.xz
+Ways to provide/pin nixpkgs:
+
+- ``nix-channel --add URL nixpkgs && nix-channel --update`` sets it globally for the user,
+  but it doesn't allow precision (pinning to specific version)
+
+- As environment variable: ``$NIX_PATH=URL`` 
+
+- ``-I`` command line parameter to most of commands like ``nix-build``, ``nix-shell``, etc
+
+- Using `builtins.fetchTarball <https://nixos.org/nix/manual/#ssec-builtins>`_ function that fetches the channel at evaluation time
+
+
+Possible ``URL`` values:
+
+- Local file path. Using just ``.`` means that nixpkgs is located in current folder.
+
+- Pinned to a specific commit: ``https://github.com/NixOS/nixpkgs/archive/addcb0dddf2b7db505dae5c38fceb691c7ed85f9.tar.gz``
+
+- Using latest channel, meaning all tests have passed: ``http://nixos.org/channels/nixos-17.03/nixexprs.tar.xz``
+
+- Using latest channel, but hosted by github: ``https://github.com/NixOS/nixpkgs-channels/archive/nixos-17.03.tar.gz``
+
+- Using latest commit for release branch, but not tested yet: ``https://github.com/NixOS/nixpkgs/archive/release-17.03.tar.gz``
+
+Examples:
+
+
+- ``nix-build -I ~/dev``
+- ``nix-build -I ~/dev``
+- ``nix-build -I nixpkgs=http://nixos.org/channels/nixos-17.03/nixexprs.tar.xz``
+- ``NIX_PATH=nixpkgs=http://nixos.org/channels/nixos-17.03/nixexprs.tar.xz nix-build ...``
+- Using just Nix:
+
+::
+
+    with import (fetchTarball https://github.com/NixOS/nixpkgs-channels/archive/nixos-14.12.tar.gz) {};
+
+    stdenv.mkDerivation { … }
 
 How to build reverse dependencies of a package?
 -----------------------------------------------
@@ -109,9 +146,6 @@ How to build my own ISO?
 
 http://nixos.org/nixos/manual/index.html#sec-building-cd
 
-How do I mix channels for packages?
------------------------------------
-
 Hydra
 *****