Document the nixpkgs-channels repo

This replaces update-channel-branches.sh with standard Git
invocations.

1 files changed, 28 insertions, 16 deletions

diff --git a/nixos/doc/manual/development/sources.xml b/nixos/doc/manual/development/sources.xml
index 3ac07da19f1..879a31e32c5 100644
--- a/nixos/doc/manual/development/sources.xml
+++ b/nixos/doc/manual/development/sources.xml
@@ -24,6 +24,9 @@ $ mkdir -p <replaceable>/my/sources</replaceable>
 $ cd <replaceable>/my/sources</replaceable>
 $ nix-env -i git
 $ git clone git://github.com/NixOS/nixpkgs.git
+$ cd nixpkgs
+$ git remote add channels git://github.com/NixOS/nixpkgs-channels.git
+$ git remote update channels
 </screen>
 
 This will check out the latest NixOS sources to
@@ -31,7 +34,12 @@ This will check out the latest NixOS sources to
 and the Nixpkgs sources to
 <filename><replaceable>/my/sources</replaceable>/nixpkgs</filename>.
 (The NixOS source tree lives in a subdirectory of the Nixpkgs
-repository.)</para>
+repository.) The remote <literal>channels</literal> refers to a
+read-only repository that tracks the Nixpkgs/NixOS channels (see <xref
+linkend="sec-upgrading"/> for more information about channels). Thus,
+the Git branch <literal>channels/nixos-14.12</literal> will contain
+the latest built and tested version available in the
+<literal>nixos-14.12</literal> channel.</para>
 
 <para>It’s often inconvenient to develop directly on the master
 branch, since if somebody has just committed (say) a change to GCC,
@@ -40,28 +48,32 @@ rebuild everything from source. So you may want to create a local
 branch based on your current NixOS version:
 
 <screen>
-$ <replaceable>/my/sources</replaceable>/nixpkgs/maintainers/scripts/update-channel-branches.sh
-Fetching channels from https://nixos.org/channels:
- * [new branch]      cbe467e           -> channels/remotes/nixos-unstable
-Fetching channels from nixos-version:
- * [new branch]      9ff4738           -> channels/current-system
-Fetching channels from ~/.nix-defexpr:
- * [new branch]      0d4acad           -> channels/root/nixos
-$ git checkout -b local channels/current-system
+$ nixos-version
+14.04.273.ea1952b (Baboon)
+
+$ git checkout -b local ea1952b
 </screen>
 
-Or, to base your local branch on the latest version available in the
+Or, to base your local branch on the latest version available in a
 NixOS channel:
 
 <screen>
-$ <replaceable>/my/sources</replaceable>/nixpkgs/maintainers/scripts/update-channel-branches.sh
-$ git checkout -b local channels/remotes/nixos-unstable
+$ git remote update channels
+$ git checkout -b local channels/nixos-14.12
+</screen>
+
+(Replace <literal>nixos-14.12</literal> with the name of the channel
+you want to use.) You can use <command>git merge</command> or
+<command>git rebase</command> to keep your local branch in sync with
+the channel, e.g.
+
+<screen>
+$ git remote update channels
+$ git merge channels/nixos-14.12
 </screen>
 
-You can then use <command>git rebase</command> to sync your local
-branch with the upstream branch, and use <command>git
-cherry-pick</command> to copy commits from your local branch to the
-upstream branch.</para>
+You can use <command>git cherry-pick</command> to copy commits from
+your local branch to the upstream branch.</para>
 
 <para>If you want to rebuild your system using your (modified)
 sources, you need to tell <command>nixos-rebuild</command> about them