From be7c236565ae981a5b0f5a952bfb8380418cea41 Mon Sep 17 00:00:00 2001
From: Valentin Gagarin <valentin.gagarin@tweag.io>
Date: Wed, 26 Apr 2023 15:37:08 +0200
Subject: move compatibility info to `nix profile` docs

---
 src/nix/profile.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

(limited to 'src/nix/profile.md')

diff --git a/src/nix/profile.md b/src/nix/profile.md
index 1c4e92ee4..ddbb1ba36 100644
--- a/src/nix/profile.md
+++ b/src/nix/profile.md
@@ -10,4 +10,36 @@ them to be rolled back easily.
 # Files
 
 )""
+
 #include "doc/files/user-profiles.md"
+
+R""(
+
+### Profile compatibility
+
+> **Warning**
+>
+> Once you have used [`nix profile`] you can no longer use [`nix-env`] without first deleting `$XDG_STATE_HOME/nix/profiles/profile`
+
+[`nix-env`]: @docroot@/command-ref/nix-env.md
+[`nix profile`]: @docroot@/command-ref/new-cli/nix3-profile.md
+
+Once you installed a package with [`nix profile`], you get the following error message when using [`nix-env`]:
+
+```console
+$ nix-env -f '<nixpkgs>' -iA 'hello'
+error: nix-env
+profile '/home/alice/.local/state/nix/profiles/profile' is incompatible with 'nix-env'; please use 'nix profile' instead
+```
+
+To migrate back to `nix-env` you can delete your current profile:
+
+> **Warning**
+>
+> This will delete packages that have been installed before, so you may want to back up this information before running the command.
+
+```console
+ $ rm -rf "${XDG_STATE_HOME-$HOME/.local/state}/nix/profiles/profile"
+```
+
+)""
-- 
cgit v1.2.3