mirror of
https://github.com/nix-community/home-manager
synced 2024-12-24 10:49:48 +01:00
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.
This commit is contained in:
Robert Helgesson
parent
f82246171b
commit
42732990cd
5 changed files with 423 additions and 62 deletions
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
<manvolnum>1</manvolnum>
|
||||
<refentrytitle><command>home-manager</command>
|
||||
</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>
|
||||
<refpurpose>reconfigure a user environment</refpurpose>
|
||||
<refname><command>home-manager</command>
|
||||
</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><nixpkgs></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>
|
||||
|
|
@ -81,8 +411,7 @@
|
|||
<para>
|
||||
<citerefentry>
|
||||
<refentrytitle>home-configuration.nix</refentrytitle>
|
||||
<manvolnum>5</manvolnum>
|
||||
</citerefentry>
|
||||
<manvolnum>5</manvolnum> </citerefentry>
|
||||
</para>
|
||||
</refsection>
|
||||
</refentry>
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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") )
|
||||
;;
|
||||
|
|
|
|||
|
|
@ -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
|
||||
# command line then print help and exit.
|
||||
for arg in "$@"; do
|
||||
if [[ $arg == "--help" ]]; then
|
||||
doHelp
|
||||
exit 0
|
||||
fi
|
||||
done
|
||||
|
||||
while getopts 2f:I:A:b:vnh opt; do
|
||||
while [[ $# -gt 0 ]]; do
|
||||
opt="$1"
|
||||
shift
|
||||
case $opt in
|
||||
2)
|
||||
build|edit|expire-generations|generations|help|news|packages|remove-generations|switch|uninstall)
|
||||
COMMAND="$opt"
|
||||
;;
|
||||
-2)
|
||||
USE_NIX2_COMMAND=1
|
||||
;;
|
||||
f)
|
||||
HOME_MANAGER_CONFIG="$OPTARG"
|
||||
-A)
|
||||
HOME_MANAGER_CONFIG_ATTRIBUTE="$1"
|
||||
shift
|
||||
;;
|
||||
I)
|
||||
EXTRA_NIX_PATH+=("$OPTARG")
|
||||
-I)
|
||||
EXTRA_NIX_PATH+=("$1")
|
||||
shift
|
||||
;;
|
||||
A)
|
||||
HOME_MANAGER_CONFIG_ATTRIBUTE="$OPTARG"
|
||||
-b)
|
||||
export HOME_MANAGER_BACKUP_EXT="$1"
|
||||
shift
|
||||
;;
|
||||
b)
|
||||
export HOME_MANAGER_BACKUP_EXT="$OPTARG"
|
||||
-f|--file)
|
||||
HOME_MANAGER_CONFIG="$1"
|
||||
shift
|
||||
;;
|
||||
v)
|
||||
export VERBOSE=1
|
||||
-h|--help)
|
||||
doHelp
|
||||
;;
|
||||
n)
|
||||
-n|--dry-run)
|
||||
export DRY_RUN=1
|
||||
;;
|
||||
h)
|
||||
doHelp
|
||||
exit 0
|
||||
--show-trace)
|
||||
PASSTHROUGH_OPTS+=("$opt")
|
||||
;;
|
||||
-v|--verbose)
|
||||
export VERBOSE=1
|
||||
;;
|
||||
*)
|
||||
doHelp >&2
|
||||
case $COMMAND in
|
||||
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.
|
||||
shift "$((OPTIND-1))"
|
||||
|
||||
if [[ $# -eq 0 ]]; then
|
||||
if [[ -z $COMMAND ]]; then
|
||||
doHelp >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
cmd="$1"
|
||||
shift 1
|
||||
|
||||
case "$cmd" in
|
||||
case $COMMAND 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
|
||||
;;
|
||||
|
|
|
|||
Loading…
Reference in a new issue