mirror of
https://github.com/nix-community/home-manager.git
synced 2025-11-08 19:46:05 +01:00
64c49b1aa5
- calls nix-instatiate instead of nixos-option (using nix-option's underlying nix script). - loops over options to display since nixos-option can only process a single option. - passes through the --recursive flag from nixos-option. and includes --help and man page for the flag. details: nixos-option was changed from a C++ command to a shell script that feeds a nix script (with arguments) to nix-instatiate. in the process, the --config_expr and --options_expr we once passed to nixos-option were removed. without changing the nixos-option shell script, we have no may to override the arguments to the nixos-option nix script. luckily, we can use our modulesExpr as a direct argument to the new nixos-option nix script. unluckily, the nix script does not accept multiple options per instantiation. so we are also looping through the given options ourselves and feeding them each to nixos-option's nix script. the nixos-option shell and nix scripts are in different places in the nix store, so we have to search the store for the nix script given the location of the shell script. also, the nixos-option nix script wants a 'recursive' flag, so we now honor that flag for the home-manager option subcommand.
424 lines
7.5 KiB
Groff
424 lines
7.5 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 Oo Fl -recursive Oc Ar option.name
|
|
.Cm | packages
|
|
.Cm | remove-generations Ar ID \&...
|
|
.Cm | switch
|
|
.Op Fl -rollback
|
|
.Op Bro Fl c | Fl -specialisation Brc Ar NAME
|
|
.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 -log-format
|
|
.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 \fBVISUAL\fR or \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 Oo Fl -recursive Oc Ar option.name
|
|
.RS 4
|
|
Inspect the given option name in the home configuration, like
|
|
\fBnixos-option\fR(8)\&.
|
|
.sp
|
|
If the
|
|
.Fl -recursive
|
|
option is given, print all the values at or below the option name recursively\&.
|
|
.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 Oo Fl -rollback Oc Oo Bro Fl c | Fl -specialisation Brc Ar NAME Oc
|
|
.RS 4
|
|
Build and activate the configuration\&.
|
|
.sp
|
|
If the
|
|
.Fl -rollback
|
|
option is given, then the build is not done, instead roll back to and
|
|
activate the configuration prior to the current configuration\&.
|
|
.sp
|
|
If the
|
|
.Fl -specialisation
|
|
option is given, then the named specialisation is activated\&.
|
|
.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 -log-format Ar format
|
|
.RS 4
|
|
Passed on to
|
|
\fBnix-build\fR(1)\&.
|
|
.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\(en2025 Home Manager contributors
|
|
.br
|