home-manager: rewrite argument parsing

This rewrite allows "long options" but unfortunately does not allow
merged options such as `-vn`.

Also improve the home-manager manual page, with this it should include
all sub-commands and arguments.

Finally, include the home-manager manual page in the generated HTML
documentation.

doc/default.nix

@@ -119,6 +119,7 @@ let
       <toc role="chunk-toc">
         <d:tocentry xmlns:d="http://docbook.org/ns/docbook" linkend="book-home-manager-manual"><?dbhtml filename="index.html"?>
           <d:tocentry linkend="ch-options"><?dbhtml filename="options.html"?></d:tocentry>
+          <d:tocentry linkend="ch-tools"><?dbhtml filename="tools.html"?></d:tocentry>
           <d:tocentry linkend="ch-release-notes"><?dbhtml filename="release-notes.html"?></d:tocentry>
         </d:tocentry>
       </toc>

doc/man-home-manager.xml

@@ -2,46 +2,121 @@
           xmlns:xlink="http://www.w3.org/1999/xlink"
           xmlns:xi="http://www.w3.org/2001/XInclude">
  <refmeta>
-  <refentrytitle><command>home-manager</command></refentrytitle>
+  <refentrytitle><command>home-manager</command>
-  <manvolnum>1</manvolnum>
+  </refentrytitle><manvolnum>1</manvolnum>
   <refmiscinfo class="source">Home Manager</refmiscinfo>
-<!-- <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo> -->
  </refmeta>
  <refnamediv>
-  <refname><command>home-manager</command></refname>
+  <refname><command>home-manager</command>
-  <refpurpose>reconfigure a user environment</refpurpose>
+  </refname><refpurpose>reconfigure a user environment</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>home-manager</command> <group choice="req"> 
    <arg choice="plain">
-    <option>help</option>
+    build
    </arg>
     
    <arg choice="plain">
-    <option>build</option>
+    edit
    </arg>
     
    <arg choice="plain">
-    <option>switch</option>
+    expire-generations <replaceable>timestamp</replaceable>
    </arg>
     
    <arg choice="plain">
-    <option>generations</option>
+    generations
    </arg>
     
    <arg choice="plain">
-    <option>remove-generations</option>
+    help
    </arg>
     
    <arg choice="plain">
-    <option>packages</option>
+    news
    </arg>
     
    <arg choice="plain">
-    <option>news</option>
+    packages
+   </arg>
+    
+   <arg choice="plain">
+    remove-generations <replaceable>ID …</replaceable>
+   </arg>
+    
+   <arg choice="plain">
+    switch
+   </arg>
+    
+   <arg choice="plain">
+    uninstall
    </arg>
     </group>
+   <sbr />
+   <arg>
+    -A <replaceable>attrPath</replaceable>
+   </arg>
+    
+   <arg>
+    -I <replaceable>path</replaceable>
+   </arg>
+    
+   <arg>
+    -b <replaceable>ext</replaceable>
+   </arg>
+    
+   <arg>
+    <group choice="req"> 
+    <arg choice="plain">
+     -f
+    </arg>
+     
+    <arg choice="plain">
+     --file
+    </arg>
+     </group> <replaceable>path</replaceable>
+   </arg>
+    
+   <arg>
+    <group choice="req"> 
+    <arg choice="plain">
+     -h
+    </arg>
+     
+    <arg choice="plain">
+     --help
+    </arg>
+     </group>
+   </arg>
+    
+   <arg>
+    <group choice="req"> 
+    <arg choice="plain">
+     -n
+    </arg>
+     
+    <arg choice="plain">
+     --dry-run
+    </arg>
+     </group>
+   </arg>
+    
+   <arg>
+    --show-trace
+   </arg>
+    
+   <arg>
+    <group choice="req"> 
+    <arg choice="plain">
+     -v
+    </arg>
+     
+    <arg choice="plain">
+     --verbose
+    </arg>
+     </group>
+   </arg>
   </cmdsynopsis>
  </refsynopsisdiv>
  <refsection>
@@ -50,6 +125,261 @@
    This command updates the user environment so that it corresponds to the
    configuration specified in <filename>~/.config/nixpkgs/home.nix</filename>.
   </para>
