Document --user-data-dir for VS Code instance isolation (#8996)

* Initial plan

* Document VS Code instance isolation with --user-data-dir

Co-authored-by: ntrogh <[email protected]>

* Address review feedback: update heading level, note format, and remove examples

Co-authored-by: ntrogh <[email protected]>

* Remove additional line about unexpected issues as requested

Co-authored-by: ntrogh <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: ntrogh <[email protected]>

Author: Copilot

docs/configure/command-line.md

@@ -124,7 +124,7 @@ There are several CLI options that help with reproducing errors and advanced set
 Argument|Description
 ------------------|-----------
 `--extensions-dir <dir>` | Set the root path for extensions.<br>Overridden in [Portable Mode](/docs/editor/portable.md) by the `data` folder.
-`--user-data-dir <dir>` | Specifies the directory that user data is kept in, useful when running as root.<br>Overridden in [Portable Mode](/docs/editor/portable.md) by the `data` folder.
+`--user-data-dir <dir>` | Specifies the directory that user data is kept in. Can be used to run multiple isolated instances of VS Code with separate environments, settings, and extensions. Also useful when running as root.<br>Overridden in [Portable Mode](/docs/editor/portable.md) by the `data` folder.
 `-s, --status` | Print process usage and diagnostics information.
 `-p, --performance` | Start with the **Developer: Startup Performance** command enabled.
 `--disable-gpu` | Disable GPU hardware acceleration.
@@ -135,6 +135,35 @@ Argument|Description
 `--add <dir>` | Add folder(s) to the last active window for a multi-root workspace.
 `--remove <dir>` | Remove folder(s) from the last active window for a multi-root workspace.
 
+## Isolating VS Code instances
+
+By default, VS Code instances share environment variables in the following way:
+
+* If this is the first VS Code instance, environment variables are inherited from the parent process.
+* If this is not the first VS Code instance, environment variables are inherited from the already running VS Code instance.
+
+This behavior can cause issues when you need different environment variables for different projects or build configurations. For example, if you're working on two projects that require different versions of Node.js or different `PATH` settings.
+
+To run VS Code instances with separate environment variables, use the `--user-data-dir` option to specify a unique user data directory for each instance:
+
+```bash
+# First instance with its own environment
+code ~/project1 --user-data-dir ~/vscode-data-project1
+
+# Second instance with different environment
+code ~/project2 --user-data-dir ~/vscode-data-project2
+```
+
+Each instance with a different `--user-data-dir` will maintain its own:
+
+* Environment variables
+* Settings and preferences
+* Installed extensions
+* UI state and layout
+
+> [!NOTE]
+> When using `--user-data-dir`, you'll need to reinstall extensions for each user data directory, as extensions are stored separately.
+
 ### Create remote tunnel
 
 VS Code integrates with other [remote environments](/docs/remote/remote-overview.md) to become even more powerful and flexible. Our goal is to provide a cohesive experience that allows you to manage both local and remote machines from one, unified CLI.

docs/terminal/advanced.md

@@ -176,6 +176,15 @@ When VS Code is opened, it launches a login shell environment in order to source
 
 This environment inheritance can be disabled on macOS and Linux via the `setting(terminal.integrated.inheritEnv)` setting.
 
+### Environment variables between VS Code instances
+
+When launching multiple VS Code instances, environment variables are shared between them:
+
+* The first VS Code instance inherits environment variables from the parent process (for example, the shell or application that launched VS Code).
+* Subsequent VS Code instances inherit environment variables from the first running VS Code instance, not from the parent process.
+
+To isolate environment variables between VS Code instances, use the [`--user-data-dir` command-line option](/docs/configure/command-line.md#isolating-vs-code-instances) to run each instance with a separate user data directory. This ensures that each instance maintains its own environment, settings, and extensions.
+
 ### Interaction with `$LANG`
 
 There is some special interaction with the `$LANG` environment variable, which determines how characters are presented in the terminal. This feature is configured with the `setting(terminal.integrated.detectLocale)` setting: