From 6b6c2769f441d557274dae93b72e215d3b787503 Mon Sep 17 00:00:00 2001
From: Hofer-Julian <30049909+Hofer-Julian@users.noreply.github.com>
Date: Thu, 17 Oct 2024 13:16:34 +0200
Subject: [PATCH] docs: document where `pixi-global.toml` can be found (#2304)

I also removed the note that the desing of global tools is still in
progress
---
 docs/features/global_tools.md | 36 ++++++++++++++++++++++++++++++-----
 1 file changed, 31 insertions(+), 5 deletions(-)

diff --git a/docs/features/global_tools.md b/docs/features/global_tools.md
index 11ca5cba5..f53feb1d5 100644
--- a/docs/features/global_tools.md
+++ b/docs/features/global_tools.md
@@ -3,15 +3,12 @@
 With `pixi global`, users can manage globally installed tools in a way that makes them available from any directory.
 This means that the pixi environment will be placed in a global location, and the tools will be exposed to the system `PATH`, allowing you to run them from the command line.
 
-!!! note
-    The design for global tools is still in progress, and the commands and behavior may change in future releases.
-    The proposal for the global tools feature can be found [here](../design_proposals/pixi_global_manifest.md).
-
 ## The Global Manifest
-Since `v0.33.0` pixi has a new manifest file that will be created in the global directory (default: `$HOME/.pixi/manifests/pixi-global.toml`).
+Since `v0.33.0` pixi has a new manifest file that will be created in the global directory.
 This file will contain the list of environments that are installed globally, their dependencies and exposed binaries.
 The manifest can be edited, synced, checked in to a version control system, and shared with others.
 
+
 A simple version looks like this:
 ```toml
 [envs.vim]
@@ -34,6 +31,35 @@ exposed = { python310 = "python" } # (3)!
 2. The exposed binaries are the ones that will be available in the system path. `vim` has multiple and all of them are exposed.
 3. Here python is exposed as `python310` to avoid conflicts with other python installations. You can give it any name you want.
 
+### Manifest locations
+
+The manifest can be found at the following locations depending on your operation system.
+
+=== "Linux"
+
+    | **Priority** | **Location**                                                           | **Comments**                                                                       |
+    |--------------|------------------------------------------------------------------------|------------------------------------------------------------------------------------|
+    | 1            | `$HOME/.pixi/manifests/pixi-global.toml`                               | User-specific manifest                                                             |
+    | 2            | `$PIXI_HOME/manifests/pixi-global.toml`                                | Global manifest in the user home directory. `PIXI_HOME` defaults to `~/.pixi`      |
+
+=== "macOS"
+
+    | **Priority** | **Location**                                                           | **Comments**                                                                       |
+    |--------------|------------------------------------------------------------------------|------------------------------------------------------------------------------------|
+    | 1            | `$HOME/.pixi/manifests/pixi-global.toml`                               | User-specific manifest                                                             |
+    | 2            | `$PIXI_HOME/manifests/pixi-global.toml`                                | Global manifest in the user home directory. `PIXI_HOME` defaults to `~/.pixi`      |
+
+=== "Windows"
+
+    | **Priority** | **Location**                                                           | **Comments**                                                                                   |
+    |--------------|------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
+    | 1            | `%USERPROFILE%\.pixi\manifests\pixi-global.toml`                       | User-specific manifest                                                                         |
+    | 2            | `$PIXI_HOME\manifests/pixi-global.toml`                                | Global manifest in the user home directory. `PIXI_HOME` defaults to `%USERPROFILE%/.pixi`      |
+
+!!! note
+    If multiple locations exist, the manifest with the highest priority will be used.
+
+
 ### Channels
 The channels are the conda channels that will be used to search for the packages.
 There is a priority to these, so the first one will have the highest priority, if a package is not found in that channel the next one will be used.