+  <para>
+   All operations using this tool expects a sub-command that indicates the
+   operation to perform. It must be one of
+   <variablelist>
+    <varlistentry>
+     <term>
+      <option>build</option>
+     </term>
+     <listitem>
+      <para>
+       Build configuration into a <filename>result</filename> directory.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <option>edit</option>
+     </term>
+     <listitem>
+      <para>
+       Open the home configuration using the editor indicated by
+       <envar>EDITOR</envar>.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <option>expire-generations <replaceable>timestamp</replaceable></option>
+     </term>
+     <listitem>
+      <para>
+       Remove generations older than <replaceable>timestamp</replaceable> where
+       <replaceable>timestamp</replaceable> is interpreted as in the
+       <option>-d</option> argument of the <citerefentry>
+       <refentrytitle>date</refentrytitle>
+       <manvolnum>1</manvolnum> </citerefentry> tool. For example <literal>-30
+       days</literal> or <literal>2018-01-01</literal>.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <option>generations</option>
+     </term>
+     <listitem>
+      <para>
+       List all home environment generations.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <option>help</option>
+     </term>
+     <listitem>
+      <para>
+       Print tool help.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <option>news</option>
+     </term>
+     <listitem>
+      <para>
+       Show news entries in a pager.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <option>packages</option>
+     </term>
+     <listitem>
+      <para>
+       List all packages installed in <varname>home-manager-path</varname>.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <option>remove-generations <replaceable>ID …</replaceable></option>
+     </term>
+     <listitem>
+      <para>
+       Remove indicated generations. Use the <option>generations</option>
+       sub-command to find suitable generation numbers.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <option>switch</option>
+     </term>
+     <listitem>
+      <para>
+       Build and activate the configuration.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term>
+      <option>uninstall</option>
+     </term>
+     <listitem>
+      <para>
+       Remove Home Manager from the user environment. This will
+       <itemizedlist>
+        <listitem>
+         <para>
+          remove all managed files from the home directory,
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          remove packages installed through Home Manager from the user profile,
+          and
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          optionally remove all Home Manager generations and make them
+          available for immediate garbage collection.
+         </para>
+        </listitem>
+       </itemizedlist>
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsection>
+ <refsection>
+  <title>Options</title>
+  <para>
+   The tool accepts the options
+  </para>
+  <variablelist>
+   <varlistentry>
+    <term>
+     <option>-A <replaceable>attrPath</replaceable></option>
+    </term>
+    <listitem>
+     <para>
+      Optional attribute that selects a configuration expression in the
+      configuration file. That is, if <filename>home.nix</filename> contains
+<programlisting language="nix">
+{
+  joe-at-work = {pkgs, ...}: { home.packages = [ pkgs.fortune ]; };
+  joe-at-home = {pkgs, ...}: { home.packages = [ pkgs.cowsay ]; };
+}
+</programlisting>
+      then the command <command>home-manager switch -A joe-at-work</command>
+      will activate the profile containing the fortune program.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <option>-I <replaceable>path</replaceable></option>
+    </term>
+    <listitem>
+     <para>
+      Add a path to the Nix expression search path. For example, to build a
+      Home Manager profile using a specific Nixpkgs run <command>home-manager
+      -I nixpkgs=/absolute/path/to/nixpkgs build</command>. By default
+      <literal>&lt;nixpkgs&gt;</literal> is used.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <option>-b <replaceable>extension</replaceable></option>
+    </term>
+    <listitem>
+     <para>
+      Enabled automatic resolution of collisions between unmanaged and managed
+      files. The name of the original file will be suffixed by the given
+      extension. For example,
+<screen>
+<prompt>$</prompt> <userinput>home-manager -b bck switch</userinput>
+</screen>
+      will cause a colliding file <filename>~/.config/foo.conf</filename> to be
+      moved to <filename>~/.config/foo.conf.bck</filename>.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <option>-f <replaceable>path</replaceable></option>
+    </term>
+    <term>
+     <option>--file <replaceable>path</replaceable></option>
+    </term>
+    <listitem>
+     <para>
+      Indicates the path to the Home Manager configuration file. If not given,
+      <filename>~/.config/nixpkgs/home.nix</filename> is used.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <option>-h</option>
+    </term>
+    <term>
+     <option>--help</option>
+    </term>
+    <listitem>
+     <para>
+      Prints usage information for the <command>home-manager</command> tool.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <option>-n</option>
+    </term>
+    <term>
+     <option>--dry-run</option>
+    </term>
+    <listitem>
+     <para>
+      Perform a dry-run of the given operation, only prints what actions would
+      be taken.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <option>--show-trace</option>
+    </term>
+    <listitem>
+     <para>
+      Passed on to <citerefentry>
+      <refentrytitle>nix-build</refentrytitle>
+      <manvolnum>1</manvolnum> </citerefentry>.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry>
+    <term>
+     <option>-v</option>
+    </term>
+    <term>
+     <option>--verbose</option>
+    </term>
+    <listitem>
+     <para>
+      Activates verbose output.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
  </refsection>
  <refsection>
   <title>Files</title>
