605 lines
14 KiB
XML
605 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>
|
|
--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>~/.config/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>--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>~/.local/share/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>
|