diff --git a/doc/default.nix b/doc/default.nix
index e65e904d..c94d52c9 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -119,6 +119,7 @@ let
+
diff --git a/doc/man-home-manager.xml b/doc/man-home-manager.xml
index deb2a3ba..d83566a3 100644
--- a/doc/man-home-manager.xml
+++ b/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">
- home-manager
- 1
+ home-manager
+ 1
Home Manager
-
- home-manager
- reconfigure a user environment
+ home-manager
+ reconfigure a user environment
home-manager
-
+ build
-
+ edit
-
+ expire-generations timestamp
-
+ generations
-
+ help
-
+ news
-
+ packages
+
+
+
+ remove-generations ID …
+
+
+
+ switch
+
+
+
+ uninstall
+
+
+ -A attrPath
+
+
+
+ -I path
+
+
+
+ -b ext
+
+
+
+
+
+ -f
+
+
+
+ --file
+
+ path
+
+
+
+
+
+ -h
+
+
+
+ --help
+
+
+
+
+
+
+
+ -n
+
+
+
+ --dry-run
+
+
+
+
+
+ --show-trace
+
+
+
+
+
+ -v
+
+
+
+ --verbose
+
+
+
@@ -50,6 +125,261 @@
This command updates the user environment so that it corresponds to the
configuration specified in ~/.config/nixpkgs/home.nix.
+
+ All operations using this tool expects a sub-command that indicates the
+ operation to perform. It must be one of
+
+
+
+
+
+
+
+ Build configuration into a result directory.
+
+
+
+
+
+
+
+
+
+ Open the home configuration using the editor indicated by
+ EDITOR.
+
+
+
+
+
+
+
+
+
+ Remove generations older than timestamp where
+ timestamp is interpreted as in the
+ argument of the
+ date
+ 1 tool. For example -30
+ days or 2018-01-01.
+
+
+
+
+
+
+
+
+
+ List all home environment generations.
+
+
+
+
+
+
+
+
+
+ Print tool help.
+
+
+
+
+
+
+
+
+
+ Show news entries in a pager.
+
+
+
+
+
+
+
+
+
+ List all packages installed in home-manager-path.
+
+
+
+
+
+
+
+
+
+ Remove indicated generations. Use the
+ sub-command to find suitable generation numbers.
+
+
+
+
+
+
+
+
+
+ Build and activate the configuration.
+
+
+
+
+
+
+
+
+
+ Remove Home Manager from the user environment. This will
+
+
+
+ remove all managed files from the home directory,
+
+
+
+
+ remove packages installed through Home Manager from the user profile,
+ and
+
+
+
+
+ optionally remove all Home Manager generations and make them
+ available for immediate garbage collection.
+
+
+
+
+
+
+
+
+
+
+ Options
+
+ The tool accepts the options
+
+
+
+
+
+
+
+
+ Optional attribute that selects a configuration expression in the
+ configuration file. That is, if home.nix contains
+
+{
+ joe-at-work = {pkgs, ...}: { home.packages = [ pkgs.fortune ]; };
+ joe-at-home = {pkgs, ...}: { home.packages = [ pkgs.cowsay ]; };
+}
+
+ then the command home-manager switch -A joe-at-work
+ will activate the profile containing the fortune program.
+
+
+
+
+
+
+
+
+
+ Add a path to the Nix expression search path. For example, to build a
+ Home Manager profile using a specific Nixpkgs run home-manager
+ -I nixpkgs=/absolute/path/to/nixpkgs build. By default
+ <nixpkgs> is used.
+
+
+
+
+
+
+
+
+
+ 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,
+
+$ home-manager -b bck switch
+
+ will cause a colliding file ~/.config/foo.conf to be
+ moved to ~/.config/foo.conf.bck.
+
+
+
+
+
+
+
+
+
+
+
+
+ Indicates the path to the Home Manager configuration file. If not given,
+ ~/.config/nixpkgs/home.nix is used.
+
+
+
+
+
+
+
+
+
+
+
+
+ Prints usage information for the home-manager tool.
+
+
+
+
+
+
+
+
+
+
+
+
+ Perform a dry-run of the given operation, only prints what actions would
+ be taken.
+
+
+
+
+
+
+
+
+
+ Passed on to
+ nix-build
+ 1 .
+
+
+
+
+
+
+
+
+
+
+
+
+ Activates verbose output.
+
+
+
+
Files
@@ -77,12 +407,11 @@
- See also
-
-
- home-configuration.nix
- 5
-
-
+ See also
+
+
+ home-configuration.nix
+ 5
+
diff --git a/doc/manual.xml b/doc/manual.xml
index c4493254..014a4a7a 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -30,5 +30,9 @@
Configuration Options
+
+ Tools
+
+
diff --git a/home-manager/completion.bash b/home-manager/completion.bash
index cb7c0009..501b8727 100644
--- a/home-manager/completion.bash
+++ b/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
#
@@ -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") )
;;
diff --git a/home-manager/home-manager b/home-manager/home-manager
index b6ea92ed..bd81fc92 100644
--- a/home-manager/home-manager
+++ b/home-manager/home-manager
@@ -93,12 +93,14 @@ function doBuildAttr() {
nix build \
-f "" \
$extraArgs \
+ ${PASSTHROUGH_OPTS[*]} \
--argstr confPath "$HOME_MANAGER_CONFIG" \
--argstr confAttr "$HOME_MANAGER_CONFIG_ATTRIBUTE"
else
nix-build \
"" \
$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
- exit 1
+ 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
;;