mirror of
https://github.com/nix-community/home-manager
synced 2024-11-26 21:19:45 +01:00
docs: add home-manager manpage
This commit is contained in:
parent
80ac72bf03
commit
728423e6f4
2 changed files with 396 additions and 0 deletions
|
@ -110,10 +110,12 @@ let
|
||||||
} ''
|
} ''
|
||||||
# Generate manpages.
|
# Generate manpages.
|
||||||
mkdir -p $out/share/man/man5
|
mkdir -p $out/share/man/man5
|
||||||
|
mkdir -p $out/share/man/man1
|
||||||
home-manager-render-docs -j $NIX_BUILD_CORES options manpage \
|
home-manager-render-docs -j $NIX_BUILD_CORES options manpage \
|
||||||
--revision ${revision} \
|
--revision ${revision} \
|
||||||
${hmOptionsDocs.optionsJSON}/share/doc/nixos/options.json \
|
${hmOptionsDocs.optionsJSON}/share/doc/nixos/options.json \
|
||||||
$out/share/man/man5/home-configuration.nix.5
|
$out/share/man/man5/home-configuration.nix.5
|
||||||
|
cp ${./home-manager.1} $out/share/man/man1/home-manager.1
|
||||||
'';
|
'';
|
||||||
# Generate the HTML manual pages
|
# Generate the HTML manual pages
|
||||||
home-manager-manual = pkgs.callPackage ./home-manager-manual.nix {
|
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