mirror of
https://github.com/nix-community/home-manager
synced 2024-11-23 19:49:45 +01:00
322 lines
No EOL
16 KiB
HTML
322 lines
No EOL
16 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix D. Tools</title><link rel="stylesheet" type="text/css" href="style.css" /><script src="highlight.min.js" type="text/javascript"></script><script src="highlight.load.js" type="text/javascript"></script><meta name="generator" content="DocBook XSL Stylesheets V1.79.2" /><link rel="home" href="index.html" title="Home Manager Manual" /><link rel="up" href="index.html" title="Home Manager Manual" /><link rel="prev" href="nix-darwin-options.html" title="Appendix C. nix-darwin Module Options" /><link rel="next" href="release-notes.html" title="Appendix E. Release Notes" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix D. Tools</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="nix-darwin-options.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="release-notes.html">Next</a></td></tr></table><hr /></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="ch-tools"></a>Appendix D. Tools</h1></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="tools.html#id-1.13.2"><span class="command"><strong>home-manager</strong></span>
|
||
</a></span><span class="refpurpose"> — reconfigure a user environment</span></dt></dl></div><div class="refentry"><a id="id-1.13.2"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p><span class="command"><strong>home-manager</strong></span>
|
||
— reconfigure a user environment</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">home-manager</code> {
|
||
build
|
||
|
|
||
init [--switch] [<em class="replaceable"><code>dir</code></em>]
|
||
|
|
||
instantiate
|
||
|
|
||
edit
|
||
|
|
||
expire-generations <em class="replaceable"><code>timestamp</code></em>
|
||
|
|
||
generations
|
||
|
|
||
help
|
||
|
|
||
news
|
||
|
|
||
option <em class="replaceable"><code>option.name</code></em>
|
||
|
|
||
packages
|
||
|
|
||
remove-generations <em class="replaceable"><code>ID …</code></em>
|
||
|
|
||
switch
|
||
|
|
||
uninstall
|
||
}<br /> [
|
||
-A <em class="replaceable"><code>attrPath</code></em>
|
||
] [
|
||
-I <em class="replaceable"><code>path</code></em>
|
||
] [
|
||
--flake <em class="replaceable"><code>flake-uri</code></em>
|
||
] [
|
||
-b <em class="replaceable"><code>ext</code></em>
|
||
] [
|
||
{
|
||
-f
|
||
|
|
||
--file
|
||
} <em class="replaceable"><code>path</code></em>
|
||
] [
|
||
{
|
||
-h
|
||
|
|
||
--help
|
||
}
|
||
] [
|
||
--version
|
||
] [
|
||
{
|
||
-n
|
||
|
|
||
--dry-run
|
||
}
|
||
] [
|
||
--option <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em>
|
||
] [
|
||
--cores <em class="replaceable"><code>number</code></em>
|
||
] [
|
||
{
|
||
-j
|
||
|
|
||
--max-jobs
|
||
}
|
||
<em class="replaceable"><code>number</code></em>
|
||
] [
|
||
--debug
|
||
] [
|
||
--impure
|
||
] [
|
||
--keep-failed
|
||
] [
|
||
--keep-going
|
||
] [
|
||
{
|
||
-L
|
||
|
|
||
--print-build-logs
|
||
}
|
||
] [
|
||
--show-trace
|
||
] [
|
||
--(no-)substitute
|
||
] [
|
||
--no-out-link
|
||
] [
|
||
--refresh
|
||
] [
|
||
{
|
||
-v
|
||
|
|
||
--verbose
|
||
}
|
||
]</p></div></div><div class="refsection"><a id="id-1.13.2.4"></a><h2>Description</h2><p>
|
||
This command updates the user environment so that it corresponds to the
|
||
configuration specified in
|
||
<code class="filename">$XDG_CONFIG_HOME/home-manager/home.nix</code> or
|
||
<code class="filename">$XDG_CONFIG_HOME/home-manager/flake.nix</code>.
|
||
</p><p>
|
||
All operations using this tool expects a sub-command that indicates the
|
||
operation to perform. It must be one of
|
||
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
|
||
<code class="option">build</code>
|
||
</span></dt><dd><p>
|
||
Build configuration into a <code class="filename">result</code> directory.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">init</code> [<code class="option">--switch</code>] [<em class="replaceable"><code>dir</code></em>]
|
||
</span></dt><dd><p class="simpara">
|
||
Generates an initial <code class="filename">home.nix</code> file for the
|
||
current user. If Nix flakes are enabled, then this command also
|
||
generates a <code class="filename">flake.nix</code> file.
|
||
</p><p class="simpara">
|
||
If a path <em class="replaceable"><code>dir</code></em> is given then the
|
||
configuration will be generated in that directory. Otherwise, the
|
||
configuration will be generated in
|
||
<code class="filename">~/.config/home-manager</code>. The output directory will
|
||
be created if it does not exist.
|
||
</p><p class="simpara">
|
||
If the <code class="option">--switch</code> option is given, then the generated
|
||
configuration is activated.
|
||
</p><p class="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 <code class="option">init</code> command with <code class="option">--switch</code>
|
||
enabled to activate the configuration.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">instantiate</code>
|
||
</span></dt><dd><p>
|
||
Instantiate the configuration and print the resulting derivation.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">edit</code>
|
||
</span></dt><dd><p>
|
||
Open the home configuration using the editor indicated by
|
||
<code class="envar">EDITOR</code>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">expire-generations <em class="replaceable"><code>timestamp</code></em></code>
|
||
</span></dt><dd><p>
|
||
Remove generations older than <em class="replaceable"><code>timestamp</code></em> where
|
||
<em class="replaceable"><code>timestamp</code></em> is interpreted as in the
|
||
<code class="option">-d</code> argument of the <span class="citerefentry"><span class="refentrytitle">date</span>(1)</span> tool. For example <code class="literal">-30
|
||
days</code> or <code class="literal">2018-01-01</code>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">generations</code>
|
||
</span></dt><dd><p>
|
||
List all home environment generations.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">help</code>
|
||
</span></dt><dd><p>
|
||
Print tool help.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">news</code>
|
||
</span></dt><dd><p>
|
||
Show news entries in a pager.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">option <em class="replaceable"><code>option.name</code></em></code>
|
||
</span></dt><dd><p>
|
||
Inspect the given option name in the home configuration, like <span class="citerefentry"><span class="refentrytitle">nixos-option</span>(8)</span>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">packages</code>
|
||
</span></dt><dd><p>
|
||
List all packages installed in <code class="varname">home-manager-path</code>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">remove-generations <em class="replaceable"><code>ID …</code></em></code>
|
||
</span></dt><dd><p>
|
||
Remove indicated generations. Use the <code class="option">generations</code>
|
||
sub-command to find suitable generation numbers.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">switch</code>
|
||
</span></dt><dd><p>
|
||
Build and activate the configuration.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">uninstall</code>
|
||
</span></dt><dd><p>
|
||
Remove Home Manager from the user environment. This will
|
||
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
|
||
remove all managed files from the home directory,
|
||
</p></li><li class="listitem"><p>
|
||
remove packages installed through Home Manager from the user profile,
|
||
and
|
||
</p></li><li class="listitem"><p>
|
||
remove all Home Manager generations and make them available
|
||
for immediate garbage collection.
|
||
</p></li></ul></div><p>
|
||
</p></dd></dl></div><p>
|
||
</p></div><div class="refsection"><a id="id-1.13.2.5"></a><h2>Options</h2><p>
|
||
The tool accepts the options
|
||
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
|
||
<code class="option">-A <em class="replaceable"><code>attrPath</code></em></code>
|
||
</span></dt><dd><p>
|
||
Optional attribute that selects a configuration expression in the
|
||
configuration file. That is, if <code class="filename">home.nix</code> contains
|
||
</p><pre class="programlisting nix">
|
||
{
|
||
joe-at-work = {pkgs, ...}: { home.packages = [ pkgs.fortune ]; };
|
||
joe-at-home = {pkgs, ...}: { home.packages = [ pkgs.cowsay ]; };
|
||
}
|
||
</pre><p>
|
||
then the command <span class="command"><strong>home-manager switch -A joe-at-work</strong></span>
|
||
will activate the profile containing the fortune program.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">-I <em class="replaceable"><code>path</code></em></code>
|
||
</span></dt><dd><p>
|
||
Add a path to the Nix expression search path. For example, to build a
|
||
Home Manager profile using a specific Nixpkgs run <span class="command"><strong>home-manager
|
||
-I nixpkgs=/absolute/path/to/nixpkgs build</strong></span>. By default
|
||
<code class="literal"><nixpkgs></code> is used.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">--flake <em class="replaceable"><code>flake-uri[#name]</code></em></code>
|
||
</span></dt><dd><p>
|
||
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.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">-b <em class="replaceable"><code>extension</code></em></code>
|
||
</span></dt><dd><p>
|
||
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,
|
||
</p><pre class="screen">
|
||
<code class="prompt">$</code> <strong class="userinput"><code>home-manager -b bck switch</code></strong>
|
||
</pre><p>
|
||
will cause a colliding file <code class="filename">~/.config/foo.conf</code> to be
|
||
moved to <code class="filename">~/.config/foo.conf.bck</code>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">-f <em class="replaceable"><code>path</code></em></code>
|
||
, </span><span class="term">
|
||
<code class="option">--file <em class="replaceable"><code>path</code></em></code>
|
||
</span></dt><dd><p>
|
||
Indicates the path to the Home Manager configuration file. If not given,
|
||
<code class="filename">$XDG_CONFIG_HOME/home-manager/home.nix</code> is used.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">-h</code>
|
||
, </span><span class="term">
|
||
<code class="option">--help</code>
|
||
</span></dt><dd><p>
|
||
Prints usage information for the <span class="command"><strong>home-manager</strong></span> tool.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">--version</code>
|
||
</span></dt><dd><p>
|
||
Prints the version number of the <span class="command"><strong>home-manager</strong></span> tool.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">-n</code>
|
||
, </span><span class="term">
|
||
<code class="option">--dry-run</code>
|
||
</span></dt><dd><p>
|
||
Perform a dry-run of the given operation, only prints what actions would
|
||
be taken.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">--option <em class="replaceable"><code>name</code></em> <em class="replaceable"><code>value</code></em></code>
|
||
</span></dt><dd><p>
|
||
Passed on to <span class="citerefentry"><span class="refentrytitle">nix-build</span>(1)</span>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">--cores <em class="replaceable"><code>number</code></em></code>
|
||
</span></dt><dd><p>
|
||
Passed on to <span class="citerefentry"><span class="refentrytitle">nix-build</span>(1)</span>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">-j <em class="replaceable"><code>number</code></em></code>
|
||
, </span><span class="term">
|
||
<code class="option">--max-jobs <em class="replaceable"><code>number</code></em></code>
|
||
</span></dt><dd><p>
|
||
Passed on to <span class="citerefentry"><span class="refentrytitle">nix-build</span>(1)</span>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">--debug</code>
|
||
</span></dt><dd><p>
|
||
Passed on to <span class="citerefentry"><span class="refentrytitle">nix-build</span>(1)</span>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">--impure</code>
|
||
</span></dt><dd><p>
|
||
Passed on to <span class="citerefentry"><span class="refentrytitle">nix-build</span>(1)</span>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">--keep-failed</code>
|
||
</span></dt><dd><p>
|
||
Passed on to <span class="citerefentry"><span class="refentrytitle">nix-build</span>(1)</span>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">--keep-going</code>
|
||
</span></dt><dd><p>
|
||
Passed on to <span class="citerefentry"><span class="refentrytitle">nix-build</span>(1)</span>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">-L</code>
|
||
, </span><span class="term">
|
||
<code class="option">--print-build-logs</code>
|
||
</span></dt><dd><p>
|
||
Passed on to <span class="citerefentry"><span class="refentrytitle">nix build</span></span>
|
||
when building from a flake.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">--show-trace</code>
|
||
</span></dt><dd><p>
|
||
Passed on to <span class="citerefentry"><span class="refentrytitle">nix-build</span>(1)</span>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">--(no-)substitute</code>
|
||
</span></dt><dd><p>
|
||
Passed on to <span class="citerefentry"><span class="refentrytitle">nix-build</span>(1)</span>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">--no-out-link</code>
|
||
</span></dt><dd><p>
|
||
Passed on to <span class="citerefentry"><span class="refentrytitle">nix-build</span>(1)</span>
|
||
when running <span class="command"><strong>home-manager build</strong></span>.
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">--refresh</code>
|
||
</span></dt><dd><p>
|
||
Passed on to <span class="citerefentry"><span class="refentrytitle">nix-build</span>(1)</span>
|
||
</p></dd><dt><span class="term">
|
||
<code class="option">-v</code>
|
||
, </span><span class="term">
|
||
<code class="option">--verbose</code>
|
||
</span></dt><dd><p>
|
||
Activates verbose output.
|
||
</p></dd></dl></div></div><div class="refsection"><a id="id-1.13.2.6"></a><h2>Files</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term">
|
||
<code class="filename">$XDG_DATA_HOME/home-manager/news-read-ids</code>
|
||
</span></dt><dd><p>
|
||
Identifiers of news items that have been shown. Can be deleted to reset
|
||
the read news indicator.
|
||
</p></dd></dl></div></div><div class="refsection"><a id="id-1.13.2.7"></a><h2>Bugs</h2><p>
|
||
Please report any bugs on the
|
||
<a class="link" href="https://github.com/nix-community/home-manager/issues" target="_top">project
|
||
issue tracker</a>.
|
||
</p></div><div class="refsection"><a id="id-1.13.2.8"></a><h2>See also</h2><p>
|
||
<span class="citerefentry"><span class="refentrytitle">home-configuration.nix</span>(5)</span>
|
||
</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="nix-darwin-options.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="release-notes.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix C. nix-darwin Module Options </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Appendix E. Release Notes</td></tr></table></div></body></html> |