feat: show detailed error messages

docs/best-practices/debugging.md

@@ -1,5 +1,13 @@
 # Debugging Derivations and Nix Expressions
 
+## Show detailed error messages
+
+You can always try to add `--show-trace -L` to the `nixos-rebuild` command to get the detailed error message if you encounter any errors during the deployment. e.g.
+
+```bash
+sudo nixos-rebuild switch --flake .#myhost --show-trace -L
+```
+
 ## Debugging with `nix repl`
 
 > NOTE: If you have disabled `NIX_PATH`, you won't be able to use syntax like `<nixpkgs>`. Instead, you should use `nix repl -f flake:nixpkgs` to load nixpkgs.

docs/nixos-with-flakes/get-started-with-nixos.md

@@ -62,6 +62,8 @@ In this configuration, we declare our intention to enable the openssh service, a
 
 To deploy the modified configuration, run `sudo nixos-rebuild switch`. This command will apply the changes, generate a new system environment, and set it as the default. You can now log in to the system using SSH with the configured SSH keys.
 
+> You can always try to add `--show-trace -L` to the `nixos-rebuild` command to get the detailed error message if you encounter any errors during the deployment.
+
 Remember that any reproducible changes to the system can be made by modifying the `/etc/nixos/configuration.nix` file and deploying the changes with `sudo nixos-rebuild switch`.
 
 To find configuration options and documentation:

docs/nixos-with-flakes/nixos-with-flakes-enabled.md

@@ -248,6 +248,8 @@ After that, you can start the Helix editor by running the `hx` command.
 
 > If your system's hostname is not `nixos-test`, you need to modify the name of `nixosConfigurations` in `flake.nix`, or use `--flake /etc/nixos#nixos-test` to specify the configuration name.
 
+> You can always try to add `--show-trace -L` to the `nixos-rebuild` command to get the detailed error message if you encounter any errors during the deployment.
+
 Furthermore, if you merely want to experiment with the latest version of Helix before deciding whether to install it system-wide, there's a simpler way – just a single command:
 
 > Similarly, if you wish to use the latest version, compiling from source is usually unavoidable and may take some time.

docs/nixos-with-flakes/other-useful-tips.md

@@ -1,5 +1,14 @@
 # Other Useful Tips
 
+## Show detailed error messages
+
+You can always try to add `--show-trace -L` to the `nixos-rebuild` command to get the detailed error message if you encounter any errors during the deployment. e.g.
+
+```bash
+cd /etc/nixos
+sudo nixos-rebuild switch --flake .#myhost --show-trace -L
+```
+
 ## Managing the Configuration with Git
 
 NixOS configuration, being a set of text files, is well-suited for version control with Git. This allows easy rollback to a previous version in case of issues.
@@ -87,7 +96,7 @@ The following configuration can be added to your NixOS configuration to help red
     automatic = true;
     dates = "weekly";
     options = "--delete-older-than 1w";
- };
+  };
 
   # Optimize storage
   # You can also manually optimize the store via:

docs/zh/best-practices/debugging.md

@@ -1,5 +1,13 @@
 # 调试 Derivation 跟 Nix 表达式
 
+## 查看详细错误信息
+
+如果你在部署配置时遇到了任何错误，都可以尝试在 `nixos-rebuild` 命令后面添加 `--show-trace -L` 参数来获取详细的错误信息。举例如下：
+
+```bash
+sudo nixos-rebuild switch --flake .#myhost --show-trace -L
+```
+
 ## 通过 `nix repl` 查看源码、调试配置
 
 > 注：如果你禁用了 `NIX_PATH`，那么 `<nixpkgs>` 这样的语法将无法使用，你需要改用 `nix repl -f flake:nixpkgs` 来加载 nixpkgs。

docs/zh/nixos-with-flakes/get-started-with-nixos.md

@@ -67,6 +67,8 @@ NixOS 的系统配置路径为 `/etc/nixos/configuration.nix`，它包含系统
 
 现在运行 `sudo nixos-rebuild switch` 部署修改后的配置，之后就可以通过 ssh 密钥远程登录到我的这台主机了。
 
+> 如果你在部署配置时遇到了任何错误，都可以尝试在 `nixos-rebuild` 命令后面添加 `--show-trace -L` 参数来获取详细的错误信息。举例如下：
+
 这就是 NixOS 默认的声明式系统配置，要对系统做任何可复现的变更，都只需要修改 `/etc/nixos/configuration.nix` 文件，然后运行 `sudo nixos-rebuild switch` 部署变更即可。
 
 `/etc/nixos/configuration.nix` 的所有配置项，可以在这几个地方查到：

docs/zh/nixos-with-flakes/nixos-with-flakes-enabled.md

@@ -229,6 +229,8 @@ cat flake.nix
 
 > 如果你的系统 Hostname 不是 `nixos-test`，你需要在 `flake.nix` 中修改 `nixosConfigurations` 的名称，或者使用 `--flake /etc/nixos#nixos-test` 来指定配置名称。
 
+> 如果你在部署配置时遇到了任何错误，都可以尝试在 `nixos-rebuild` 命令后面添加 `--show-trace -L` 参数来获取详细的错误信息。举例如下：
+
 另外，如果你只是想尝试一下 Helix 的最新版本，再决定要不要真正地将它安装到系统里，有更简单的办法，一行命令就行：
 
 > 同样，想使用最新版本的话，源码编译基本是免不了的，这会需要一些时间。

docs/zh/nixos-with-flakes/other-useful-tips.md

@@ -1,5 +1,14 @@
 # NixOS 的其他实用技巧
 
+## 查看详细错误信息
+
+如果你在部署配置时遇到了任何错误，都可以尝试在 `nixos-rebuild` 命令后面添加 `--show-trace -L` 参数来获取详细的错误信息。举例如下：
+
+```bash
+cd /etc/nixos
+sudo nixos-rebuild switch --flake .#myhost --show-trace -L
+```
+
 ## 使用 Git 管理 NixOS 配置 {#git-manage-nixos-config}
 
 > 这里不介绍 Git 本身的使用，如果不熟悉 Git 的话，可以先找资料学习一下 Git.