Mirrors/home-manager
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

readme: major cleanup

Browse source 
Includes the following changes:

- Remove unused reference definition.

- Sort reference definitions.

- Internally reference "Words of warning" section.

- Consistently reference.

- Fix typo.

- Format HTML code.

- Link only to first occurence per section.

- Simplify list formatting.

- Adapt 'Installation' section to manual.

- Fix punctuation.

- Wrap text at 80 characters.

- Simplify link phrasing.

- Add missing punctuation.

PR #4363
This commit is contained in:
NAHO 2023-08-19 18:35:23 +02:00 committed by Robert Helgesson
parent 4c0bcf5dff
commit 81ab146262
No known key found for this signature in database
GPG key ID: 36BDAA14C2797E89
1 changed files with 73 additions and 77 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

148
README.md
View file

@ -1,109 +1,106 @@
Home Manager using Nix Home Manager using Nix
====================== ======================
This project provides a basic system for managing a user environment This project provides a basic system for managing a user environment using the
using the [Nix][] package manager together with the Nix libraries [Nix][] package manager together with the Nix libraries found in [Nixpkgs][]. It
found in [Nixpkgs][]. It allows declarative configuration of user allows declarative configuration of user specific (non-global) packages and
specific (non global) packages and dotfiles. dotfiles.
Usage Usage
----- -----
Before attempting to use Home Manager please read the warning below. Before attempting to use Home Manager please read [the warning
below](#words-of-warning).
For a systematic overview of Home Manager and its available options, For a systematic overview of Home Manager and its available options, please see:
please see
- the [Home Manager manual][manual], - [Home Manager manual][manual]
- the [Home Manager configuration options][configuration options], and - [Home Manager configuration options][configuration options]
- the 3rd party [Home Manager option search](https://mipmip.github.io/home-manager-option-search/). - [3rd party Home Manager option
search](https://mipmip.github.io/home-manager-option-search/)
If you would like to contribute to Home Manager If you would like to contribute to Home Manager, then please have a look at
then please have a look at the [contributing][] chapter of the manual. ["Contributing" in the manual][contributing].
Releases Releases
-------- --------
Home Manager is developed against `nixpkgs-unstable` branch, which Home Manager is developed against `nixpkgs-unstable` branch, which often causes
often causes it to contain tweaks for changes/packages not yet it to contain tweaks for changes/packages not yet released in stable [NixOS][].
released in stable NixOS. To avoid breaking users' configurations, To avoid breaking users' configurations, Home Manager is released in branches
Home Manager is released in branches corresponding to NixOS releases corresponding to NixOS releases (e.g. `release-23.05`). These branches get
(e.g. `release-23.05`). These branches get fixes, but usually not new fixes, but usually not new modules. If you need a module to be backported, then
modules. If you need a module to be backported, then feel free to open feel free to open an issue.
an issue.
Words of warning Words of warning
---------------- ----------------
Unfortunately, it is quite possible to get difficult to understand Unfortunately, it is quite possible to get difficult to understand errors when
errors when working with Home Manager. You should therefore be working with Home Manager. You should therefore be comfortable using the [Nix][]
comfortable using the Nix language and the various tools in the Nix language and the various tools in the Nix ecosystem.
ecosystem.
If you are not very familiar with Nix but still want to use Home If you are not very familiar with Nix but still want to use Home Manager then
Manager then you are strongly encouraged to start with a small and you are strongly encouraged to start with a small and very simple configuration
very simple configuration and gradually make it more elaborate as you and gradually make it more elaborate as you learn.
learn.
In some cases Home Manager cannot detect whether it will overwrite a In some cases Home Manager cannot detect whether it will overwrite a previous
previous manual configuration. For example, the Gnome Terminal module manual configuration. For example, the Gnome Terminal module will write to your
will write to your dconf store and cannot tell whether a configuration dconf store and cannot tell whether a configuration that it is about to be
that it is about to be overwritten was from a previous Home Manager overwritten was from a previous Home Manager generation or from manual
generation or from manual configuration. configuration.
Home Manager targets [NixOS][] unstable and NixOS version 23.05 (the Home Manager targets [NixOS][] unstable and NixOS version 23.05 (the current
current stable version), it may or may not work on other Linux stable version), it may or may not work on other Linux distributions and NixOS
distributions and NixOS versions. versions.
Also, the `home-manager` tool does not explicitly support rollbacks at Also, the `home-manager` tool does not explicitly support rollbacks at the
the moment so if your home directory gets messed up you'll have to fix moment so if your home directory gets messed up you'll have to fix it yourself.
it yourself. See the [rollbacks][] section for instructions on how to See the [rollbacks][] section for instructions on how to manually perform a
manually perform a rollback. rollback.
Now when your expectations have been built up and you are eager to try Now when your expectations have been built up and you are eager to try all this
all this out you can go ahead and read the rest of this text. out you can go ahead and read the rest of this text.
Contact Contact
------- -------
You can chat with us on IRC in the channel [#home-manager][] on [OFTC][]. You can chat with us on IRC in the channel [#home-manager][] on [OFTC][]. There
There is also a [Matrix room](https://matrix.to/#/#hm:rycee.net), is also a [Matrix room](https://matrix.to/#/#hm:rycee.net), which is bridged to
which is bridged to the IRC channel. the IRC channel.
Installation Installation
------------ ------------
Home Manager can be used in three primary ways: Home Manager can be used in three primary ways:
1. Using the standalone `home-manager` tool. For platforms other than 1. Using the standalone `home-manager` tool. For platforms other than NixOS and
NixOS and Darwin, this is the only available choice. It is also Darwin, this is the only available choice. It is also recommended for people
recommended for people on NixOS or Darwin that want to manage their on [NixOS][] or Darwin that want to manage their home directory independently
home directory independently of the system as a whole. See of the system as a whole. See ["Standalone installation" in the
[Standalone installation][manual standalone install] in the manual manual][manual standalone install] for instructions on how to perform this
for instructions on how to perform this installation. installation.
2. As a module within a NixOS system configuration. This allows the 1. As a module within a NixOS system configuration. This allows the user
user profiles to be built together with the system when running profiles to be built together with the system when running `nixos-rebuild`.
`nixos-rebuild`. See [NixOS module installation][manual nixos See ["NixOS module" in the manual][manual nixos install] for a description of
install] in the manual for a description of this setup. this setup.
3. As a module within a [nix-darwin][] system configuration. This 1. As a module within a [nix-darwin] system configuration. This allows the user
allows the user profiles to be built together with the system when profiles to be built together with the system when running `darwin-rebuild`.
running `darwin-rebuild`. See [nix-darwin module See ["nix-darwin module" in the manual][manual nix-darwin install] for a
installation][manual nix-darwin install] in the manual for a
description of this setup. description of this setup.
Home Manager provides both the channel-based setup and the flake-based one. Home Manager provides both the channel-based setup and the flake-based one. See
See [Nix Flakes][manual nix flakes] for a description of the flake-based setup. [Nix Flakes][manual nix flakes] for a description of the flake-based setup.
Translations Translations
------------ ------------
Home Manager has basic support for internationalization through Home Manager has basic support for internationalization through
[gettext](https://www.gnu.org/software/gettext/). The translations are [gettext](https://www.gnu.org/software/gettext/). The translations are hosted by
hosted by [Weblate](https://weblate.org/). If you would like to [Weblate](https://weblate.org/). If you would like to contribute to the
contribute to the translation effort then start by going to the translation effort then start by going to the [Home Manager Weblate
[Home Manager Weblate project](https://hosted.weblate.org/engage/home-manager/). project](https://hosted.weblate.org/engage/home-manager/).
<a href="https://hosted.weblate.org/engage/home-manager/"> <a href="https://hosted.weblate.org/engage/home-manager/">
<img src="https://hosted.weblate.org/widgets/home-manager/-/multi-auto.svg" alt="Translation status" /> <img src="https://hosted.weblate.org/widgets/home-manager/-/multi-auto.svg" alt="Translation status" />
@ -114,19 +111,18 @@ License
This project is licensed under the terms of the [MIT license](LICENSE). This project is licensed under the terms of the [MIT license](LICENSE).
[Nix]: https://nixos.org/explore.html
[NixOS]: https://nixos.org/
[Nixpkgs]: https://github.com/NixOS/nixpkgs
[manual]: https://nix-community.github.io/home-manager/index.html
[contributing]: https://nix-community.github.io/home-manager/#ch-contributing
[manual usage]: https://nix-community.github.io/home-manager/#ch-usage
[configuration options]: https://nix-community.github.io/home-manager/options.html
[#home-manager]: https://webchat.oftc.net/?channels=home-manager [#home-manager]: https://webchat.oftc.net/?channels=home-manager
[OFTC]: https://oftc.net/
[Nix Flakes]: https://nixos.wiki/wiki/Flakes [Nix Flakes]: https://nixos.wiki/wiki/Flakes
[nix-darwin]: https://github.com/LnL7/nix-darwin [NixOS]: https://nixos.org/
[manual standalone install]: https://nix-community.github.io/home-manager/index.html#sec-install-standalone [Nix]: https://nixos.org/explore.html
[manual nixos install]: https://nix-community.github.io/home-manager/index.html#sec-install-nixos-module [Nixpkgs]: https://github.com/NixOS/nixpkgs
[manual nix-darwin install]: https://nix-community.github.io/home-manager/index.html#sec-install-nix-darwin-module [OFTC]: https://oftc.net/
[configuration options]: https://nix-community.github.io/home-manager/options.html
[contributing]: https://nix-community.github.io/home-manager/#ch-contributing
[manual nix flakes]: https://nix-community.github.io/home-manager/index.html#ch-nix-flakes [manual nix flakes]: https://nix-community.github.io/home-manager/index.html#ch-nix-flakes
[manual nix-darwin install]: https://nix-community.github.io/home-manager/index.html#sec-install-nix-darwin-module
[manual nixos install]: https://nix-community.github.io/home-manager/index.html#sec-install-nixos-module
[manual standalone install]: https://nix-community.github.io/home-manager/index.html#sec-install-standalone
[manual]: https://nix-community.github.io/home-manager/index.html
[nix-darwin]: https://github.com/LnL7/nix-darwin
[rollbacks]: https://nix-community.github.io/home-manager/index.html#sec-usage-rollbacks [rollbacks]: https://nix-community.github.io/home-manager/index.html#sec-usage-rollbacks