@@ -77,12 +407,11 @@
   </para>
  </refsection>
  <refsection>
-   <title>See also</title>
+  <title>See also</title>
-   <para>
+  <para>
-     <citerefentry>
+   <citerefentry>
-       <refentrytitle>home-configuration.nix</refentrytitle>
+   <refentrytitle>home-configuration.nix</refentrytitle>
-       <manvolnum>5</manvolnum>
+   <manvolnum>5</manvolnum> </citerefentry>
-     </citerefentry>
+  </para>
-   </para>
  </refsection>
 </refentry>

doc/manual.xml

@@ -30,5 +30,9 @@
   <title>Configuration Options</title>
   <xi:include href="./generated/options-db.xml" xpointer="configuration-variable-list" />
  </appendix>
+ <appendix xml:id="ch-tools">
+  <title>Tools</title>
+  <xi:include href="./man-home-manager.xml" />
+ </appendix>
  <xi:include href="./release-notes/release-notes.xml" />
 </book>

home-manager/completion.bash

@@ -49,9 +49,13 @@
 # -A
 # -I
 # -f
+# --file
 # -h
+# --help
 # -n
+# --dry-run
 # -v
+# --verbose
 # build
 # edit
 # expire-generations
@@ -61,6 +65,7 @@
 # packages
 # remove-generations
 # switch
+# uninstall
 
 # $ home-manager e<TAB>
 #
@@ -88,15 +93,21 @@
 #   expire-generations
 #   packages
 #   news
+#   uninstall
 
 # « home-manager » Options:
 #
+#   -b EXT
 #   -f FILE
+#   --file FILE
 #   -A ATTRIBUTE
 #   -I PATH
 #   -v
+#   --verbose
 #   -n
+#   --dry-run
 #   -h
+#   --help
 
 # $ home-manager
 #
@@ -109,6 +120,7 @@
 #   -A ATTRIBUTE Optional attribute that selects a configuration
 #                expression in the configuration file.
 #   -I PATH      Add a path to the Nix expression search path.
+#   -b EXT       Move existing files to new path rather than fail.
 #   -v           Verbose output
 #   -n           Do a dry run, only prints what actions would be taken
 #   -h           Print this help
@@ -138,7 +150,8 @@
 #
 #   news         Show news entries in a pager
 #
-
+#   uninstall    Remove Home Manager
+#
 ##################################################
 # Dependencies:
 
@@ -265,14 +278,14 @@ _home-manager_completions ()
     #--------------------------#
 
     local Subcommands
-    Subcommands=( "help" "edit" "build" "switch" "generations" "remove-generations" "expire-generations" "packages" "news" )
+    Subcommands=( "help" "edit" "build" "switch" "generations" "remove-generations" "expire-generations" "packages" "news" "uninstall" )
 
     # ^ « home-manager »'s subcommands.
 
     #--------------------------#
 
     local Options
-    Options=( "-f" "-A" "-I" "-h" "-n" "-v" )
+    Options=( "-f" "--file" "-b" "-A" "-I" "-h" "--help" "-n" "--dry-run" "-v" "--verbose" "--show-trace" )
 
     # ^ « home-manager »'s options.
 
@@ -304,7 +317,7 @@ _home-manager_completions ()
 
     case "$PreviousWord" in
 
-        "-f")
+        "-f"|"--file")
 
             COMPREPLY+=( $( compgen -A file -- "$CurrentWord") )
             ;;

home-manager/home-manager

