From 14f29065e1f2c2579075cd59b54b156c3e646d0c Mon Sep 17 00:00:00 2001 From: Viktor Kronvall Date: Tue, 21 Nov 2023 01:40:49 +0900 Subject: [PATCH] docs: add home-manager manpage --- docs/default.nix | 2 + docs/home-manager.1 | 394 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 396 insertions(+) create mode 100644 docs/home-manager.1 diff --git a/docs/default.nix b/docs/default.nix index f5d2fe743..20974c2fd 100644 --- a/docs/default.nix +++ b/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 { diff --git a/docs/home-manager.1 b/docs/home-manager.1 new file mode 100644 index 000000000..b74355efb --- /dev/null +++ b/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 +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