mirror of
https://github.com/nix-community/home-manager.git
synced 2024-12-14 11:57:55 +00:00
400 lines
6.9 KiB
Groff
400 lines
6.9 KiB
Groff
.Dd January 1, 1980
|
|
.Dt home-manager 1
|
|
.Os Home Manager
|
|
.\" disable hyphenation
|
|
.nh
|
|
.\" disable justification (adjust text to left margin only)
|
|
.ad l
|
|
.\" enable line breaks after slashes
|
|
.cflags 4 /
|
|
.Sh NAME
|
|
.Nm home-manager
|
|
.Nd reconfigure a user environment
|
|
.
|
|
.
|
|
.
|
|
.Sh SYNOPSIS
|
|
.Nm home-manager
|
|
.Bro
|
|
.Cm build
|
|
.Cm | init Op Fl -switch Ar dir
|
|
.Cm | instantiate
|
|
.Cm | edit
|
|
.Cm | expire-generations Ar timestamp
|
|
.Cm | generations
|
|
.Cm | help
|
|
.Cm | news
|
|
.Cm | option Ar option.name
|
|
.Cm | packages
|
|
.Cm | remove-generations Ar ID \&...
|
|
.Cm | uninstall
|
|
.Brc
|
|
.Op Fl A Ar attrPath
|
|
.Op Fl I Ar path
|
|
.Op Fl -flake Ar flake-uri
|
|
.Op Fl b Ar ext
|
|
.Op Bro Fl f | Fl -file Brc Ar path
|
|
.Op Bro Fl h | Fl -help Brc
|
|
.Op Fl -version
|
|
.Op Bro Fl n | Fl -dry-run Brc
|
|
.Op Fl -option Ar name Ar value
|
|
.Op Fl -cores Ar number
|
|
.Op Bro Fl j | Fl -max-jobs Brc Ar number
|
|
.Op Fl -option
|
|
.Op Fl -impure
|
|
.Op Fl -keep-failed
|
|
.Op Fl -keep-going
|
|
.Op Bro Fl L | Fl -print-build-logs Brc
|
|
.Op Fl -show-trace
|
|
.Op Fl -(no-)substitute
|
|
.Op Fl -no-out-link
|
|
.Op Fl -refresh
|
|
.Op Bro Fl v | Fl -verbose Brc
|
|
.
|
|
.Sh DESCRIPTION
|
|
.Pp
|
|
This command updates the user environment so that it corresponds to the configuration specified in
|
|
$XDG_CONFIG_HOME/home-manager/home.nix
|
|
or
|
|
$XDG_CONFIG_HOME/home-manager/flake.nix.
|
|
.Pp
|
|
All operations using this tool expects a sub-command that indicates the operation to perform. It must be one of
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
|
|
.It Cm build
|
|
.RS 4
|
|
Build configuration into a result directory.
|
|
.RE
|
|
|
|
.It Cm init Op Fl -switch Op Ar dir
|
|
.RS 14
|
|
Generates an initial home.nix file for the current user. If Nix flakes are
|
|
enabled, then this command also generates a flake.nix file.
|
|
.sp
|
|
If a path
|
|
.Ar dir
|
|
is given then the configuration will be generated in that directory. Otherwise, the configuration will be generated in
|
|
~/.config/home-manager. The output directory will be created if it does not exist.
|
|
.sp
|
|
If the
|
|
.Fl -switch
|
|
option is given, then the generated configuration is activated.
|
|
.sp
|
|
Note, this command will not overwrite any existing files. It is therefore safe to initialize a configuration, edit it, and then re-run the
|
|
.Cm init
|
|
command with
|
|
.Fl -switch
|
|
enabled to activate the configuration.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm instantiate
|
|
.RS 15
|
|
Instantiate the configuration and print the resulting derivation\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm edit
|
|
.RS 16
|
|
Open the home configuration using the editor indicated by \fBEDITOR\fR\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm expire-generations Ar timestamp
|
|
.RS 4
|
|
Remove generations older than
|
|
.Ar timestamp
|
|
where
|
|
.Ar timestamp
|
|
is interpreted as in the
|
|
.Fl d
|
|
argument of the
|
|
\fBdate\fR(1)
|
|
tool. For example
|
|
-30 days or 2018-01-01.
|
|
.RE
|
|
.PP
|
|
|
|
.It Cm generations
|
|
.RS 4
|
|
List all home environment generations\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm help
|
|
.RS 4
|
|
Print tool help.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm news
|
|
.RS 4
|
|
Show news entries in a pager.
|
|
.RE
|
|
.PP
|
|
|
|
.It Cm option Ar option.name
|
|
.RS 4
|
|
Inspect the given option name in the home configuration, like
|
|
\fBnixos-option\fR(8)\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm packages
|
|
.RS 4
|
|
List all packages installed in home-manager-path.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm remove-generations Ar ID \&...
|
|
.RS 4
|
|
Remove indicated generations. Use the
|
|
.Cm generations
|
|
sub-command to find suitable generation numbers.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm switch
|
|
.RS 4
|
|
Build and activate the configuration\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm uninstall
|
|
.RS 4
|
|
Remove Home Manager from the user environment\&. This will
|
|
.sp
|
|
.RE
|
|
.RS 4
|
|
.Bl -bullet
|
|
.It
|
|
remove all managed files from the home directory,
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.It
|
|
remove packages installed through Home Manager from the user profile, and
|
|
.RE
|
|
.sp
|
|
.RS 4
|
|
.It
|
|
remove all Home Manager generations and make them available for immediate garbage collection\&.
|
|
.RE
|
|
.El
|
|
.sp
|
|
.RE
|
|
.El
|
|
.
|
|
.Sh OPTIONS
|
|
.Pp
|
|
The tool accepts the options
|
|
.Pp
|
|
.Bl -tag -width Ds
|
|
.It Cm Fl A Ar attrPath
|
|
.RS 4
|
|
Optional attribute that selects a configuration expression in the configuration file. That is, if
|
|
home.nix contains
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
{
|
|
joe\-at\-work = {pkgs, \&.\&.\&.}: { home\&.packages = [ pkgs\&.fortune ]; };
|
|
joe\-at\-home = {pkgs, \&.\&.\&.}: { home\&.packages = [ pkgs\&.cowsay ]; };
|
|
}
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
then the command
|
|
\fBhome\-manager switch \-A joe\-at\-work\fR
|
|
will activate the profile containing the fortune program\&.
|
|
.RE
|
|
.PP
|
|
.It Cm Fl I Ar path
|
|
.RS 4
|
|
Add a path to the Nix expression search path. For example, to build a Home Manager profile using a specific Nixpkgs run
|
|
.Cm home-manager Fl I Ar nixpkgs=/absolute/path/to/nixpkgs build.
|
|
By default
|
|
.Ar <nixpkgs>
|
|
is used.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl -flake Ar flake-uri[#name]
|
|
.RS 4
|
|
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.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl b Ar extension
|
|
.RS 4
|
|
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,
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
$ \fBhome\-manager \-b bck switch\fR
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
will cause a colliding file
|
|
~/\&.config/foo\&.conf
|
|
to be moved to
|
|
~/\&.config/foo\&.conf\&.bck\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl f Ar path, Fl -file Ar path
|
|
.RS 4
|
|
Indicates the path to the Home Manager configuration file. If not given,
|
|
$XDG_CONFIG_HOME/home-manager/home.nix
|
|
is used.
|
|
.RE
|
|
.Pp
|
|
.It Cm Fl h, Fl -help
|
|
.RS 4
|
|
Prints usage information for the
|
|
\fBhome\-manager\fR
|
|
tool.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl -version
|
|
.RS 4
|
|
Prints the version number of the
|
|
\fBhome\-manager\fR
|
|
tool.
|
|
.RE
|
|
.Pp
|
|
.It Cm Fl n, Fl -dry-run
|
|
.RS 4
|
|
Perform a dry-run of the given operation, only prints what actions would be taken.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl -option Ar name Ar value
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix-build\fR(1)\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl -cores Ar number
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix-build\fR(1)\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl j Ar number, Fl -max-jobs Ar number
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix-build\fR(1)\&.
|
|
.RE
|
|
.\" TODO
|
|
.Pp
|
|
.It Cm Fl -debug
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix-build\fR(1)\&.
|
|
.RE
|
|
.Pp
|
|
.It Cm Fl -impure
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix-build\fR(1)\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl -keep-failed
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix-build\fR(1)\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl -keep-going
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix-build\fR(1)\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl L, Fl -print-build-logs
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix build\fR()
|
|
when building from a flake\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl -show-trace
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix-build\fR(1)\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl -(no-)substitute
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix-build\fR(1)\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl -no-out-link
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix-build\fR(1)
|
|
when running
|
|
\fBhome\-manager build\fR\&.
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl -refresh
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix-build\fR(1)
|
|
.RE
|
|
.Pp
|
|
|
|
.It Cm Fl v, Fl -verbose
|
|
.RS 4
|
|
Activates verbose output\&.
|
|
.RE
|
|
.El
|
|
|
|
.Sh FILES
|
|
.Pp
|
|
$XDG_DATA_HOME/home\-manager/news\-read\-ids
|
|
.RS 4
|
|
Identifiers of news items that have been shown\&. Can be deleted to reset the read news indicator\&.
|
|
.RE
|
|
|
|
.Sh BUGS
|
|
.Pp
|
|
Please report any bugs on the
|
|
\m[blue]\fBproject issue tracker\fR\m[]\&.
|
|
|
|
.Sh SEE ALSO
|
|
.Pp
|
|
\fBhome-configuration.nix\fR(5)
|
|
|
|
.Sh AUTHOR
|
|
.Pp
|
|
\fBHome Manager contributors\fR
|
|
.RS 4
|
|
Author.
|
|
.RE
|
|
|
|
.Sh COPYRIGHT
|
|
.br
|
|
Copyright \(co 2017\(en2022 Home Manager contributors
|
|
.br
|