diff --git a/docs/manual/introduction.md b/docs/manual/introduction.md new file mode 100644 index 00000000..ebdac5bd --- /dev/null +++ b/docs/manual/introduction.md @@ -0,0 +1,32 @@ +# Introduction to Home Manager {#ch-introduction} + +Home Manager is a [Nix](https://nix.dev/)-powered tool for reproducible management of the contents of users' home directories. +This includes programs, configuration files, environment variables and, well… arbitrary files. +The following example snippet of Nix code: + +```nix +programs.git = { + enable = true; + userEmail = "joe@example.org"; + userName = "joe"; +}; +``` + +would make available to a user the `git` executable and man pages and a configuration file `~/.config/git/config`: + +```ini +[user] + email = "joe@example.org" + name = "joe" +``` + +Since Home Manager is implemented in Nix, it provides several benefits: + +- Contents are reproducible — a home will be the exact same every time it is built, unless of course, an intentional change is made. + This also means you can have the exact same home on different hosts. +- Significantly faster and more powerful than various backup strategies. +- Unlike "dotfiles" repositories, Home Manager supports specifying programs, as well as their configurations. +- Supported by , so that you don't have to build from source. +- If you do want to build some programs from source, there is hardly a tool more useful than Nix for that, and the build instructions can be neatly integrated in your Home Manager usage. +- Infinitely composable, so that values in different configuration files and build instructions can share a source of truth. +- Connects you with the [most extensive](https://repology.org/repositories/statistics/total) and [most up-to-date](https://repology.org/repositories/statistics/newest) software package repository on earth, [Nixpkgs](https://github.com/NixOS/nixpkgs). diff --git a/docs/manual/manual.md b/docs/manual/manual.md index a1cfb1a0..0f81642f 100644 --- a/docs/manual/manual.md +++ b/docs/manual/manual.md @@ -8,6 +8,7 @@ preface.md ``` ```{=include=} parts +introduction.md installation.md usage.md nix-flakes.md