docs: add home-manager manpage

docs/default.nix

@@ -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 {

docs/home-manager.1

@@ -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