Add basic README file

1 files changed, 127 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 00000000000..179fcf1581b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,127 @@
+Home Manager using Nix
+======================
+
+This project provides a basic system for managing a user environment
+using the [Nix][] package manager together with the Nix libraries
+found in [Nixpkgs][]. Before attempting to use Home Manager please
+read the warning below.
+
+Words of warning
+----------------
+
+This project is in early development! I personally use it to manage
+several user configurations but it may fail catastrophically for you.
+So beware!
+
+To configure programs and services the Home Manager must write various
+things to your home directory and possibly overwrite files you have
+previously created. For example, if you use Home Manager to install
+and configure Git then your `~/.gitconfig` will be replaced by a link
+to a configuration generated by Home Manager:
+
+```
+$ ls -gG ~/.gitconfig
+lrwxrwxrwx 1 73 Jan  8 21:59 /home/rycee/.gitconfig -> /nix/store/pk7g12816avnxyhnkbdhqhnlzrw7fsga-home-manager-files/.gitconfig
+```
+
+So, if you already have a wonderful, painstakingly created
+`~/.gitconfig` it will be gone. Home Manager will _not_ attempt to
+backup the previous `~/.gitconfig` file.
+
+Further, Home Manager has only ever been used on [NixOS][] version
+16.09 (the stable version), it may or may not work on other Linux
+distributions and NixOS versions.
+
+Finally, the `home-manager` tool does not support rollbacks at the
+moment so if your home directory gets messed up you'll have to fix it
+yourself.
+
+Now when your expectations have been built up and you are eager to try
+all this out you can go ahead and read the rest of this text.
+
+Installation
+------------
+
+Currently the easiest way to install Home Manager is as follows:
+
+ 1. Make sure you have a working Nix installation.
+
+ 2. Clone the Home Manager repository into the `~/.nixpkgs` directory:
+
+    ```
+    $ git clone https://github.com/rycee/home-manager ~/.nixpkgs/home-manager
+    ```
+
+ 3. Add Home Manager to your user's Nixpkgs, for example by adding it
+    to the `packageOverrides` section in your `~/.nixpkgs/config.nix`
+    file:
+
+    ```nix
+    {
+      packageOverrides = pkgs: rec {
+        home-manager = import ./home-manager { inherit pkgs; };
+      };
+    }
+    ```
+
+ 4. Install the `home-manager` package:
+
+    ```
+    $ nix-env -f '<nixpkgs>' -iA home-manager
+    installing ‘home-manager’
+    ```
+
+Usage
+-----
+
+The `home-manager` package installs a tool that is conveniently called
+`home-manager`. This tool can apply configurations to your home
+directory, list user packages installed by the tool, and list the
+configuration generations.
+
+As an example, let us set up a very simple configuration that installs
+the htop and fortune packages, installs Emacs with a few extra
+packages enabled, installs Firefox with Adobe Flash enabled, and
+enables the user gpg-agent service.
+
+First create a file `~/.nixpkgs/home.nix` containing
+
+```nix
+{ pkgs }:
+
+{
+  home.packages = [
+    pkgs.htop
+    pkgs.fortune
+  ];
+
+  programs.emacs = {
+    enable = true;
+    extraPackages = epkgs: [
+      epkgs.nix-mode
+      epkgs.magit
+    ];
+  };
+
+  programs.firefox = {
+    enable = true;
+    enableAdobeFlash = true;
+  };
+
+  services.gpg-agent = {
+    enable = true;
+    defaultCacheTtl = 1800;
+    enableSshSupport = true;
+  };
+}
+```
+
+To activate this configuration you can then run
+
+```
+$ home-manager switch ~/.nixpkgs/home.nix
+```
+
+[Nix]: https://nixos.org/nix/
+[NixOS]: https://nixos.org/
+[Nixpkgs]: https://nixos.org/nixpkgs/