From b521c0c6bd11e259fb52e6eee538c355f177d2f4 Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Wed, 4 Dec 2024 12:07:58 +0000
Subject: [PATCH 01/11] nixos-rebuild-ng: add --builders as common_build_flags

---
 pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py b/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py
index c7dbf8acb350..86a6af876de3 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py
@@ -30,6 +30,7 @@ def get_parser() -> tuple[argparse.ArgumentParser, dict[str, argparse.ArgumentPa
     common_flags.add_argument("--option", nargs=2)
 
     common_build_flags = argparse.ArgumentParser(add_help=False)
+    common_build_flags.add_argument("--builders")
     common_build_flags.add_argument("--include", "-I")
     common_build_flags.add_argument("--quiet", action="store_true")
     common_build_flags.add_argument("--print-build-logs", "-L", action="store_true")

From 916d65a2d022c739c0117f29d845243abbf6014d Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Wed, 4 Dec 2024 12:32:13 +0000
Subject: [PATCH 02/11] nixos-rebuild-ng: add shell completion via shtab

---
 pkgs/by-name/ni/nixos-rebuild-ng/README.md    |   2 +-
 pkgs/by-name/ni/nixos-rebuild-ng/package.nix  |  27 +++--
 .../src/nixos_rebuild/__init__.py             | 111 ++++++++++++++----
 3 files changed, 110 insertions(+), 30 deletions(-)

diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/README.md b/pkgs/by-name/ni/nixos-rebuild-ng/README.md
index 9a565de2dd18..88cd9a82f37a 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/README.md
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/README.md
@@ -109,7 +109,7 @@ ruff format .
   `system.switch.enableNg` for `switch-to-configuration-ng`
 - [ ] Improve documentation
 - [x] `nixos-rebuild repl`
-- [ ] Generate tab completion via [`shtab`](https://docs.iterative.ai/shtab/)
+- [x] Generate tab completion via [`shtab`](https://docs.iterative.ai/shtab/)
 - [x] Reduce build closure
 
 ## TODON'T
diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/package.nix b/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
index 4ef9d29807f5..1e222d08e5cd 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
@@ -1,5 +1,6 @@
 {
   lib,
+  stdenv,
   installShellFiles,
   mkShell,
   nix,
@@ -7,8 +8,12 @@
   python3,
   python3Packages,
   runCommand,
+  withShellCompletion ? (stdenv.buildPlatform.canExecute stdenv.hostPlatform),
   withNgSuffix ? true,
 }:
+let
+  executable = if withNgSuffix then "nixos-rebuild-ng" else "nixos-rebuild";
+in
 python3Packages.buildPythonApplication rec {
   pname = "nixos-rebuild-ng";
   version = "0.0.0";
@@ -23,9 +28,13 @@ python3Packages.buildPythonApplication rec {
     tabulate
   ];
 
-  nativeBuildInputs = [
-    installShellFiles
-  ];
+  nativeBuildInputs =
+    [
+      installShellFiles
+    ]
+    ++ lib.optionals withShellCompletion [
+      python3Packages.shtab
+    ];
 
   propagatedBuildInputs = [
     # Make sure that we use the Nix package we depend on, not something
@@ -42,12 +51,14 @@ python3Packages.buildPythonApplication rec {
   postInstall =
     ''
       installManPage ${nixos-rebuild}/share/man/man8/nixos-rebuild.8
-
-      installShellCompletion \
-        --bash ${nixos-rebuild}/share/bash-completion/completions/_nixos-rebuild
+    ''
+    + lib.optionalString withShellCompletion ''
+      installShellCompletion --cmd ${executable} \
+        --bash <(shtab --shell bash nixos_rebuild.get_main_parser) \
+        --zsh <(shtab --shell zsh nixos_rebuild.get_main_parser)
     ''
     + lib.optionalString withNgSuffix ''
-      mv $out/bin/nixos-rebuild $out/bin/nixos-rebuild-ng
+      mv $out/bin/nixos-rebuild $out/bin/${executable}
     '';
 
   nativeCheckInputs = with python3Packages; [
@@ -98,6 +109,6 @@ python3Packages.buildPythonApplication rec {
     homepage = "https://github.com/NixOS/nixpkgs/tree/master/pkgs/by-name/ni/nixos-rebuild-ng";
     license = lib.licenses.mit;
     maintainers = [ lib.maintainers.thiagokokada ];
-    mainProgram = if withNgSuffix then "nixos-rebuild-ng" else "nixos-rebuild";
+    mainProgram = executable;
   };
 }
diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py b/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py
index 86a6af876de3..982fd070be61 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py
@@ -73,32 +73,101 @@ def get_parser() -> tuple[argparse.ArgumentParser, dict[str, argparse.ArgumentPa
         add_help=False,
         allow_abbrev=False,
     )
-    main_parser.add_argument("--help", "-h", action="store_true")
-    main_parser.add_argument("--file", "-f")
-    main_parser.add_argument("--attr", "-A")
-    main_parser.add_argument("--flake", nargs="?", const=True)
-    main_parser.add_argument("--no-flake", dest="flake", action="store_false")
-    main_parser.add_argument("--install-bootloader", action="store_true")
-    main_parser.add_argument("--install-grub", action="store_true")  # deprecated
-    main_parser.add_argument("--profile-name", "-p", default="system")
-    main_parser.add_argument("--specialisation", "-c")
-    main_parser.add_argument("--rollback", action="store_true")
-    main_parser.add_argument("--upgrade", action="store_true")
-    main_parser.add_argument("--upgrade-all", action="store_true")
-    main_parser.add_argument("--json", action="store_true")
-    main_parser.add_argument("--sudo", action="store_true")
-    main_parser.add_argument("--ask-sudo-password", action="store_true")
-    main_parser.add_argument("--use-remote-sudo", action="store_true")  # deprecated
-    main_parser.add_argument("--no-ssh-tty", action="store_true")  # deprecated
-    main_parser.add_argument("--fast", action="store_true")
-    main_parser.add_argument("--build-host")
-    main_parser.add_argument("--target-host")
-    main_parser.add_argument("--no-build-nix", action="store_true")  # deprecated
+    main_parser.add_argument("--help", "-h", action="store_true", help="Show manpage")
+    main_parser.add_argument(
+        "--file", "-f", help="Enable and build the NixOS system from the specified file"
+    )
+    main_parser.add_argument(
+        "--attr",
+        "-A",
+        help="Enable and build the NixOS system from nix file and use the "
+        + "specified attribute path from file specified by the --file option",
+    )
+    main_parser.add_argument(
+        "--flake",
+        nargs="?",
+        const=True,
+        help="Build the NixOS system from the specified flake",
+    )
+    main_parser.add_argument(
+        "--no-flake",
+        dest="flake",
+        action="store_false",
+        help="Do not imply --flake if /etc/nixos/flake.nix exists",
+    )
+    main_parser.add_argument(
+        "--install-bootloader",
+        action="store_true",
+        help="Causes the boot loader to be (re)installed on the device specified "
+        + "by the relevant configuration options",
+    )
+    main_parser.add_argument(
+        "--install-grub",
+        action="store_true",
+        help="Deprecated, use '--install-bootloader' instead",
+    )
+    main_parser.add_argument(
+        "--profile-name",
+        "-p",
+        default="system",
+        help="Use nix profile /nix/var/nix/profiles/system-profiles/<profile-name>",
+    )
+    main_parser.add_argument(
+        "--specialisation", "-c", help="Activates given specialisation"
+    )
+    main_parser.add_argument(
+        "--rollback",
+        action="store_true",
+        help="Roll back to the previous configuration",
+    )
+    main_parser.add_argument(
+        "--upgrade",
+        action="store_true",
+        help="Update the root user's channel named 'nixos' before rebuilding "
+        + "the system and channels which have a file named '.update-on-nixos-rebuild'",
+    )
+    main_parser.add_argument(
+        "--upgrade-all",
+        action="store_true",
+        help="Same as --upgrade, but updates all root user's channels",
+    )
+    main_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="JSON output, only implemented for 'list-generations' right now",
+    )
+    main_parser.add_argument(
+        "--ask-sudo-password",
+        action="store_true",
+        help="Asks for sudo password for remote activation, implies --sudo",
+    )
+    main_parser.add_argument(
+        "--sudo", action="store_true", help="Prefixes activation commands with sudo"
+    )
+    main_parser.add_argument(
+        "--use-remote-sudo",
+        action="store_true",
+        help="Deprecated, use '--sudo' instead",
+    )
+    main_parser.add_argument("--no-ssh-tty", action="store_true", help="Deprecated")
+    main_parser.add_argument(
+        "--fast",
+        action="store_true",
+        help="Skip possibly expensive operations",
+    )
+    main_parser.add_argument("--build-host", help="Specifies host to perform the build")
+    main_parser.add_argument("--target-host", help="Specifies the NixOS target host")
+    main_parser.add_argument("--no-build-nix", action="store_true", help="Deprecated")
     main_parser.add_argument("action", choices=Action.values(), nargs="?")
 
     return main_parser, sub_parsers
 
 
+# For shtab to generate completions
+def get_main_parser() -> argparse.ArgumentParser:
+    return get_parser()[0]
+
+
 def parse_args(
     argv: list[str],
 ) -> tuple[argparse.Namespace, dict[str, argparse.Namespace]]:

From 68a1082234b117eed774134d77cb68752a3006ec Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Wed, 4 Dec 2024 12:52:02 +0000
Subject: [PATCH 03/11] nixos-rebuild-ng: add proper manpage using scd format

---
 pkgs/by-name/ni/nixos-rebuild-ng/README.md    |   2 +-
 .../ni/nixos-rebuild-ng/nixos-rebuild.8.scd   | 335 ++++++++++++++++++
 pkgs/by-name/ni/nixos-rebuild-ng/package.nix  |  18 +-
 .../src/nixos_rebuild/__init__.py             |   8 +-
 4 files changed, 355 insertions(+), 8 deletions(-)
 create mode 100644 pkgs/by-name/ni/nixos-rebuild-ng/nixos-rebuild.8.scd

diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/README.md b/pkgs/by-name/ni/nixos-rebuild-ng/README.md
index 88cd9a82f37a..41bfb43ba3c9 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/README.md
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/README.md
@@ -107,7 +107,7 @@ ruff format .
 - [ ] Port `nixos-rebuild.passthru.tests`
 - [ ] Change module system to allow easier opt-in, like
   `system.switch.enableNg` for `switch-to-configuration-ng`
-- [ ] Improve documentation
+- [x] Improve documentation
 - [x] `nixos-rebuild repl`
 - [x] Generate tab completion via [`shtab`](https://docs.iterative.ai/shtab/)
 - [x] Reduce build closure
diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/nixos-rebuild.8.scd b/pkgs/by-name/ni/nixos-rebuild-ng/nixos-rebuild.8.scd
new file mode 100644
index 000000000000..cacc72e64217
--- /dev/null
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/nixos-rebuild.8.scd
@@ -0,0 +1,335 @@
+nixos-rebuild-ng(8) ["nixpkgs"]
+; quick summary:
+; # new section
+; comments starts with ;
+; - this is a list
+; 	- sub-list
+; - *bold*: _underline_, force a line break++
+; - [tables], \[ can be used to force an actual [
+; . numbered list
+; please configure your editor to use hard tabs
+; see `man 5 scdoc` for more information about syntax
+; or https://man.archlinux.org/man/scdoc.5.en
+
+# NAME
+
+nixos-rebuild - reconfigure a NixOS machine
+
+# SYNOPSIS
+
+_nixos-rebuild_ \[--verbose] [--max-jobs MAX_JOBS] [--cores CORES] [--log-format LOG_FORMAT] [--keep-going] [--keep-failed] [--fallback] [--repair] [--option OPTION OPTION] [--builders BUILDERS]++
+	\[--include INCLUDE] [--quiet] [--print-build-logs] [--show-trace] [--accept-flake-config] [--refresh] [--impure] [--offline] [--no-net] [--recreate-lock-file]++
+	\[--no-update-lock-file] [--no-write-lock-file] [--no-registries] [--commit-lock-file] [--update-input UPDATE_INPUT] [--override-input OVERRIDE_INPUT OVERRIDE_INPUT]++
+	\[--no-build-output] [--use-substitutes] [--help] [--file FILE] [--attr ATTR] [--flake [FLAKE]] [--no-flake] [--install-bootloader] [--profile-name PROFILE_NAME]++
+	\[--specialisation SPECIALISATION] [--rollback] [--upgrade] [--upgrade-all] [--json] [--ask-sudo-password] [--sudo] [--fast]++
+	\[--build-host BUILD_HOST] [--target-host TARGET_HOST]++
+	\[{switch,boot,test,build,edit,repl,dry-build,dry-run,dry-activate,build-vm,build-vm-with-bootloader,list-generations}]
+
+# DESCRIPTION
+
+This command updates the system so that it corresponds to the configuration
+specified in /etc/nixos/configuration.nix, /etc/nixos/flake.nix or the file and
+attribute specified by the *--file* and/or *--attr* options. Thus, every
+time you modify the configuration or any other NixOS module, you must run
+*nixos-rebuild* to make the changes take effect. It builds the new system in
+/nix/store, runs its activation script, and stop and (re)starts any system
+services if needed. Please note that user services need to be started manually
+as they aren't detected by the activation script at the moment.
+
+This command has one required argument, which specifies the desired operation.
+It must be one of the following:
+
+*switch*
+	Build and activate the new configuration, and make it the boot default.
+	That is, the configuration is added to the GRUB boot menu as the
+	default menu entry, so that subsequent reboots will boot the system
+	into the new configuration. Previous configurations activated with
+	nixos-rebuild switch or nixos-rebuild boot remain available in the GRUB
+	menu.
+
+	Note that if you are using specializations, running just nixos-rebuild
+	switch will switch you back to the unspecialized, base system — in that
+	case, you might want to use this instead:
+
+		$ nixos-rebuild switch --specialisation your-specialisation-name
+
+	This command will build all specialisations and make them bootable
+	just like regular nixos-rebuild switch does — the only thing different
+	is that it will switch to given specialisation instead of the base
+	system; it can be also used to switch from the base system into a
+	specialised one, or to switch between specialisations.
+
+*boot*
+	Build the new configuration and make it the boot default (as with
+	*nixos-rebuild switch*), but do not activate it. That is, the system
+	continues to run the previous configuration until the next reboot.
+
+*test*
+	Build and activate the new configuration, but do not add it to the GRUB
+	boot menu. Thus, if you reboot the system (or if it crashes), you will
+	automatically revert to the default configuration (i.e. the
+	configuration resulting from the last call to *nixos-rebuild switch* or
+	*nixos-rebuild boot*).
+
+	Note that if you are using specialisations, running just nixos-rebuild
+	test will activate the unspecialised, base system — in that case, you
+	might want to use this instead:
+
+		$ nixos-rebuild test --specialisation your-specialisation-name
+
+	This command can be also used to switch from the base system into a
+	specialised one, or to switch between specialisations.
+
+*build*
+	Build the new configuration, but neither activate it nor add it to the
+	GRUB boot menu. It leaves a symlink named result in the current
+	directory, which points to the output of the top-level “system”
+	derivation. This is essentially the same as doing
+
+		$ nix-build /path/to/nixpkgs/nixos -A system
+
+	Note that you do not need to be root to run *nixos-rebuild build*.
+
+*dry-build*
+	Show what store paths would be built or downloaded by any of the
+	operations above, but otherwise do nothing.
+
+*dry-activate*
+	Build the new configuration, but instead of activating it, show what
+	changes would be performed by the activation (i.e. by *nixos-rebuild*
+	test). For instance, this command will print which systemd units would be
+	restarted. The list of changes is not guaranteed to be complete.
+
+*edit*
+	Opens _configuration.nix_ in the default editor.
+
+*repl*
+	Opens the configuration in *nix repl*.
+
+*build-vm*
+	Build a script that starts a NixOS virtual machine with the desired
+	configuration. It leaves a symlink _result_ in the current directory that
+	points (under ‘result/bin/run-_hostname_-vm’) at the script that starts
+	the VM. Thus, to test a NixOS configuration in a virtual machine, you
+	should do the following:
+
+		$ nixos-rebuild build-vm && ./result/bin/run-\*-vm
+
+	The VM is implemented using the ‘qemu’ package. For best performance, you
+	should load the ‘kvm-intel’ or ‘kvm-amd’ kernel modules to get hardware
+	virtualisation.
+
+	The VM mounts the Nix store of the host through the 9P file system. The
+	host Nix store is read-only, so Nix commands that modify the Nix store
+	will not work in the VM. This includes commands such as *nixos-rebuild*;
+	to change the VM’s configuration, you must halt the VM and re-run the
+	commands above.
+
+	The VM has its own ext3 root file system, which is automatically created
+	when the VM is first started, and is persistent across reboots of the VM.
+	It is stored in ‘./_hostname_.qcow2’.
+
+*build-vm-with-bootloader*
+	Like build-vm, but boots using the regular boot loader of your
+	configuration (e.g. GRUB 1 or 2), rather than booting directly into the
+	kernel and initial ramdisk of the system. This al‐ lows you to test
+	whether the boot loader works correctly. However, it does not guarantee
+	that your NixOS configuration will boot successfully on the host
+	hardware (i.e., after running *nixos-rebuild switch*), because the
+	hardware and boot loader configuration in the VM are different. The boot
+	loader is installed on an automatically generated virtual disk
+	containing a /boot partition.
+
+*list-generations [--json]*
+	List the available generations in a similar manner to the boot loader
+	menu. It shows the generation number, build date and time, NixOS
+	version, kernel version and the configuration revi‐ sion. There is also
+	a json version of output available.
+
+# OPTIONS
+
+*--upgrade, --upgrade-all*
+	Update the root user's channel named ‘nixos’ before rebuilding the
+	system.
+
+	In addition to the ‘nixos’ channel, the root user's channels which have
+	a file named ‘.update-on-nixos-rebuild’ in their base directory will
+	also be updated.
+
+	Passing *--upgrade-all* updates all of the root user's channels.
+
+*--install-bootloader*
+	Causes the boot loader to be (re)installed on the device specified by
+	the relevant configuration options.
+
+*--fast*
+	Normally, *nixos-rebuild* first finds and builds itself from the
+	_config.system.build.nixos-rebuild_ attribute from the current user
+	channel or flake and exec into it. This allows *nixos-rebuild* to run
+	with the latest bug-fixes. This option disables it, using the current
+	*nixos-rebuild* instance instead.
+
+*--rollback*
+	Instead of building a new configuration as specified by
+	_/etc/nixos/configuration.nix_, roll back to the previous configuration.
+	(The previous configuration is defined as the one before the “current”
+	generation of the Nix profile _/nix/var/nix/profiles/system_.)
+
+*--builders* _builder-spec_
+	Allow ad-hoc remote builders for building the new system. This requires
+	the user executing *nixos-rebuild* (usually root) to be configured as a
+	trusted user in the Nix daemon. This can be achieved by using the
+	_nix.settings.trusted-users_ NixOS option. Examples values for that
+	option are described in the “Remote builds” chapter in the Nix manual,
+	(i.e. ‘--builders "ssh://bigbrother x86_64-linux"‘). By specifying an
+	empty string existing builders specified in /etc/nix/machines can be
+	ignored: ‘--builders ""‘ for example when they are not reachable due to
+	network connectivity.
+
+*--profile-name* _name_, *-p* _name_
+	Instead of using the Nix profile _/nix/var/nix/profiles/system_ to keep
+	track of the current and previous system configurations, use
+	_/nix/var/nix/profiles/system-profiles/name_. When you use GRUB 2, for
+	every system profile created with this flag, NixOS will create a submenu
+	named “NixOS - Profile _name_“ in GRUB's boot menu, containing the
+	current and previous configurations of this profile.
+
+	For instance, if you want to test a configuration file named _test.nix_
+	without affecting the default system profile, you would do:
+
+		$ nixos-rebuild switch -p test -I nixos-config=./test.nix
+
+	The new configuration will appear in the GRUB 2 submenu “NixOS - Profile
+	‘test’“.
+
+*--specialisation* _name_, *-c* _name_
+	Activates given specialisation; when not specified, switching and testing
+	will activate the base, unspecialised system.
+
+*--build-host* _host_
+	Instead of building the new configuration locally, use the specified host
+	to perform the build. The host needs to be accessible with ssh, and must
+	be able to perform Nix builds. If the option *--target-host* is not set,
+	the build will be copied back to the local machine when done.
+
+	You can include a remote user name in the host name (_user@host_). You
+	can also set ssh options by defining the NIX_SSHOPTS environment
+	variable.
+
+*--target-host* _host_
+	Specifies the NixOS target host. By setting this to something other than
+	an empty string, the system activation will happen on the remote host
+	instead of the local machine. The remote host needs to be accessible
+	over *ssh*, and for the commands *switch*, *boot* and *test* you need
+	root access.
+
+	If *--build-host* is not explicitly specified or empty, building will
+	take place locally.
+
+	You can include a remote user name in the host name (_user@host_). You
+	can also set ssh options by defining the NIX_SSHOPTS environment
+	variable.
+
+	Note that *nixos-rebuild* honors the _nixpkgs.crossSystem_ setting of
+	the given configuration but disregards the true architecture of the
+	target host. Hence the _nixpkgs.crossSystem_ setting has to match the
+	target platform or else activation will fail.
+
+*--use-substitutes*
+	When set, nixos-rebuild will add *--use-substitutes* to each invocation
+	of _nix-copy-closure_/_nix copy_. This will only affect the behavior of
+	nixos-rebuild if *--target-host* or *--build-host* is also set. This is
+	useful when the target-host connection to cache.nixos.org is faster than
+	the connection between hosts.
+
+*--sudo*
+	When set, *nixos-rebuild* prefixes activation commands with sudo.
+	Setting this option allows deploying as a non-root user.
+
+*--ask-sudo-password*
+	When set, *nixos-rebuild* will ask for sudo password for remote
+	activation (i.e.: on *--target-host*) at the start of the build process.
+
+*--file* _path_, *-f* _path_
+	Enable and build the NixOS system from the specified file. The file must
+	evaluate to an attribute set, and it must contain a valid NixOS
+	configuration at attribute _attrPath_. This is useful for building a
+	NixOS system from a nix file that is not a flake or a NixOS
+	configuration module. Attribute set a with valid NixOS configuration can
+	be made using _nixos_ function in nixpkgs or importing and calling
+	nixos/lib/eval-config.nix from nixpkgs. If specified without *--attr*
+	option, builds the configuration from the top-level attribute of the
+	file.
+
+*--attr* _attrPath_, *-A* _attrPath_
+	Enable and build the NixOS system from nix file and use the specified
+	attribute path from file specified by the *--file* option. If specified
+	without *--file* option, uses _default.nix_ in current directory.
+
+*--flake* _flake-uri[#name]_
+	Build the NixOS system from the specified flake. It defaults to the
+	directory containing the target of the symlink _/etc/nixos/flake.nix_,
+	if it exists. The flake must contain an output named
+	‘nixosConfigurations.name’. If name is omitted, it default to the
+	current host name.
+
+*--no-flake*
+	Do not imply *--flake* if _/etc/nixos/flake.nix exists_. With this
+	option, it is possible to build non-flake NixOS configurations even if
+	the current NixOS systems uses flakes.
+
+In addition, *nixos-rebuild* accepts following options from nix commands that
+the tool calls:
+
+Flake-related options:
+
+*--accept-flake-config*, *--refresh*, *--impure*, *--offline*, *--no-net*
+*--recreate-lock-file*, *--no-update-lock-file*, *--no-write-lock-file*,
+*--no-registries*, *--commit-lock-file*, *--update-input* _input-path_,
+*--override-input* _input-path_ _flake-url_
+
+Builder options:
+
+*--verbose,*  *-v*,  *--quiet*,  *--log-format*,  *--no-build-output*, *-Q*,
+*--max-jobs*, *-j*, *--cores*, *--keep-going*, *-k*, *--keep-failed*, *-K*,
+*--fallback*, *--incllude*, *-I*, *--option*, *--repair*, *--builders*,
+*--print-build-logs*, *-L*, *--show-trace*
+
+See the Nix manual, *nix flake lock --help* or *nix-build --help* for details.
+
+# ENVIRONMENT
+
+NIXOS_CONFIG
+	Path to the main NixOS configuration module. Defaults to
+	_/etc/nixos/configuration.nix_.
+
+NIX_PATH
+	A colon-separated list of directories used to look up Nix expressions
+	enclosed in angle brackets (e.g. <nixpkgs>). Example:
+
+		nixpkgs=./my-nixpkgs
+
+NIX_SSHOPTS
+	Additional options to be passed to ssh on the command line.
+
+# FILES
+
+/etc/nixos/flake.nix
+	If this file exists, then *nixos-rebuild* will use it as if the
+	*--flake* option was given. This file may be a symlink to a
+	flake.nix in an actual flake; thus _/etc/nixos_ need not be a
+	flake.
+
+/run/current-system
+	A symlink to the currently active system configuration in the
+	Nix store.
+
+/nix/var/nix/profiles/system
+	The Nix profile that contains the current and previous system
+	configurations. Used to generate the GRUB boot menu.
+
+# AUTHORS
+
+Nixpkgs/NixOS contributors
+
+; vim: set noet
diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/package.nix b/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
index 1e222d08e5cd..ff8b9f6eef8e 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
@@ -4,10 +4,11 @@
   installShellFiles,
   mkShell,
   nix,
-  nixos-rebuild,
   python3,
   python3Packages,
   runCommand,
+  scdoc,
+  withManPage ? (stdenv.buildPlatform.canExecute stdenv.hostPlatform),
   withShellCompletion ? (stdenv.buildPlatform.canExecute stdenv.hostPlatform),
   withNgSuffix ? true,
 }:
@@ -29,9 +30,12 @@ python3Packages.buildPythonApplication rec {
   ];
 
   nativeBuildInputs =
-    [
+    lib.optionals (withManPage || withShellCompletion) [
       installShellFiles
     ]
+    ++ lib.optionals withManPage [
+      scdoc
+    ]
     ++ lib.optionals withShellCompletion [
       python3Packages.shtab
     ];
@@ -48,9 +52,15 @@ python3Packages.buildPythonApplication rec {
     nix
   ];
 
+  postPatch = ''
+    substituteInPlace nixos_rebuild/__init__.py \
+      --subst-var-by executable ${executable}
+  '';
+
   postInstall =
-    ''
-      installManPage ${nixos-rebuild}/share/man/man8/nixos-rebuild.8
+    lib.optionalString withManPage ''
+      scdoc < ${./nixos-rebuild.8.scd} > ${executable}.8
+      installManPage ${executable}.8
     ''
     + lib.optionalString withShellCompletion ''
       installShellCompletion --cmd ${executable} \
diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py b/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py
index 982fd070be61..d1a6ca84c7ca 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py
@@ -156,7 +156,9 @@ def get_parser() -> tuple[argparse.ArgumentParser, dict[str, argparse.ArgumentPa
         help="Skip possibly expensive operations",
     )
     main_parser.add_argument("--build-host", help="Specifies host to perform the build")
-    main_parser.add_argument("--target-host", help="Specifies the NixOS target host")
+    main_parser.add_argument(
+        "--target-host", help="Specifies host to activate the configuration"
+    )
     main_parser.add_argument("--no-build-nix", action="store_true", help="Deprecated")
     main_parser.add_argument("action", choices=Action.values(), nargs="?")
 
@@ -193,7 +195,7 @@ def parse_args(
         args.sudo = True
 
     if args.help or args.action is None:
-        r = run(["man", "8", "nixos-rebuild"], check=False)
+        r = run(["man", "8", "@executable@"], check=False)
         parser.exit(r.returncode)
 
     # TODO: use deprecated=True in Python >=3.13
@@ -262,7 +264,7 @@ def reexec(
         logger.warning("could not find a newer version of nixos-rebuild")
 
     if drv:
-        new = drv / "bin/nixos-rebuild-ng"
+        new = drv / "bin/@executable@"
         current = Path(argv[0])
         # Disable re-exec during development
         if current.name != "__main__.py" and new != current:

From a987599ac134668cdcf3664e4433d7c370b4e627 Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Thu, 5 Dec 2024 10:25:43 +0000
Subject: [PATCH 04/11] nixos-rebuild-ng: simplify build options

---
 pkgs/by-name/ni/nixos-rebuild-ng/package.nix  | 41 ++++++++-----------
 .../ni/nixos-rebuild-ng/src/pyproject.toml    |  2 +-
 2 files changed, 17 insertions(+), 26 deletions(-)

diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/package.nix b/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
index ff8b9f6eef8e..51449ea3289a 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
@@ -8,9 +8,8 @@
   python3Packages,
   runCommand,
   scdoc,
-  withManPage ? (stdenv.buildPlatform.canExecute stdenv.hostPlatform),
-  withShellCompletion ? (stdenv.buildPlatform.canExecute stdenv.hostPlatform),
   withNgSuffix ? true,
+  withShellFiles ? (stdenv.buildPlatform.canExecute stdenv.hostPlatform),
 }:
 let
   executable = if withNgSuffix then "nixos-rebuild-ng" else "nixos-rebuild";
@@ -29,16 +28,11 @@ python3Packages.buildPythonApplication rec {
     tabulate
   ];
 
-  nativeBuildInputs =
-    lib.optionals (withManPage || withShellCompletion) [
-      installShellFiles
-    ]
-    ++ lib.optionals withManPage [
-      scdoc
-    ]
-    ++ lib.optionals withShellCompletion [
-      python3Packages.shtab
-    ];
+  nativeBuildInputs = lib.optionals withShellFiles [
+    installShellFiles
+    python3Packages.shtab
+    scdoc
+  ];
 
   propagatedBuildInputs = [
     # Make sure that we use the Nix package we depend on, not something
@@ -55,21 +49,18 @@ python3Packages.buildPythonApplication rec {
   postPatch = ''
     substituteInPlace nixos_rebuild/__init__.py \
       --subst-var-by executable ${executable}
+    substituteInPlace pyproject.toml \
+      --subst-var-by executable ${executable}
   '';
 
-  postInstall =
-    lib.optionalString withManPage ''
-      scdoc < ${./nixos-rebuild.8.scd} > ${executable}.8
-      installManPage ${executable}.8
-    ''
-    + lib.optionalString withShellCompletion ''
-      installShellCompletion --cmd ${executable} \
-        --bash <(shtab --shell bash nixos_rebuild.get_main_parser) \
-        --zsh <(shtab --shell zsh nixos_rebuild.get_main_parser)
-    ''
-    + lib.optionalString withNgSuffix ''
-      mv $out/bin/nixos-rebuild $out/bin/${executable}
-    '';
+  postInstall = lib.optionalString withShellFiles ''
+    scdoc < ${./nixos-rebuild.8.scd} > ${executable}.8
+    installManPage ${executable}.8
+
+    installShellCompletion --cmd ${executable} \
+      --bash <(shtab --shell bash nixos_rebuild.get_main_parser) \
+      --zsh <(shtab --shell zsh nixos_rebuild.get_main_parser)
+  '';
 
   nativeCheckInputs = with python3Packages; [
     pytestCheckHook
diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml b/pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml
index d773e8888923..e640188d363a 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml
@@ -7,7 +7,7 @@ name = "nixos-rebuild-ng"
 version = "0.0.0"
 
 [project.scripts]
-nixos-rebuild = "nixos_rebuild:main"
+@executable@ = "nixos_rebuild:main"
 
 [tool.setuptools.package-data]
 nixos_rebuild = ["*.template.nix"]

From da566994eac60d23e9be0c9dc3116722e9f0a5a8 Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Thu, 5 Dec 2024 12:56:59 +0000
Subject: [PATCH 05/11] nixos-rebuild-ng: enable shell files by default

---
 pkgs/by-name/ni/nixos-rebuild-ng/package.nix | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/package.nix b/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
index 51449ea3289a..4df882fc176a 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
@@ -1,6 +1,5 @@
 {
   lib,
-  stdenv,
   installShellFiles,
   mkShell,
   nix,
@@ -9,7 +8,7 @@
   runCommand,
   scdoc,
   withNgSuffix ? true,
-  withShellFiles ? (stdenv.buildPlatform.canExecute stdenv.hostPlatform),
+  withShellFiles ? true,
 }:
 let
   executable = if withNgSuffix then "nixos-rebuild-ng" else "nixos-rebuild";

From bd200697e9d95ae0c0dacedaa4813ccde2e1d8db Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Fri, 6 Dec 2024 10:56:00 +0000
Subject: [PATCH 06/11] nixos-rebuild-ng: show help when manpage is disabled

---
 pkgs/by-name/ni/nixos-rebuild-ng/package.nix         |  4 +++-
 .../nixos-rebuild-ng/src/nixos_rebuild/__init__.py   | 12 ++++++++----
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/package.nix b/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
index 4df882fc176a..e5a4796136de 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
@@ -47,7 +47,9 @@ python3Packages.buildPythonApplication rec {
 
   postPatch = ''
     substituteInPlace nixos_rebuild/__init__.py \
-      --subst-var-by executable ${executable}
+      --subst-var-by executable ${executable} \
+      --subst-var-by withShellFiles ${lib.boolToString withShellFiles}
+
     substituteInPlace pyproject.toml \
       --subst-var-by executable ${executable}
   '';
diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py b/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py
index d1a6ca84c7ca..bdec4797e5c3 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/__init__.py
@@ -180,6 +180,14 @@ def parse_args(
         for group, parser in sub_parsers.items()
     }
 
+    if args.help or args.action is None:
+        if "@withShellFiles@" == "true":
+            r = run(["man", "8", "@executable@"], check=False)
+            parser.exit(r.returncode)
+        else:
+            parser.print_help()
+            parser.exit()
+
     def parser_warn(msg: str) -> None:
         print(f"{parser.prog}: warning: {msg}", file=sys.stderr)
 
@@ -194,10 +202,6 @@ def parse_args(
     if args.ask_sudo_password:
         args.sudo = True
 
-    if args.help or args.action is None:
-        r = run(["man", "8", "@executable@"], check=False)
-        parser.exit(r.returncode)
-
     # TODO: use deprecated=True in Python >=3.13
     if args.install_grub:
         parser_warn("--install-grub deprecated, use --install-bootloader instead")

From 1fe9bfe98202e09bb83cba864bc231110954faa5 Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Sat, 7 Dec 2024 11:31:45 +0000
Subject: [PATCH 07/11] nixos-rebuild-ng: rename manual to nixos-rebuild

---
 pkgs/by-name/ni/nixos-rebuild-ng/nixos-rebuild.8.scd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/nixos-rebuild.8.scd b/pkgs/by-name/ni/nixos-rebuild-ng/nixos-rebuild.8.scd
index cacc72e64217..25581f91c0f3 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/nixos-rebuild.8.scd
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/nixos-rebuild.8.scd
@@ -1,4 +1,4 @@
-nixos-rebuild-ng(8) ["nixpkgs"]
+nixos-rebuild(8) ["nixpkgs"]
 ; quick summary:
 ; # new section
 ; comments starts with ;

From 556a52ac2718ba58bf27ed1ea89ebfd8b2508865 Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Sat, 7 Dec 2024 11:38:03 +0000
Subject: [PATCH 08/11] nixos-rebuild-ng: fix linter failures

---
 pkgs/by-name/ni/nixos-rebuild-ng/package.nix        | 2 +-
 pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/package.nix b/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
index e5a4796136de..e64d4208c73e 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/package.nix
@@ -51,7 +51,7 @@ python3Packages.buildPythonApplication rec {
       --subst-var-by withShellFiles ${lib.boolToString withShellFiles}
 
     substituteInPlace pyproject.toml \
-      --subst-var-by executable ${executable}
+      --replace-fail nixos-rebuild ${executable}
   '';
 
   postInstall = lib.optionalString withShellFiles ''
diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml b/pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml
index e640188d363a..1ea72b4b6ebb 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml
@@ -3,11 +3,11 @@ requires = ["setuptools"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "nixos-rebuild-ng"
+name = "nixos-rebuild"
 version = "0.0.0"
 
 [project.scripts]
-@executable@ = "nixos_rebuild:main"
+nixos-rebuild = "nixos_rebuild:main"
 
 [tool.setuptools.package-data]
 nixos_rebuild = ["*.template.nix"]

From af4fad1f21ee3f7d9d5ed61d1f2393a1d37b134c Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Sun, 8 Dec 2024 02:37:40 +0000
Subject: [PATCH 09/11] nixos-rebuild-ng: remove --raw from nix-instantiate

---
 pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/nix.py | 1 -
 pkgs/by-name/ni/nixos-rebuild-ng/src/tests/test_nix.py    | 1 -
 2 files changed, 2 deletions(-)

diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/nix.py b/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/nix.py
index 7c9338b3ef92..e2e1cea2327d 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/nix.py
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/nix.py
@@ -77,7 +77,6 @@ def remote_build(
     r = run_wrapper(
         [
             "nix-instantiate",
-            "--raw",
             build_attr.path,
             "--attr",
             build_attr.to_attr(attr),
diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/src/tests/test_nix.py b/pkgs/by-name/ni/nixos-rebuild-ng/src/tests/test_nix.py
index 6a34f98bd066..928c0e8616a8 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/src/tests/test_nix.py
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/src/tests/test_nix.py
@@ -94,7 +94,6 @@ def test_remote_build(mock_run: Any, monkeypatch: Any) -> None:
             call(
                 [
                     "nix-instantiate",
-                    "--raw",
                     "<nixpkgs/nixos>",
                     "--attr",
                     "preAttr.config.system.build.toplevel",

From 69d9c3529d13ad7fbc776207356cfc5c0e62128b Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Sun, 8 Dec 2024 21:11:11 +0000
Subject: [PATCH 10/11] nixos-rebuild-ng: fix repl command

---
 pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml b/pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml
index 1ea72b4b6ebb..9d3f92f5471e 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/src/pyproject.toml
@@ -10,7 +10,7 @@ version = "0.0.0"
 nixos-rebuild = "nixos_rebuild:main"
 
 [tool.setuptools.package-data]
-nixos_rebuild = ["*.template.nix"]
+nixos_rebuild = ["*.nix.template"]
 
 [tool.mypy]
 # `--strict` config, but explicit options to avoid breaking build when mypy is

From b928ad0093c9b6c1c2081162653092fc4a73839b Mon Sep 17 00:00:00 2001
From: Thiago Kenji Okada <thiagokokada@gmail.com>
Date: Sun, 8 Dec 2024 21:15:23 +0000
Subject: [PATCH 11/11] nixos-rebuild-ng: only show the error message if the
 user forget to use --ask-sudo-password flag

---
 pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/process.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/process.py b/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/process.py
index 07d01c6f121b..10666b47d657 100644
--- a/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/process.py
+++ b/pkgs/by-name/ni/nixos-rebuild-ng/src/nixos_rebuild/process.py
@@ -144,7 +144,7 @@ def run_wrapper(
 
         return r
     except subprocess.CalledProcessError:
-        if sudo and remote:
+        if sudo and remote and remote.sudo_password is None:
             logger.error(
                 "while running command with remote sudo, did you forget to use "
                 + "--ask-sudo-password?"