diff --git a/doc/default.nix b/doc/default.nix index e65e904df..c94d52c9e 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 deb2a3baf..d83566a3c 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 c4493254b..014a4a7a8 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 cb7c00096..501b87279 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 b6ea92edb..bd81fc923 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 ;;