mirror of
https://github.com/nix-community/home-manager
synced 2024-11-10 21:29:48 +01:00
docs: add home-manager manpage
This commit is contained in:
Viktor Kronvall
Mikilio
parent
186fe307c2
commit
ebe95dbf1a
2 changed files with 396 additions and 0 deletions
|
|
@ -110,10 +110,12 @@ let
|
|||
} ''
|
||||
# Generate manpages.
|
||||
mkdir -p $out/share/man/man5
|
||||
mkdir -p $out/share/man/man1
|
||||
home-manager-render-docs -j $NIX_BUILD_CORES options manpage \
|
||||
--revision ${revision} \
|
||||
${hmOptionsDocs.optionsJSON}/share/doc/nixos/options.json \
|
||||
$out/share/man/man5/home-configuration.nix.5
|
||||
cp ${./home-manager.1} $out/share/man/man1/home-manager.1
|
||||
'';
|
||||
# Generate the HTML manual pages
|
||||
home-manager-manual = pkgs.callPackage ./home-manager-manual.nix {
|
||||
|
|
|
|||
394
docs/home-manager.1
Normal file
394
docs/home-manager.1
Normal file
|
|
@ -0,0 +1,394 @@
|
|||
.Dd January 1, 1980
|
||||
.Dt home-manager 8
|
||||
.Os
|
||||
.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
|
||||
|
||||
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
|
||||
Loading…
Reference in a new issue