@@ -93,12 +93,14 @@ function doBuildAttr() {
         nix build \
             -f "<home-manager/home-manager/home-manager.nix>" \
             $extraArgs \
+            ${PASSTHROUGH_OPTS[*]} \
             --argstr confPath "$HOME_MANAGER_CONFIG" \
             --argstr confAttr "$HOME_MANAGER_CONFIG_ATTRIBUTE"
     else
         nix-build \
             "<home-manager/home-manager/home-manager.nix>" \
             $extraArgs \
+            ${PASSTHROUGH_OPTS[*]} \
             --argstr confPath "$HOME_MANAGER_CONFIG" \
             --argstr confAttr "$HOME_MANAGER_CONFIG_ATTRIBUTE"
     fi
@@ -451,62 +453,69 @@ function doHelp() {
 
 EXTRA_NIX_PATH=()
 HOME_MANAGER_CONFIG_ATTRIBUTE=""
+PASSTHROUGH_OPTS=()
+COMMAND=""
+COMMAND_ARGS=()
 
-# As a special case, if the user has given --help anywhere on the
+while [[ $# -gt 0 ]]; do
-# command line then print help and exit.
+    opt="$1"
-for arg in "$@"; do
+    shift
-    if [[ $arg == "--help" ]]; then
-        doHelp
-        exit 0
-    fi
-done
-
-while getopts 2f:I:A:b:vnh opt; do
     case $opt in
-        2)
+        build|edit|expire-generations|generations|help|news|packages|remove-generations|switch|uninstall)
+            COMMAND="$opt"
+            ;;
+        -2)
             USE_NIX2_COMMAND=1
             ;;
-        f)
+        -A)
-            HOME_MANAGER_CONFIG="$OPTARG"
+            HOME_MANAGER_CONFIG_ATTRIBUTE="$1"
+            shift
             ;;
-        I)
+        -I)
-            EXTRA_NIX_PATH+=("$OPTARG")
+            EXTRA_NIX_PATH+=("$1")
+            shift
             ;;
-        A)
+        -b)
-            HOME_MANAGER_CONFIG_ATTRIBUTE="$OPTARG"
+            export HOME_MANAGER_BACKUP_EXT="$1"
+            shift
             ;;
-        b)
+        -f|--file)
-            export HOME_MANAGER_BACKUP_EXT="$OPTARG"
+            HOME_MANAGER_CONFIG="$1"
+            shift
             ;;
-        v)
+        -h|--help)
-            export VERBOSE=1
+            doHelp
             ;;
-        n)
+        -n|--dry-run)
             export DRY_RUN=1
             ;;
-        h)
+        --show-trace)
-            doHelp
+            PASSTHROUGH_OPTS+=("$opt")
-            exit 0
+            ;;
+        -v|--verbose)
+            export VERBOSE=1
             ;;
         *)
-            doHelp >&2
+            case $COMMAND in
-            exit 1
+                expire-generations|remove-generations)
+                    COMMAND_ARGS+=("$opt")
+                    ;;
+                *)
+                    errorEcho "$0: unknown option '$opt'"
+                    errorEcho "Run '$0 --help' for usage help"
+                    exit 1
+                    ;;
+            esac
             ;;
     esac
 done
 
-# Get rid of the options.
+if [[ -z $COMMAND ]]; then
-shift "$((OPTIND-1))"
-
-if [[ $# -eq 0 ]]; then
     doHelp >&2
     exit 1
 fi
 
-cmd="$1"
+case $COMMAND in
-shift 1
-
-case "$cmd" in
     edit)
         doEdit
         ;;
@@ -520,10 +529,15 @@ case "$cmd" in
         doListGens
         ;;
     remove-generations)
-        doRmGenerations "$@"
+        doRmGenerations "${COMMAND_ARGS[@]}"
         ;;
     expire-generations)
-        doExpireGenerations "$@"
+        if [[ ${#COMMAND_ARGS[@]} != 1 ]]; then
+            errorEcho "expire-generations expects one argument, got ${#COMMAND_ARGS[@]}."
+            exit 1
+        else
+            doExpireGenerations "${COMMAND_ARGS[@]}"
+        fi
         ;;
     packages)
         doListPackages
@@ -534,11 +548,11 @@ case "$cmd" in
     uninstall)
         doUninstall
         ;;
-    help|--help)
+    help)
         doHelp
         ;;
     *)
-        errorEcho "Unknown command: $cmd"
+        errorEcho "Unknown command: $COMMAND"
         doHelp >&2
         exit 1
         ;;