mirror of
https://github.com/nix-community/home-manager
synced 2024-06-02 21:13:33 +02:00
c7592b747b
Currently, dot directories and XDG base directories are used inconsistently in the Home Manager option declarations. This creates ambiguity for the user as to where the location of the file should be albeit this is rarely encountered in practice as it is sufficient to read upstream documentation. The rationale is to make declarations consistent and make a clear distinction between hardcoded and modular specifications. References to ~/.config in relevant nixpkgs modules were untouched as the location is hardcoded upstream[1]. Furthermore, modules of programs which do not follow XDG specifications were also untouched. Generalization of tilde(~) expansions to $HOME were also considered, however there isn't sufficient rationale despite the use of $HOME being more universal. The expansion is standardized in POSIX[2] and is essentially portable across all shells, thus there is no pragmatic value to introducing the change. [1] https://github.com/nixos/nixpkgs/blob/master/pkgs/top-level/impure.nix [2] https://pubs.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_06_01
621 lines
14 KiB
XML
621 lines
14 KiB
XML
<refentry xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<refmeta>
|
|
<refentrytitle><command>home-manager</command>
|
|
</refentrytitle><manvolnum>1</manvolnum>
|
|
<refmiscinfo class="source">Home Manager</refmiscinfo>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname><command>home-manager</command>
|
|
</refname><refpurpose>reconfigure a user environment</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>home-manager</command> <group choice="req">
|
|
<arg choice="plain">
|
|
build
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
instantiate
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
edit
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
expire-generations <replaceable>timestamp</replaceable>
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
generations
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
help
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
news
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
option <replaceable>option.name</replaceable>
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
packages
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
remove-generations <replaceable>ID …</replaceable>
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
switch
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
uninstall
|
|
</arg>
|
|
</group>
|
|
<sbr />
|
|
<arg>
|
|
-A <replaceable>attrPath</replaceable>
|
|
</arg>
|
|
|
|
<arg>
|
|
-I <replaceable>path</replaceable>
|
|
</arg>
|
|
|
|
<arg>
|
|
--flake <replaceable>flake-uri</replaceable>
|
|
</arg>
|
|
|
|
<arg>
|
|
-b <replaceable>ext</replaceable>
|
|
</arg>
|
|
|
|
<arg>
|
|
<group choice="req">
|
|
<arg choice="plain">
|
|
-f
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
--file
|
|
</arg>
|
|
</group> <replaceable>path</replaceable>
|
|
</arg>
|
|
|
|
<arg>
|
|
<group choice="req">
|
|
<arg choice="plain">
|
|
-h
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
--help
|
|
</arg>
|
|
</group>
|
|
</arg>
|
|
|
|
<arg>
|
|
<group choice="req">
|
|
<arg choice="plain">
|
|
-n
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
--dry-run
|
|
</arg>
|
|
</group>
|
|
</arg>
|
|
|
|
<arg>
|
|
--option <replaceable>name</replaceable> <replaceable>value</replaceable>
|
|
</arg>
|
|
|
|
<arg>
|
|
--cores <replaceable>number</replaceable>
|
|
</arg>
|
|
|
|
<arg>
|
|
<group choice="req">
|
|
<arg choice="plain">
|
|
-j
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
--max-jobs
|
|
</arg>
|
|
</group>
|
|
<replaceable>number</replaceable>
|
|
</arg>
|
|
|
|
<arg>
|
|
--debug
|
|
</arg>
|
|
|
|
<arg>
|
|
--impure
|
|
</arg>
|
|
|
|
<arg>
|
|
--keep-failed
|
|
</arg>
|
|
|
|
<arg>
|
|
--keep-going
|
|
</arg>
|
|
|
|
<arg>
|
|
--show-trace
|
|
</arg>
|
|
|
|
<arg>
|
|
--(no-)substitute
|
|
</arg>
|
|
|
|
<arg>
|
|
--no-out-link
|
|
</arg>
|
|
|
|
<arg>
|
|
<group choice="req">
|
|
<arg choice="plain">
|
|
-v
|
|
</arg>
|
|
|
|
<arg choice="plain">
|
|
--verbose
|
|
</arg>
|
|
</group>
|
|
</arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsection>
|
|
<title>Description</title>
|
|
<para>
|
|
This command updates the user environment so that it corresponds to the
|
|
configuration specified in <filename>~/.config/nixpkgs/home.nix</filename> or <filename>~/.config/nixpkgs/flake.nix</filename>.
|
|
</para>
|
|
<para>
|
|
All operations using this tool expects a sub-command that indicates the
|
|
operation to perform. It must be one of
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<option>build</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Build configuration into a <filename>result</filename> directory.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>instantiate</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Instantiate the configuration and print the resulting derivation.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>edit</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Open the home configuration using the editor indicated by
|
|
<envar>EDITOR</envar>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>expire-generations <replaceable>timestamp</replaceable></option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Remove generations older than <replaceable>timestamp</replaceable> where
|
|
<replaceable>timestamp</replaceable> is interpreted as in the
|
|
<option>-d</option> argument of the <citerefentry>
|
|
<refentrytitle>date</refentrytitle>
|
|
<manvolnum>1</manvolnum> </citerefentry> tool. For example <literal>-30
|
|
days</literal> or <literal>2018-01-01</literal>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>generations</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
List all home environment generations.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>help</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Print tool help.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>news</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Show news entries in a pager.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>option <replaceable>option.name</replaceable></option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Inspect the given option name in the home configuration, like <citerefentry>
|
|
<refentrytitle>nixos-option</refentrytitle>
|
|
<manvolnum>8</manvolnum> </citerefentry>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>packages</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
List all packages installed in <varname>home-manager-path</varname>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>remove-generations <replaceable>ID …</replaceable></option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Remove indicated generations. Use the <option>generations</option>
|
|
sub-command to find suitable generation numbers.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>switch</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Build and activate the configuration.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>uninstall</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Remove Home Manager from the user environment. This will
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
remove all managed files from the home directory,
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
remove packages installed through Home Manager from the user profile,
|
|
and
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
optionally remove all Home Manager generations and make them
|
|
available for immediate garbage collection.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Options</title>
|
|
<para>
|
|
The tool accepts the options
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<option>-A <replaceable>attrPath</replaceable></option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Optional attribute that selects a configuration expression in the
|
|
configuration file. That is, if <filename>home.nix</filename> contains
|
|
<programlisting language="nix">
|
|
{
|
|
joe-at-work = {pkgs, ...}: { home.packages = [ pkgs.fortune ]; };
|
|
joe-at-home = {pkgs, ...}: { home.packages = [ pkgs.cowsay ]; };
|
|
}
|
|
</programlisting>
|
|
then the command <command>home-manager switch -A joe-at-work</command>
|
|
will activate the profile containing the fortune program.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>-I <replaceable>path</replaceable></option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Add a path to the Nix expression search path. For example, to build a
|
|
Home Manager profile using a specific Nixpkgs run <command>home-manager
|
|
-I nixpkgs=/absolute/path/to/nixpkgs build</command>. By default
|
|
<literal><nixpkgs></literal> is used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--flake <replaceable>flake-uri[#name]</replaceable></option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Build Home Manager configuration from the flake, which must contain the
|
|
output homeConfigurations.name. If no name is specified it will first try
|
|
username@hostname and then username.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>-b <replaceable>extension</replaceable></option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Enable automatic resolution of collisions between unmanaged and managed
|
|
files. The name of the original file will be suffixed by the given
|
|
extension. For example,
|
|
<screen>
|
|
<prompt>$</prompt> <userinput>home-manager -b bck switch</userinput>
|
|
</screen>
|
|
will cause a colliding file <filename>~/.config/foo.conf</filename> to be
|
|
moved to <filename>~/.config/foo.conf.bck</filename>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>-f <replaceable>path</replaceable></option>
|
|
</term>
|
|
<term>
|
|
<option>--file <replaceable>path</replaceable></option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Indicates the path to the Home Manager configuration file. If not given,
|
|
<filename>$XDG_CONFIG_HOME/nixpkgs/home.nix</filename> is used.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>-h</option>
|
|
</term>
|
|
<term>
|
|
<option>--help</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Prints usage information for the <command>home-manager</command> tool.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>-n</option>
|
|
</term>
|
|
<term>
|
|
<option>--dry-run</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Perform a dry-run of the given operation, only prints what actions would
|
|
be taken.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--option <replaceable>name</replaceable> <replaceable>value</replaceable></option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passed on to <citerefentry>
|
|
<refentrytitle>nix-build</refentrytitle>
|
|
<manvolnum>1</manvolnum> </citerefentry>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--cores <replaceable>number</replaceable></option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passed on to <citerefentry>
|
|
<refentrytitle>nix-build</refentrytitle>
|
|
<manvolnum>1</manvolnum> </citerefentry>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>-j <replaceable>number</replaceable></option>
|
|
</term>
|
|
<term>
|
|
<option>--max-jobs <replaceable>number</replaceable></option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passed on to <citerefentry>
|
|
<refentrytitle>nix-build</refentrytitle>
|
|
<manvolnum>1</manvolnum> </citerefentry>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--debug</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passed on to <citerefentry>
|
|
<refentrytitle>nix-build</refentrytitle>
|
|
<manvolnum>1</manvolnum> </citerefentry>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--impure</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passed on to <citerefentry>
|
|
<refentrytitle>nix-build</refentrytitle>
|
|
<manvolnum>1</manvolnum> </citerefentry>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--keep-failed</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passed on to <citerefentry>
|
|
<refentrytitle>nix-build</refentrytitle>
|
|
<manvolnum>1</manvolnum> </citerefentry>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--keep-going</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passed on to <citerefentry>
|
|
<refentrytitle>nix-build</refentrytitle>
|
|
<manvolnum>1</manvolnum> </citerefentry>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--show-trace</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passed on to <citerefentry>
|
|
<refentrytitle>nix-build</refentrytitle>
|
|
<manvolnum>1</manvolnum> </citerefentry>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--(no-)substitute</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passed on to <citerefentry>
|
|
<refentrytitle>nix-build</refentrytitle>
|
|
<manvolnum>1</manvolnum> </citerefentry>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>--no-out-link</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Passed on to <citerefentry>
|
|
<refentrytitle>nix-build</refentrytitle>
|
|
<manvolnum>1</manvolnum> </citerefentry>
|
|
when running <command>home-manager build</command>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<option>-v</option>
|
|
</term>
|
|
<term>
|
|
<option>--verbose</option>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Activates verbose output.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Files</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<filename>$XDG_DATA_HOME/home-manager/news-read-ids</filename>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Identifiers of news items that have been shown. Can be deleted to reset
|
|
the read news indicator.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsection>
|
|
<refsection>
|
|
<title>Bugs</title>
|
|
<para>
|
|
Please report any bugs on the
|
|
<link
|
|
xlink:href="https://github.com/nix-community/home-manager/issues">project
|
|
issue tracker</link>.
|
|
</para>
|
|
</refsection>
|
|
<refsection>
|
|
<title>See also</title>
|
|
<para>
|
|
<citerefentry>
|
|
<refentrytitle>home-configuration.nix</refentrytitle>
|
|
<manvolnum>5</manvolnum> </citerefentry>
|
|
</para>
|
|
</refsection>
|
|
</refentry>
|