home-manager/docs/man-home-manager.xml
Robert Helgesson c8cb60b8a1
home-manager: add init command to main tool
The init command is essentially the old install script but integrated
into the home-manager tool. This simplifies things slightly since we
can use the existing code infrastructure.

The init command is Nix flake aware in the sense that, if we detect
that the user's Nix setup supports flakes, then we also create an
initial `flake.nix` file.

Finally, we update the installation instructions for the Nix flakes
standalone setup to use the new init command.

Zsh completion update provided by Anund <anundm@gmail.com>.
2023-03-15 22:47:04 +01:00

714 lines
16 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">
init <arg>--switch</arg> <arg><replaceable>dir</replaceable></arg>
</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>
--version
</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>
<group choice="req">
<arg choice="plain">
-L
</arg>
<arg choice="plain">
--print-build-logs
</arg>
</group>
</arg>
<arg>
--show-trace
</arg>
<arg>
--(no-)substitute
</arg>
<arg>
--no-out-link
</arg>
<arg>
--refresh
</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>$XDG_CONFIG_HOME/home-manager/home.nix</filename> or
<filename>$XDG_CONFIG_HOME/home-manager/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>init</option> [<option>--switch</option>] [<replaceable>dir</replaceable>]
</term>
<listitem>
<simpara>
Generates an initial <filename>home.nix</filename> file for the
current user. If Nix flakes are enabled, then this command also
generates a <filename>flake.nix</filename> file.
</simpara>
<simpara>
If a path <replaceable>dir</replaceable> is given then the
configuration will be generated in that directory. Otherwise, the
configuration will be generated in
<filename>~/.config/home-manager</filename>. The output directory will
be created if it does not exist.
</simpara>
<simpara>
If the <option>--switch</option> option is given, then the generated
configuration is activated.
</simpara>
<simpara>
Note, this command will not overwrite any existing files. It is
therefore safe to initialize a configuration, edit it, and then re-run
the <option>init</option> command with <option>--switch</option>
enabled to activate the configuration.
</simpara>
</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>
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>&lt;nixpkgs&gt;</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/home-manager/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>--version</option>
</term>
<listitem>
<para>
Prints the version number of 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>-L</option>
</term>
<term>
<option>--print-build-logs</option>
</term>
<listitem>
<para>
Passed on to <citerefentry>
<refentrytitle>nix build</refentrytitle>
</citerefentry>
when building from a flake.
</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>--refresh</option>
</term>
<listitem>
<para>
Passed on to <citerefentry>
<refentrytitle>nix-build</refentrytitle>
<manvolnum>1</manvolnum> </citerefentry>
</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>