eeva/home-manager
1
0
Fork 0
mirror of https://github.com/nix-community/home-manager synced 2024-11-30 15:09:46 +01:00
Code Issues Releases Wiki Activity
home-manager/tools.html
rycee 1a571e4e35 deploy: 2c29ae48f9
2023-01-18 12:40:32 +00:00

292 lines
No EOL
15 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?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.12.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.12.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
|
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
] [
{
-v
|
--verbose
}
]</p></div></div><div class="refsection"><a id="id-1.12.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">~/.config/nixpkgs/home.nix</code> or <code class="filename">~/.config/nixpkgs/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">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>
optionally 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.12.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">&lt;nixpkgs&gt;</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/nixpkgs/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">-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.12.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.12.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.12.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>
Reference in a new issue View git blame Copy permalink